amsd-pipeline-shared 0.5.0 → 0.5.2

package/orchestrations/scripts/lib/halt-recovery.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# WHAT THE OPERATOR IS TOLD WHEN A STORY HALTS — AND WHETHER IT IS TRUE.
+#
+# This ran inside run-agent-orchestration.sh, which cannot be sourced without running the whole
+# pipeline, so the message an operator acts on had never been executed by a test.
+#
+# It matters because the message is a DIAGNOSIS. On a live run the writer burned 12 attempts and
+# this printed "recovery was NOT exhausted: 0 of 12 attempt(s) used — the story failed on a gate
+# verdict, not on running out of attempts", sending the reader to look for a gate verdict that was
+# not the cause. A confident wrong answer costs more than no answer.
+#
+# Expects its caller to provide: error, read_story_retry_count, story_ladder_exhausted, MAX_RETRIES.
+
+# _halt_recovery_state <story_id> — report the recovery state ACTUALLY observed for this story.
+#
+# The halt used to assert "failed after its retries and self-heal completed" and "recovery is
+# exhausted" unconditionally. Live metrolinx AMSD-2041, 2026-08-19: a gate failed one story at
+# attempt 2 of 12, the ladder had not left its first rung, and the writer was mid-way through
+# addressing the reviewer's findings — and the run reported exhaustion. That message is the
+# evidence an operator reads when deciding whether to retry, and it said the opposite of the truth.
+#
+# HALTING IS STILL THE MANDATE: let recovery run, then stop. What must not happen is CLAIMING
+# exhaustion without checking. story_ladder_exhausted() already existed and was already used
+# elsewhere in this file; the halt simply never asked it.
+_halt_recovery_state() {
+    local _story="${1:-}"
+    local _used _max="${MAX_RETRIES:-11}"
+    _used="$(read_story_retry_count "${LOG_DIR:-}" "$_story" 2>/dev/null || echo 0)"
+    case "$_used" in (''|*[!0-9]*) _used=0 ;; esac
+
+    # A COUNT NOBODY COULD READ IS NOT A COUNT OF ZERO.
+    #
+    # read_story_retry_count answers 0 both for "no attempts" and for "I cannot see the state" —
+    # an empty LOG_DIR, or a lane whose own LOG_DIR this scope never received. On a live run the
+    # writer burned 12 attempts and this reported "0 of 12 attempt(s) used, the story failed on a
+    # gate verdict", sending the reader after a verdict that was not the cause. A confident wrong
+    # diagnosis costs more than none, so an unreadable state says so — the same rule the gate
+    # verdicts follow, where an unreadable log is a warn and never a pass.
+    local _state_file=""
+    if [ -n "${LOG_DIR:-}" ]; then
+        _state_file="$(_story_retry_state_file "$LOG_DIR" "$_story" 2>/dev/null || echo '')"
+    fi
+    if [ -z "${LOG_DIR:-}" ] || [ ! -f "$_state_file" ]; then
+        error "[orch]   recovery state for '${_story}' could not be read${LOG_DIR:+ at ${LOG_DIR}}"
+        error "[orch]   How many attempts were used is UNKNOWN — do not read this as none. Check the"
+        error "[orch]   lane's own log directory before concluding a gate verdict stopped the story."
+        return 0
+    fi
+    if story_ladder_exhausted "${LOG_DIR:-}" "$_story" "$_max" 2>/dev/null; then
+        error "[orch]   recovery is exhausted for '${_story}' — ${_used} of $((_max + 1)) attempt(s) used and the model ladder reached its top rung."
+        error "[orch]   Another lane would reproduce the same failure at full ladder price."
+    else
+        error "[orch]   recovery was NOT exhausted for '${_story}': ${_used} of $((_max + 1)) attempt(s) used, ladder still below its top rung."
+        error "[orch]   The story failed on a gate verdict, not on running out of attempts — read the last gate message before assuming the work cannot converge."
+    fi
+}

package/orchestrations/scripts/lib/handlers/_read-input.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * A HANDLER EITHER READS ITS INPUT OR SAYS IT COULD NOT.
+ *
+ * The handlers in this directory are shelled out to for decisions — how many agents a roster holds,
+ * which verdicts a gate reached, what a package.json pins. They are handed whatever the filesystem
+ * holds at that moment, which includes a file a dead step never wrote, a half-written one, and a
+ * log line where JSON was expected.
+ *
+ * Driven against those inputs on 2026-08-31, ten threw a raw node stack and eight printed a
+ * confident value anyway. roster-size.js shows why the second is worse: its own header says it
+ * "guards the skip-the-mint path", and handed unparseable JSON it printed 0 and exited 0 — so a
+ * CORRUPT roster read exactly like an EMPTY one and the guard waved the run through.
+ *
+ * A stack trace is not a diagnosis and a default is not an answer. This gives one of two outcomes:
+ * the parsed value, or a stated refusal on stderr and a non-zero exit.
+ */
+const fs = require('fs');
+
+/**
+ * readJsonOrRefuse(file, what) -> parsed value, or exits non-zero having said why.
+ *
+ * `what` names the thing in the operator's terms — "the minted roster", "the AC gate results" —
+ * because "ENOENT" names a syscall and the reader has to work out the rest.
+ *
+ * An empty object or array is a REAL answer and passes through. Only json `null` is refused: every
+ * handler that took one went on to read a field from it and threw.
+ */
+function readJsonOrRefuse(file, what, opts) {
+  const name = what || 'its input';
+  if (!file) {
+    process.stderr.write(`[${scriptName()}] no path was given for ${name} — nothing to read\n`);
+    process.exit(2);
+  }
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    process.stderr.write(
+      `[${scriptName()}] could not read ${name} at ${file}: ${(e && e.message) || e}\n`
+      + '  This is not an empty result — nothing was read at all.\n');
+    process.exit(2);
+  }
+  if (!String(text).trim()) {
+    process.stderr.write(
+      `[${scriptName()}] ${name} at ${file} is EMPTY. An empty file is not an empty answer: the `
+      + 'step that writes it may have died before it wrote anything.\n');
+    process.exit(2);
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (e) {
+    process.stderr.write(
+      `[${scriptName()}] ${name} at ${file} is not valid JSON and could not be parsed: `
+      + `${(e && e.message) || e}\n`
+      + '  Returning a default here would be indistinguishable from a real answer.\n');
+    process.exit(2);
+  }
+  if (value === null) {
+    process.stderr.write(
+      `[${scriptName()}] ${name} at ${file} parsed to null — there are no fields to read from it.\n`);
+    process.exit(2);
+  }
+  // VALID JSON OF THE WRONG SHAPE is the second half of this class. `{}` where an array was
+  // expected produced "results.forEach is not a function" — a node internal thrown mid-run, naming
+  // neither the file that was wrong nor what it should have held. A handler that knows the shape it
+  // needs should say so, and be told plainly when it does not get it.
+  const want = opts && opts.expect;
+  if (want) {
+    const got = Array.isArray(value) ? 'array' : typeof value;
+    if (want !== got) {
+      process.stderr.write(
+        `[${scriptName()}] ${name} at ${file} is an ${got}, but this reads it as an ${want}. `
+        + 'The file parsed, so this is not a corruption — it is the wrong thing in the right place, '
+        + 'which usually means an earlier step wrote where it should not have.\n');
+      process.exit(2);
+    }
+  }
+  return value;
+}
+
+/** The handler doing the reading, so a message in a shell log says which program spoke. */
+function scriptName() {
+  try { return require('path').basename(process.argv[1] || 'handler'); } catch { return 'handler'; }
+}
+
+module.exports = { readJsonOrRefuse };

package/orchestrations/scripts/lib/handlers/carry-plan.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * carry-plan.js <lane-prd> <canonical-prd> — a lane's work copy carries the story's plan.
+ *
+ * A resumed lane works from a copy of its checkpoint PRD, written before the story had a plan
+ * (write-missing-plans.js writes it into the canonical PRD). Every step inside the lane reads PRD_FILE, so the
+ * run's plan is copied onto the lane's copy of each story — replacing an older one. The checkpoint itself is never edited.
+ */
+'use strict';
+const fs = require('fs');
+
+const [laneFile, canonicalFile] = process.argv.slice(2);
+try {
+  const lane = JSON.parse(fs.readFileSync(laneFile, 'utf8'));
+  const canonical = JSON.parse(fs.readFileSync(canonicalFile, 'utf8'));
+  let changed = false;
+  for (const s of lane.stories || []) {
+    if (!s) continue;
+    // ONE PLAN PER STORY: the run's. A lane copy's older plan is replaced (AMSD-2974, 2026-10-07: a checkpoint's
+    // older plan skipped the writer on a plan the run no longer held).
+    const c = (canonical.stories || []).find((x) => x && x.id === s.id);
+    if (c && c.overallPlan && JSON.stringify(c.overallPlan) !== JSON.stringify(s.overallPlan)) { s.overallPlan = c.overallPlan; changed = true; }
+  }
+  if (changed) fs.writeFileSync(laneFile, JSON.stringify(lane, null, 2));
+} catch { process.exit(0); }

package/orchestrations/scripts/lib/handlers/cl-entries.js

@@ -0,0 +1,10 @@
+    const p = require('./_read-input.js').readJsonOrRefuse(process.argv[2], "the run's codeline scope");
+    const dirs = p.project && p.project.outputDirs ? p.project.outputDirs : [];
+    if (dirs.length > 0) {
+      dirs.forEach(d => console.log(d.codeline + ':' + d.path));
+    } else {
+      const cl  = process.env.JIRA_DEFAULT_CODELINE || '';
+      const dir = p.project && p.project.outputDir ? p.project.outputDir : '';
+      if (cl && dir) console.log(cl + ':' + dir);
+    }
+  

package/orchestrations/scripts/lib/handlers/codeline-ecosystem.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * WHAT ECOSYSTEM A REPOSITORY IS, AND WHAT THAT IMPLIES.
+ *
+ * codeline-health.sh assesses every codeline before a run spends anything. Its header says it
+ * "knows no package manager, no test runner and no language" — and its body named package.json,
+ * node_modules and four npm lockfiles. A Rust, Python or Ruby codeline therefore declared nothing,
+ * had nothing checked, and was reported HEALTHY without ever being assessed. A free pass from the
+ * one gate that exists to stop a run before it pays for an unusable baseline.
+ *
+ * Every answer here comes from lib/ecosystem-registry.js, the one table. This file names no manifest, no
+ * lockfile and no package manager.
+ *
+ *   argv[2]  the repository
+ *   argv[3]  optional: an estate root, to resolve a dependency to a sibling repository
+ *
+ *   stdout   one JSON object:
+ *     stack           the ecosystem label, or "" when the repo declares none
+ *     manifest        the manifest file found, or ""
+ *     installDir      where this ecosystem vendors dependencies, or null if it vendors none
+ *     packageManager  decided by the lockfile present, or "" when none says
+ *     testCommand     what runs this project's own tests, or "" when it declares none
+ *     installCommand  what installs its dependencies, or "" when it vendors nothing in-repo
+ *     testFileCommand what runs JUST the files given in argv[4], or "" when this ecosystem cannot
+ *     declaredDeps    every dependency the manifest declares
+ *     declaredBins    the declared dependencies the repo's own scripts actually invoke
+ *     missingBins     of those, the ones not present in installDir
+ *     providers       { packageName: path } for sibling repositories in the estate
+ *
+ * A repo that declares NOTHING is not unhealthy — it has nothing to install. That is the caller's
+ * rule and this reports the facts for it to apply.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { allManifests, lockfileFor } = require('../ecosystem-registry.js');
+
+const repo = process.argv[2];
+if (!repo) {
+  process.stderr.write('[codeline-ecosystem] usage: <repo> [estate-root]\n');
+  process.exit(1);
+}
+// A REPOSITORY THAT IS NOT THERE IS NOT A REPOSITORY WITHOUT A MANIFEST.
+//
+// Handed a path that does not exist, this returned {"stack":"","manifest":"",...} — the same
+// answer it gives for a real checkout carrying no manifest of any known ecosystem. The caller
+// chooses install and test commands from that, so the two must not be one answer: "there is
+// nothing to detect here" and "I was pointed at nothing" lead to different actions.
+const _repoStat = (() => { try { return fs.statSync(repo); } catch { return null; } })();
+if (!_repoStat || !_repoStat.isDirectory()) {
+  process.stderr.write(
+    `[codeline-ecosystem] ${repo} is ${_repoStat ? 'not a directory' : 'not there'} — this is NOT `
+    + 'the same as a repository with no recognised manifest, and an empty ecosystem here would be '
+    + 'read as one. The caller picks install and test commands from this answer.\n');
+  process.exit(2);
+}
+
+const estate = process.argv[3] || '';
+// argv[4]: optional comma-separated test files, to be turned into a runnable command.
+
+const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } };
+
+/** The first ecosystem whose manifest this repository carries. */
+function ecosystemOf(root) {
+  for (const eco of allManifests()) {
+    if (fs.existsSync(path.join(root, eco.file))) return eco;
+  }
+  return null;
+}
+
+const eco = ecosystemOf(repo);
+const out = {
+  stack: '', manifest: '', installDir: null, packageManager: '', testCommand: '', buildCommand: '', testFileCommand: '',
+  installCommand: '', addCommand: '',
+  lockfile: '',
+  declaredBins: [], declaredDeps: [], missingBins: [], providers: {},
+};
+
+if (eco) {
+  out.stack = eco.stack;
+  out.manifest = eco.file;
+  out.installDir = eco.installDir || null;
+
+  // The package manager is what the LOCKFILE says. Unknown means we do not know how to install,
+  // so we do not pretend to — the caller declines rather than guessing a command.
+  out.lockfile = lockfileFor(eco, (f) => fs.existsSync(path.join(repo, f)));
+  out.packageManager = out.lockfile ? eco.lockfiles[out.lockfile] : '';
+  if (typeof eco.addCommand === 'function') {
+    try { out.addCommand = eco.addCommand(out.packageManager) || ''; } catch { out.addCommand = ''; }
+  }
+
+
+  const text = read(path.join(repo, eco.file));
+  if (text !== null) {
+    let deps = [];
+    try { deps = eco.deps(text) || []; } catch { deps = []; }
+
+    // ONLY THE TOOLING THE PROJECT ACTUALLY INVOKES: a declared dependency whose name appears in
+    // the repo's own scripts. That is the set whose absence means the project cannot run its own
+    // commands — the rest may be missing without stopping a gate.
+    let scripts = '';
+    try { scripts = Object.values(JSON.parse(text).scripts || {}).join(' '); } catch { scripts = ''; }
+    // EVERY DECLARED DEPENDENCY, not only the ones the scripts invoke. The mint needs the full
+    // list as evidence for an agent brief; declaredBins is the narrower "tooling this project
+    // actually runs" set and answers a different question.
+    out.declaredDeps = deps;
+
+    out.declaredBins = scripts
+      ? deps.filter((d) => new RegExp(`(^|[^\\w/@-])${d.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^\\w-]|$)`).test(scripts))
+      : [];
+
+    // WHAT COMMAND RUNS ITS TESTS, from the ecosystem rather than from a runner name. Empty
+    // means the project declares none — which the caller must read as "nothing to run", never as
+    // "the tests passed".
+    if (typeof eco.testCommand === 'function') {
+      try { out.testCommand = eco.testCommand(text, out.packageManager) || ''; } catch { out.testCommand = ''; }
+    }
+    // WHAT BUILDS IT, from the same registry: a sibling that consumes this repository builds against
+    // that output (lib/codeline-lanes.sh link_sibling_builds).
+    if (typeof eco.buildCommand === 'function') {
+      try { out.buildCommand = eco.buildCommand(text, out.packageManager) || ''; } catch { out.buildCommand = ''; }
+    }
+
+    // HOW TO RUN SPECIFIC TEST FILES, from the same registry. The bug-reproduction gate needs to
+    // execute one story's test, not the whole suite, and it used to probe for Node binaries by
+    // name and skip itself entirely on anything else.
+    if (typeof eco.testFileCommand === 'function') {
+      const wanted = (process.argv[4] || '').split(',').map((f) => f.trim()).filter(Boolean);
+      if (wanted.length) {
+        try { out.testFileCommand = eco.testFileCommand(out.testCommand, wanted) || ''; }
+        catch { out.testFileCommand = ''; }
+      }
+    }
+
+    if (typeof eco.installCommand === 'function') {
+      try { out.installCommand = eco.installCommand(out.packageManager) || ''; }
+      catch { out.installCommand = ''; }
+    }
+
+    if (out.installDir) {
+      out.missingBins = out.declaredBins.filter((b) => !fs.existsSync(path.join(repo, out.installDir, b)));
+    }
+  }
+}
+
+// Sibling repositories, by the name each one gives ITSELF. Nothing here knows a vendor, a scope or
+// a repository name — it reads the manifest's own `name` through the ecosystem that defines it.
+if (estate && fs.existsSync(estate)) {
+  for (const entry of fs.readdirSync(estate)) {
+    const dir = path.join(estate, entry);
+    try { if (!fs.statSync(dir).isDirectory()) continue; } catch { continue; }
+    const sibling = ecosystemOf(dir);
+    if (!sibling || typeof sibling.selfName !== 'function') continue;
+    const text = read(path.join(dir, sibling.file));
+    if (text === null) continue;
+    let name = '';
+    try { name = sibling.selfName(text); } catch { name = ''; }
+    if (name) out.providers[name] = dir;
+  }
+}
+
+process.stdout.write(`${JSON.stringify(out)}\n`);

package/orchestrations/scripts/lib/handlers/codeline-manifests.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * codeline-manifests.js — WHAT THIS CODELINE DECLARES ABOUT ITSELF, or nothing at all.
+ *
+ * run-agent-orchestration.sh wrote three .epam/ manifests into every codeline worktree that lacked
+ * them, from heredocs asserting — of a repository it had never inspected — that its manifest is
+ * package.json, its sources are .ts/.tsx/.js, its vendor directory is node_modules, its install
+ * command is npm, and that it must carry typescript, @types/node, vitest and tsx.
+ *
+ * THAT IS NOT AN ASSUMPTION, IT IS A FABRICATION. Seventeen scripts read dependency-check.json as
+ * the codeline's OWN declaration; it is the ground truth every generic component consults. Writing
+ * it from a template defeats that genericity at the source — a Python repository is handed a
+ * document saying it is TypeScript, and everything downstream then behaves "generically" against
+ * a lie, in client-repo space, with facts nobody detected.
+ *
+ * Here the manifests are ASSEMBLED from the provider whose manifest the repository actually
+ * carries. The registry answers what it can (manifest file, vendor dirs, add-command); the
+ * provider supplies the rest under `codelineManifests`.
+ *
+ *   node codeline-manifests.js <codelineRoot>
+ *
+ * stdout  a JSON object keyed by filename, ready to be written into .epam/
+ * exit 0  a declaration was produced
+ * exit 1  NO provider recognises this codeline, or the one that does declares nothing — nothing is
+ *         printed. The caller must report that and move on, never substitute a default. An
+ *         undeclared codeline is a state to surface, not one to invent an answer for.
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const { allManifests, lockfileFor } = require('../ecosystem-registry.js');
+
+function manifestNames(eco) {
+  return [eco.file, ...(Array.isArray(eco.alsoMatches) ? eco.alsoMatches : [])];
+}
+
+/** The provider whose manifest this repository actually carries, in declared precedence order. */
+function resolveEcosystem(root) {
+  for (const eco of allManifests()) {
+    const present = manifestNames(eco).find((n) => {
+      try { return fs.existsSync(path.join(root, n)); } catch { return false; }
+    });
+    if (present) return { eco, present };
+  }
+  return null;
+}
+
+/** The package manager the codeline's lockfile names, per the provider's own lockfile table; '' when none. */
+function packageManagerFor(eco, root) {
+  const lock = lockfileFor(eco, (f) => {
+    try { return fs.existsSync(path.join(root, f)); } catch { return false; }
+  });
+  return (lock && (eco.lockfiles || {})[lock]) || '';
+}
+
+function build(root) {
+  const hit = resolveEcosystem(root);
+  if (!hit) return null;
+  const { eco, present } = hit;
+
+  const declared = eco.codelineManifests || {};
+
+  // The vendored tree, from what the ecosystem says it vendors. `installDir` is the one that gets
+  // populated; `artifactDirs` is the wider set it leaves behind.
+  const vendorDirs = [...new Set([
+    ...(eco.installDir ? [eco.installDir] : []),
+    ...(Array.isArray(eco.artifactDirs) ? eco.artifactDirs : []),
+  ])];
+
+  // THE ADD COMMAND, not the install command. `installCommand` provisions what the manifest already
+  // declares and cannot add anything; the engine's heredoc wrote "npm install --save-dev {package}"
+  // beside the provider's own addCommand — two spellings of one fact.
+  const manager = packageManagerFor(eco, root);
+  let addCommand = '';
+  if (typeof eco.addCommand === 'function') {
+    try { addCommand = String(eco.addCommand(manager) || ''); } catch { addCommand = ''; }
+  }
+
+  // HOW THE ENVIRONMENT IS PROVISIONED, AND WHERE COMMANDS RUN. Two more facts the plug-in
+  // declares and the engine only executes. Until 2026-09-16 the manifest carried the ADD command
+  // alone, and the engine provisioned a worktree by deleting `{package}` from it and running the
+  // remainder — a rule true of one ecosystem's package manager and of no other: a Python worktree
+  // got `pip install` with no arguments, no interpreter, and every test exited 2.
+  let provisionCommand = '';
+  if (typeof eco.installCommand === 'function') {
+    try { provisionCommand = String(eco.installCommand(manager) || ''); } catch { provisionCommand = ''; }
+  }
+  const runEnvironment = (eco.runEnvironment && typeof eco.runEnvironment === 'object') ? eco.runEnvironment : null;
+  // Files the ecosystem says are complete when empty (a package marker), by basename.
+  const emptyDeliverables = Array.isArray(eco.emptyDeliverables) ? eco.emptyDeliverables.filter((x) => typeof x === 'string' && x) : [];
+
+  // THE RUNTIME'S BUILT-IN MODULES, ASKED OF THE RUNTIME. An ecosystem declares HOW to ask
+  // (builtinModulesCommand); the answer is carried as data (builtinModules) so the scan plug-in
+  // — which must never run a process — reads a list. Python's `__future__` was reported as an
+  // undeclared import and failed a story through the ladder (regintel 20260916T200108Z).
+  let builtinModules = [];
+  const bmc = declared.dependencyCheck && typeof declared.dependencyCheck.builtinModulesCommand === 'string'
+    ? declared.dependencyCheck.builtinModulesCommand.trim() : '';
+  if (bmc) {
+    try {
+      builtinModules = require('node:child_process').execSync(bmc, { encoding: 'utf8', timeout: 20000, stdio: ['ignore', 'pipe', 'ignore'] })
+        .split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    } catch { builtinModules = []; }
+  }
+
+  const dependencyCheck = {
+    manifestFile: present,
+    ...(declared.dependencyCheck || {}),
+    ...(builtinModules.length ? { builtinModules } : {}),
+    vendorDirs,
+    ...(addCommand ? { installCommand: addCommand } : {}),
+    ...(provisionCommand ? { provisionCommand } : {}),
+    ...(runEnvironment ? { runEnvironment } : {}),
+    ...(emptyDeliverables.length ? { emptyDeliverables } : {}),
+  };
+
+  const out = { 'dependency-check.json': dependencyCheck };
+  if (declared.contractGeneration) out['contract-generation.json'] = declared.contractGeneration;
+  if (declared.knownFixes) out['known-fixes.json'] = declared.knownFixes;
+
+  // A provider that supplies nothing beyond its own identity has not declared how this codeline is
+  // checked. Emitting a near-empty dependency-check.json would read downstream as a real
+  // declaration, which is the defect this file exists to remove.
+  if (!declared.dependencyCheck) return null;
+
+  return out;
+}
+
+function main() {
+  const root = process.argv[2];
+  if (!root) {
+    process.stderr.write('[codeline-manifests] usage: <codelineRoot>\n');
+    return 2;
+  }
+  const out = build(root);
+  if (!out) {
+    process.stderr.write(
+      `[codeline-manifests] no provider declares how ${root} is checked — writing nothing. `
+      + 'Its ecosystem must declare this, or supply a provider that does.\n');
+    return 1;
+  }
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  return 0;
+}
+
+if (require.main === module) process.exit(main());
+module.exports = { build, resolveEcosystem, packageManagerFor };

package/orchestrations/scripts/lib/handlers/filtered-prd.js

@@ -0,0 +1,85 @@
+      const fs  = require('fs');
+      const prd = require('./_read-input.js').readJsonOrRefuse(process.argv[2], 'the PRD', { expect: 'object' });
+      const cl  = process.argv[4], dcl = process.env.JIRA_DEFAULT_CODELINE||'';
+      // A story may SPAN codelines. codelines[] is authoritative when present:
+      // the story stays whole and participates in each lane's execution, rather
+      // than being partitioned into exactly one. Without this it matches no
+      // partition, appears in zero filtered PRDs, and is silently dropped from
+      // the run — which is how a [GO, UP, MX] ticket reached ingest and died.
+      // The top-level shape is checked on read; a PRD that parsed but carries no stories array
+      // still reaches here, and `.filter` on undefined is a node internal thrown mid-run.
+      const stories = (prd.stories || []).filter(s =>
+        (Array.isArray(s.codelines) && s.codelines.length
+          ? s.codelines.includes(cl)
+          : (s.codeline === cl || (!s.codeline && cl === dcl)))
+      // THIS LANE'S PRD SAYS WHICH LANE IT IS.
+      //
+      // Stories were copied through unchanged, so a story spanning three codelines carried
+      // its PRIMARY codeline into all three lane PRDs. Every consumer reading the singular
+      // field then got the same answer everywhere: the detective resolved the first lane's
+      // investigator in all three lanes and investigated two repositories with a brief written
+      // for a different one. agentRole had the identical defect, and project.outputDir vs
+      // outputDirs a third instance.
+      //
+      // Fixed HERE rather than in each reader. A lane's PRD describing a different lane is the
+      // lie; once it tells the truth, every consumer — the detective, the guards, the manifest,
+      // whatever is added next — is correct without knowing lanes exist. codelines[] is left
+      // intact, so nothing loses the knowledge that the story spans more than this one.
+      // THIS LANE'S CRITERIA, NOT THE UNION.
+      //
+      // verificationCriteria / fixSiteAnalysis on canonical are the UNION across every lane —
+      // that is what canonical is for. Copying them through means a lane is handed other
+      // codelines' criteria, describing files that do not exist in its checkout.
+      //
+      // On a first run the spec pass overwrote them before anything read them, so it never
+      // showed. On a RESUME the spec pass is skipped — the whole point of resuming — so the
+      // lane keeps the union, its writer and gates verify against it, and
+      // mergeLaneIntoCanonical then faithfully records the union as THIS LANE'S OWN criteria.
+      // Live 2026-08-09: four killed runs turned gotransit's 4 criteria into all 14, and 13 fix
+      // sites into 22, compounding on every kill.
+      //
+      // Same rule as `codeline` above, and for the same reason: a lane's PRD states that lane's
+      // truth. Falls back to the flat list when there is no entry for this codeline (a first
+      // run, or a lane added later) — never to nothing, which would hand a writer an empty
+      // plan. An explicitly EMPTY entry is honoured, because 'this lane found nothing to
+      // verify' is a real state and differs from 'this lane has not run'.
+      //
+      // No double quotes anywhere in this block, comments included: the node script is passed
+      // inside a double-quoted shell string, so one would end it and bash would execute the
+      // JavaScript that follows.
+      ).map(s => {
+        const _scoped = (flat, perCl) =>
+          (perCl && Object.prototype.hasOwnProperty.call(perCl, cl)) ? perCl[cl] : flat;
+        const _ownText = (s.specTextPerCodeline && s.specTextPerCodeline[cl]) || null;
+        return {
+          ...s,
+          // THIS LANE'S OWN SPEC TEXT, OR THE TICKET'S - never another lane's rewrite (story-merge.js).
+          ...(_ownText ? { title: _ownText.title, description: _ownText.description } : {}),
+          codeline: cl,
+          verificationCriteria: _scoped(s.verificationCriteria, s.verificationCriteriaPerCodeline),
+          // A LANE NEVER INHERITS ANOTHER CODELINE'S FIX SITES. With no entry of its own yet, the
+          // fallback keeps only findings tagged with this codeline: the next lane of a spanning
+          // story was handed the first lane's files, which do not exist in its checkout (AMSD-2974,
+          // 2026-10-01). Findings carry their codeline once pooled.
+          fixSiteAnalysis: (s.fixSiteAnalysisPerCodeline && Object.prototype.hasOwnProperty.call(s.fixSiteAnalysisPerCodeline, cl))
+            ? s.fixSiteAnalysisPerCodeline[cl]
+            : (Array.isArray(s.codelines) && s.codelines.length > 1 && Array.isArray(s.fixSiteAnalysis)
+              ? s.fixSiteAnalysis.filter(f => f && f.codeline === cl)
+              : s.fixSiteAnalysis),
+        };
+      });
+      const ids = new Set(stories.map(s => s.id));
+      const order = {};
+      for (const [phase, list] of Object.entries(prd.implementationOrder||{})) {
+        const f = (list||[]).filter(id => ids.has(id));
+        if (f.length > 0) order[phase] = f;
+      }
+      if (Object.keys(order).length === 0) order.core = stories.map(s => s.id);
+      const out = {...prd, stories, implementationOrder: order};
+      if (prd.project && prd.project.outputDirs) {
+        const d = prd.project.outputDirs.find(d => d.codeline === cl);
+        if (d) out.project = {...prd.project, outputDir: d.path};
+      }
+      fs.writeFileSync(process.argv[3], JSON.stringify(out, null, 2));
+      console.log(stories.length);
+    

package/orchestrations/scripts/lib/handlers/merge-lane-into-canonical.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * MERGE ONE LANE'S STORY STATE BACK INTO THE CANONICAL PRD.
+ *
+ * Lanes of a spanning story run in parallel and each writes only its own filtered PRD. The merges
+ * happen afterwards, one at a time, here — concurrent merges into the same file would clobber
+ * each other.
+ *
+ * Lifted out of run-agent-orchestration.sh on 2026-08-16, where it was a `node -e "..."` string
+ * that interpolated four shell values directly into its own source. A codeline name or path
+ * containing a quote was a syntax error in a language the author was not writing.
+ *
+ * Generic: every input is an argument, and the rule holds for any project and any stack.
+ *
+ *   argv[2]  SCRIPT_DIR — where lib/story-merge.js lives
+ *   argv[3]  the canonical PRD, read and written in place
+ *   argv[4]  this lane's filtered PRD
+ *   argv[5]  the codeline name this lane ran as
+ *
+ * Exits non-zero on any failure. The caller distinguishes that from success and says so: a failed
+ * merge silently discards a lane's entire outcome — status, criteria and all.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const [, , scriptDir, canonicalPath, updatedPath, codeline] = process.argv;
+if (!scriptDir || !canonicalPath || !updatedPath || !codeline) {
+  process.stderr.write('[merge-lane-into-canonical] usage: <script-dir> <canonical-prd> <lane-prd> <codeline>\n');
+  process.exit(1);
+}
+
+const { mergeLaneIntoCanonical } = require(path.join(scriptDir, 'lib/story-merge.js'));
+
+const canonical = JSON.parse(fs.readFileSync(canonicalPath, 'utf8'));
+const updated = JSON.parse(fs.readFileSync(updatedPath, 'utf8'));
+mergeLaneIntoCanonical({ canonical, updated, codeline });
+fs.writeFileSync(canonicalPath, JSON.stringify(canonical, null, 2));

package/orchestrations/scripts/lib/handlers/package-engines-node.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * THE NODE VERSION A package.json REQUIRES, IF IT SAYS.
+ *
+ * Read before choosing an interpreter: a project that declares an engines.node range gets that
+ * version resolved through fnm rather than whatever `node` happens to be on PATH.
+ *
+ *   argv[2]  a package.json
+ *   stdout   the engines.node value, or empty when there is none
+ *
+ * Empty is the honest answer for "no requirement declared", and the caller reads it that way —
+ * it falls back to detection. An unreadable or absent file is the same answer for the same
+ * reason: it declares no requirement. This is the one place where quiet is correct, because the
+ * caller has a real fallback and the value is advisory.
+ *
+ * Lifted out of run-agent-orchestration.sh on 2026-08-16.
+ */
+'use strict';
+
+try {
+  const p = require(require('path').resolve(process.argv[2]));
+  process.stdout.write((p.engines && p.engines.node) || '');
+} catch {
+  process.stdout.write('');
+}