amsd-pipeline-workflow 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# amsd-pipeline-workflow
 
-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 driven as Claude workflows. It runs **against an installed AMSD pipeline** (it calls the pipeline's
+own scripts) and is installed by the pipeline's installer.
+
+## Install
+
+```bash
+npx amsd-pipeline@<version> --dest <dir> --ref v<version> --no-docker --workflows
+```
+
+`--workflows` installs the `amsd-pipeline-workflow` version the pipeline release pins
+(`orchestrations/config/claude-workflows.json`) into `<dir>/claude-workflows/`. `--workflows <file.tgz>` installs a
+local package instead (for testing a build before it is published). `--check` verifies it; `--uninstall` removes it.
+
+Needs: Node 20+, the `claude` CLI, `unshare` (util-linux) and `systemd-run --user` (the memory bound, `bin/bounded`).
+
+## Run
+
+```bash
+<dir>/claude-workflows/bin/amsd-pipeline-workflow.js run --project <p> --run <id> --out <run dir> --codeline-map <lane=copy> ...
+```
+
+`--install` defaults to the install it was installed into. The arguments are `driver/run.js`'s (see its header).
+Langfuse tracing follows the install's own settings (`LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`): each agent call is
+sent as one generation through the pipeline's own emitter.
+
+## Version
+
+`amsd-pipeline-workflow version`. `package.json` `amsdPipeline.tested` names the pipeline release it was tested against.

package/bin/amsd-pipeline-workflow.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+// amsd-pipeline-workflow — the AMSD pipeline as Claude workflows. Installed by the pipeline's own installer
+// (install.sh --workflows) into <install>/claude-workflows/, which writes install.json there naming the install.
+//   amsd-pipeline-workflow run <driver/run.js arguments>   — --install defaults to the install this was installed into
+//   amsd-pipeline-workflow version
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const [cmd, ...rest] = process.argv.slice(2);
+if (cmd === 'version') { process.stdout.write(`${require(path.join(ROOT, 'package.json')).version}\n`); process.exit(0); }
+if (cmd !== 'run') { process.stderr.write('usage: amsd-pipeline-workflow run <driver arguments> | version\n'); process.exit(64); }
+const args = [...rest];
+const linked = path.join(ROOT, 'install.json');
+if (!args.includes('--install') && fs.existsSync(linked)) args.unshift('--install', JSON.parse(fs.readFileSync(linked, 'utf8')).install);
+const r = spawnSync(process.execPath, [path.join(ROOT, 'driver', 'run.js'), ...args], { stdio: 'inherit' });
+process.exit(r.status === null ? 1 : r.status);

package/bin/bounded

@@ -0,0 +1,26 @@
+#!/bin/bash
+# bounded [--want <MB>] -- <command...>
+#
+# The ONLY sanctioned way to launch anything heavy from a Claude session on this host.
+# The cap is derived from what the HOST can spare right now, never from what the job wants:
+#   cap = min(want, available - RESERVE)   and the job is refused outright if cap < FLOOR.
+# Two WSL restarts on 2026-09-11 came from MemoryMax values (12G, 6G) chosen against a 13G host
+# that already held ~6G. A cap the host cannot honour is not a cap.
+RESERVE_MB=${BOUNDED_RESERVE_MB:-3072}   # always leave the host this much
+FLOOR_MB=${BOUNDED_FLOOR_MB:-1536}       # below this the job does not run
+WANT_MB=4096
+if [ "${1:-}" = "--want" ]; then WANT_MB="$2"; shift 2; fi
+[ "${1:-}" = "--" ] && shift
+[ $# -gt 0 ] || { echo "bounded: no command" >&2; exit 64; }
+
+AVAIL_MB=$(awk '/MemAvailable/ {print int($2/1024)}' /proc/meminfo)
+HEADROOM_MB=$(( AVAIL_MB - RESERVE_MB ))
+if [ "$HEADROOM_MB" -lt "$FLOOR_MB" ]; then
+  echo "bounded: REFUSED — host has ${AVAIL_MB}MB available, reserve ${RESERVE_MB}MB leaves ${HEADROOM_MB}MB, floor is ${FLOOR_MB}MB." >&2
+  echo "bounded: free memory (stop stacks / batch smaller) before running this." >&2
+  exit 75
+fi
+CAP_MB=$HEADROOM_MB
+[ "$CAP_MB" -gt "$WANT_MB" ] && CAP_MB=$WANT_MB
+echo "bounded: cap=${CAP_MB}MB (host available ${AVAIL_MB}MB, reserve ${RESERVE_MB}MB, wanted ${WANT_MB}MB)" >&2
+exec systemd-run --user --scope --quiet -p MemoryMax="${CAP_MB}M" -p MemorySwapMax=0 "$@"

package/driver/assess-step.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+'use strict';
+// THE PHASE ASSESSMENT'S STEP RUNNER HOOK (driver/generate-assess.js): on its structured answer, run the assessment round
+// (hooks/assess-round.sh start, or answer --failed when the team lead's call got no answer) and put its result in the answer.
+//   assess-step.js --pipeline <assess-pipeline.json> --mode start|fail   (stdin: the PreToolUse hook's JSON)
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const a = process.argv.slice(2); const arg = (n) => a[a.indexOf(`--${n}`) + 1];
+let input = {}; try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { /* nothing */ }
+if (input.tool_name !== 'StructuredOutput') process.exit(0);
+const round = path.join(__dirname, '..', 'hooks', 'assess-round.sh');
+const r = spawnSync('bash', [round, ...(arg('mode') === 'start' ? ['start', arg('pipeline')] : ['answer', arg('pipeline'), '--failed'])], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+let result; try { result = JSON.parse(String(r.stdout).trim().split('\n').pop()); } catch { result = { error: true, reason: (r.stderr || `exit ${r.status}`).slice(-400) }; }
+process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', updatedInput: { ...(input.tool_input || {}), result } } })}\n`);

package/driver/bash.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# ONE OF THE PIPELINE'S OWN BASH FUNCTIONS, CALLED UNCHANGED in the run's environment. No AI.
+#   bash.sh <env.json> <function> [args...]      (stdout and the exit code are the function's)
+# Loads the libraries run-agent-orchestration.sh loads for the lane loop (RAO:144–222, 409, 497–504, 634, 769–775), as
+# the orchestrator runs them: `set -e` off here because each call's status is the caller's to judge, no `set -u`, no
+# pipefail (RAO:75). The pipeline's log lines go to stderr; stdout carries only what the function prints.
+ENVF="${1:?env.json}"; shift
+eval "$(jq -r 'to_entries[] | select(.key | test("^[A-Za-z_][A-Za-z0-9_]*$")) | "export \(.key)=\(.value | @sh)"' "$ENVF")" || exit 90
+set +u +o pipefail
+RED='' GREEN='' YELLOW='' BLUE='' CYAN='' MAGENTA='' WHITE='' NC=''
+for _l in env-file jq-vals orch-common flags git-ops prd-state story-retry-state run-checkpoint checkpoints prd-integrity \
+          story-guards story-outputs codeline-lanes control-plane halt-recovery cost-ledger phase-exit resume-semantics \
+          render-engine-prompt plan-of-record before-the-writer run-modes orchestration-resume mint-and-spec qa-gate-evidence; do
+    # shellcheck source=/dev/null
+    [ -f "$SCRIPT_DIR/lib/$_l.sh" ] && { . "$SCRIPT_DIR/lib/$_l.sh" >/dev/null 2>&1 || { echo "lib/$_l.sh did not load" >&2; exit 91; }; }
+done
+declare -F log >/dev/null || log() { echo "$*" >&2; }
+declare -F info >/dev/null || info() { echo "[INFO] $*" >&2; }
+declare -F warning >/dev/null || warning() { echo "[WARNING] $*" >&2; }
+declare -F error >/dev/null || error() { echo "[ERROR] $*" >&2; }
+declare -F success >/dev/null || success() { echo "$*" >&2; }
+declare -F step_emit >/dev/null || step_emit() { :; }
+"$@"; _rc=$?
+# BASH_CALL_ENV_OUT: what the function exported (apply_resume_if_requested, _read_estimation_manifest), as JSON
+[ -n "${BASH_CALL_ENV_OUT:-}" ] && "$NODE_BIN" -e 'require("fs").writeFileSync(process.argv[1], JSON.stringify(process.env))' "$BASH_CALL_ENV_OUT"
+exit "$_rc"

package/driver/block-cap.js

@@ -0,0 +1,26 @@
+'use strict';
+// THE SAME GATE BLOCKING THE SAME STORY, AGAIN AND AGAIN, STOPS THE PHASE (operator, 2026-10-16: "Stop after a few
+// retries"). A recorded difference from the pipeline (backlog B39): its lane loop retries an exit-2 phase while HEAD moves,
+// and every Writer run moves it, so a story a gate keeps blocking retries forever. Here a phase stops — failed, naming
+// the gate — when its last BLOCK_CAP runs ended in the same block of the same story.
+const BLOCK_CAP = 3;
+
+/** What blocked a Writer run: the story and the gate (the reason up to its detail), or null when nothing blocked. */
+function signature(story, res) {
+  if (!res || res.status !== 'blocked') return null;
+  return `${story}|${String(res.reason || '').split(' — ')[0]}`;
+}
+
+/** A tracker for one phase's runs: note(sig) after each run; stuck() when the last BLOCK_CAP runs share one block. */
+function tracker() {
+  const seen = [];
+  return {
+    note(sig) { seen.push(sig || null); },
+    stuck() {
+      const last = seen.slice(-BLOCK_CAP);
+      return last.length === BLOCK_CAP && last[0] !== null && last.every((x) => x === last[0]) ? last[0] : null;
+    },
+  };
+}
+
+module.exports = { BLOCK_CAP, signature, tracker };

package/driver/bridge-hook.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+// THE BRIDGE'S ANSWER, JUDGED AS _run_codeline_bridge JUDGES IT (lib/codeline-lanes.sh :486–507) — a PreToolUse hook on
+// the codeline-bridge-agent's StructuredOutput. No AI.
+//   bridge-hook.js --bridge <bridge.json> --attempt N --last 0|1      (stdin: the hook's JSON)
+// The contract is the file the agent wrote; when it wrote none, its reply (`contract`) is the contract (:491–493). The
+// verdict and, on failure, which correction the next attempt carries go back in the answer as `result`. Before the next
+// attempt the call site removes the file (:487), so a failed attempt's file is removed here.
+const fs = require('fs');
+function args(argv) { const a = {}; for (let i = 0; i < argv.length; i += 2) a[argv[i].replace(/^--/, '')] = argv[i + 1]; return a; }
+const a = args(process.argv.slice(2));
+let input = {}; try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch { /* nothing */ }
+if (input.tool_name && input.tool_name !== 'StructuredOutput') process.exit(0);
+const ans = input.tool_input || {};
+const b = JSON.parse(fs.readFileSync(a.bridge, 'utf8'));
+const size = () => { try { return fs.statSync(b.bridgeOut).size; } catch { return -1; } };
+if (size() <= 0 && typeof ans.contract === 'string' && ans.contract.trim()) fs.writeFileSync(b.bridgeOut, ans.contract);
+const s = size();
+const result = s > 0 ? { ok: true } : { ok: false, why: s === 0 ? 'empty' : 'missing' };
+if (!result.ok) fs.rmSync(b.bridgeOut, { force: true });
+process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', updatedInput: { ...ans, result } } })}\n`);

package/driver/env.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# THE RUN'S ENVIRONMENT — what orchestrate.sh / run-agent-orchestration.sh export before `_run_jira_pipeline` and
+# `_run_codeline_loop` run (the parent process, not a lane). Prints it as one JSON object. No AI.
+#   env.sh <install> <project> <run-id> <run-dir> <set>
+# The project's own declarations come from its own loader (lib/env-file.sh load_project_env), over the launch settings
+# already in the environment (a set key is never overwritten — the loader's rule). Everything the run writes is under
+# <run-dir>: the project copy the run works in (EPAM_PROJECT_CONFIG_DIR, written by the driver), its log folder (LOG_DIR),
+# the canonical PRD (PRD_FILE), and every pipeline write path the parent exports (RAO:470–492).
+set -uo pipefail
+INSTALL="$1" PROJECT="$2" RUN="$3" RD="$4" SET="${5:-claude}"
+ORCH="$INSTALL/orchestrations"
+export SCRIPT_DIR="$ORCH/scripts" AUTOMATION_DIR="$ORCH" NODE_BIN="${NODE_BIN:-$(command -v node)}" EPAM_PROVIDER_SET="$SET"
+export EPAM_PROJECT_CONFIG_DIR="$RD/project"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/env-file.sh" && load_project_env "$EPAM_PROJECT_CONFIG_DIR" >/dev/null 2>&1 || { echo "project env did not load" >&2; exit 1; }
+export ORCH_RUN_ID="$RUN" PRD_FILE="$RD/prd.json" MAIN_PRD_FILE="$RD/prd.json" LOG_DIR="$RD/logs"
+export AGENTS_DIR="$ORCH/agents" EPAM_AGENTS_DIR="$ORCH/agents" AGENT_IO_DIR="$RD/logs/agent-io" TMPDIR="$RD/tmp"
+export MONITOR_FILE="$RD/logs/agent-status.json" ACTIVITY_FILE="$RD/logs/agent-activity.jsonl" MESSAGES_JSONL="$RD/logs/agent-messages.jsonl"
+export PHASE_COST_FILE="$RD/logs/phase-cost.jsonl" REVIEW_LOG="$RD/logs/code-reviews.jsonl" GATE_LOG="$RD/logs/phase-gates.jsonl"
+export COST_LOG="$RD/logs/phase-cost.jsonl" MESSAGES_DIR="$RD/logs/messages" EPAM_AGENT_REPLY_LOG_DIR="$RD/agent-replies"
+mkdir -p "$LOG_DIR" "$TMPDIR" "$EPAM_AGENT_REPLY_LOG_DIR"
+"$NODE_BIN" -e 'process.stdout.write(JSON.stringify(process.env))'

package/driver/generate-assess.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+// STEPS 18 AND 24, THE PHASE SKILL ASSESSMENT (feature skill-assessment, decision 43; run-agent-orchestration.sh:3340–3358,
+// :4318–4337) AS A NATIVE WORKFLOW the driver runs at phase level: the pipeline's own run_phase_assessment, run unchanged by
+// hooks/assess-round.sh, its call to the team lead answered by this workflow's agent through the replay runner
+// (hooks/replay-lib.sh); a retry it climbs to the next model for is asked on that model.
+//   node driver/generate-assess.js --install <dir> --codeline <copy> --out <dir> --label <step-18|step-24> [--set claude|codemie]
+//        --env <the lane's environment, JSON>
+// Writes only under --out. No AI.
+const fs = require('fs');
+const path = require('path');
+const agents = require('../generator/agents.js');
+
+function args(argv) { const a = {}; for (let i = 0; i < argv.length; i += 1) { if (argv[i].startsWith('--')) { a[argv[i].slice(2)] = argv[i + 1]; i += 1; } } return a; }
+const q = (x) => `'${String(x).replace(/'/g, "'\\''")}'`;
+
+function main(a) {
+  const env = JSON.parse(a.env || '{}');
+  const orch = path.join(a.install, 'orchestrations');
+  const out = path.resolve(a.out); fs.mkdirSync(out, { recursive: true });
+  const envFile = path.join(out, 'env.json'); fs.writeFileSync(envFile, JSON.stringify(env));
+  const pj = path.join(out, 'assess-pipeline.json');
+  fs.writeFileSync(pj, JSON.stringify({ state: path.join(out, 'state'), env: envFile, step: 'post', label: a.label || 'post' }));
+  const projectDir = env.EPAM_PROJECT_CONFIG_DIR;
+  const art = { orch, projectDir, checkpoint: projectDir, scripts: path.join(orch, 'scripts'), agentsDir: path.join(orch, 'agents'),
+    registry: path.join(orch, 'agents', 'invocation-profiles.json'), set: a.set || 'claude' };
+  const d = agents.definitionFor(art, 'team-lead-agent', path.resolve(a.codeline), fs.mkdtempSync(path.join(out, 'scratch-')), {});
+  const hook = (cmd) => ({ PreToolUse: [{ matcher: 'StructuredOutput', hooks: [{ type: 'command', command: cmd.map(q).join(' ') }] }] });
+  const step = (mode) => ({ description: `Runs the phase skill assessment's ${mode} step (its hook decides).`, model: d.frontmatter.model, maxTurns: 3, tools: [],
+    omitClaudeMd: true, hooks: hook([process.execPath, path.join(__dirname, 'assess-step.js'), '--pipeline', pj, '--mode', mode]),
+    prompt: 'Reply at once by giving your structured answer {"done": true}. Do nothing else: a hook runs the step, and its result is the answer.' });
+  const defs = {
+    'assess-start': step('start'), 'assess-fail': step('fail'),
+    'assess-team-lead': { ...d.frontmatter, name: undefined, description: `${d.frontmatter.description} Phase assessment (${a.label}).`,
+      hooks: hook([process.execPath, path.join(__dirname, '..', 'hooks', 'replay-answer.js'), 'answer', '--round', 'assess-round.sh', '--pipeline', pj]),
+      prompt: d.body.trim() },
+  };
+  delete defs['assess-team-lead'].name;
+  fs.writeFileSync(path.join(out, 'agents-assess.json'), JSON.stringify(defs, null, 2));
+  fs.mkdirSync(path.join(out, 'workflows'), { recursive: true });
+  fs.writeFileSync(path.join(out, 'workflows', 'assess.js'), emit({ label: a.label || 'post' }));
+  return { pj };
+}
+
+function emit(plan) {
+  return `export const meta = {
+  name: 'assess',
+  description: 'The phase skill assessment: the team lead reads the phase\\'s cost records and recommends role and profile changes',
+  phases: [{ title: 'Assess' }],
+}
+// GENERATED by driver/generate-assess.js — do not edit. lib/phase-assessment.sh run_phase_assessment, by hooks/assess-round.sh.
+const PLAN = ${JSON.stringify(plan)}
+// what lib/handlers/run-phase-assessment.py accepts (any object) and assess-apply.py reads
+const SCHEMA = { type: 'object', properties: { notes: { type: 'string' }, agent_recommendations: { type: 'array', items: { type: 'string' } },
+  role_reassignments: { type: 'array', items: { type: 'object', properties: { story_id: { type: 'string' }, newAgentRole: { type: 'string' }, reason: { type: 'string' } } } } } }
+const STEP = { type: 'object', properties: { done: { type: 'boolean' } } }
+phase('Assess')
+const run = async (agentType, label) => { const s = await agent('Reply now.', { agentType, schema: STEP, label, phase: 'Assess' }); return (s && s.result) || { error: true, reason: 'the step runner gave no result' } }
+let r = await run('assess-start', \`\${PLAN.label}: the phase assessment\`)
+while (r && r.pending) {
+  const q = r.pending
+  if (q.agent !== 'team-lead-agent') return { status: 'failed', exit: 0, reason: \`the assessment asked '\${q.agent}', which this workflow has no definition for\` }
+  const a = await agent(q.prompt, { agentType: 'assess-team-lead', ...(q.model ? { model: q.model } : {}), schema: SCHEMA, label: \`\${PLAN.label}: call \${q.n}\`, phase: 'Assess' })
+  r = a ? a.next : await run('assess-fail', \`\${PLAN.label}: call \${q.n} got no answer\`)
+}
+if (!r || r.error || !r.done) return { status: 'failed', exit: 0, reason: (r && r.reason) || 'no result' }
+return { status: r.exit === 0 ? 'ok' : 'warn', exit: 0, calls: r.calls, outcome: r.outcome }
+`;
+}
+
+module.exports = { main, emit };
+if (require.main === module) {
+  try { process.stdout.write(`${JSON.stringify(main(args(process.argv.slice(2))))}\n`); } catch (e) { process.stderr.write(`${e.stack || e.message}\n`); process.exit(1); }
+}

package/driver/generate-bridge.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+// THE CODELINE BRIDGE AS A NATIVE WORKFLOW (decision 24: built in the launch layer). lib/codeline-lanes.sh
+// _run_codeline_bridge (:464–534) after a lane completes in a run of more than one codeline: the engine template
+// codeline-bridge rendered by the pipeline's own renderer (render_engine_prompt), asked of the codeline-bridge-agent seam,
+// up to 1 + BRIDGE_MAX_RETRIES times with the call site's correction in front; the contract is the file the agent wrote
+// or, failing that, its reply (:491–493).
+//
+//   node driver/generate-bridge.js --install <dir> --project <p> --run <id> --lane <codeline> --codeline <copy>
+//        --prd <the lane's PRD> --out <dir> [--set claude|codemie] --env <{"LOG_DIR": the run's log folder}>
+// The run's environment is this process's (the driver runs it so). Writes only under --out, and removes a stale
+// contract at the bridge's own path (:487, the first attempt's `rm -f`). No AI.
+const fs = require('fs');
+const path = require('path');
+const agents = require('../generator/agents.js');
+const pipe = require('../generator/pipeline.js');
+const { bash } = require('./pipeline.js');
+
+function args(argv) { const a = {}; for (let i = 0; i < argv.length; i += 1) { if (argv[i].startsWith('--')) { a[argv[i].slice(2)] = argv[i + 1]; i += 1; } } return a; }
+const q = (x) => `'${String(x).replace(/'/g, "'\\''")}'`;
+
+function main(a) {
+  const env = { ...process.env, ...JSON.parse(a.env || '{}') };
+  const orch = path.join(a.install, 'orchestrations');
+  const out = path.resolve(a.out); fs.mkdirSync(out, { recursive: true });
+  const bridgeOut = path.join(env.LOG_DIR, `cross-codeline-${a.lane}.md`);                                     // :466
+  const maxRetries = Number(env.BRIDGE_MAX_RETRIES || 2);                                                       // :468
+  // :476–483 — the template, by the pipeline's own renderer, in the run's environment
+  const vals = path.join(out, 'bridge-vals.json');
+  fs.writeFileSync(vals, JSON.stringify({ __BRIDGE_OUT__: bridgeOut, __BPRD__: path.resolve(a.prd), __BCL__: a.lane, __BWT__: path.resolve(a.codeline) }));
+  const r = bash(env, 'render_engine_prompt', ['codeline-bridge', vals]);
+  if (r.status !== 0 || !r.stdout.trim()) throw new Error(`codeline-bridge did not render: ${r.stderr.slice(-600)}`);
+  const base = r.stdout.replace(/\n+$/, '');       // captured with $(...) at :482
+  fs.rmSync(bridgeOut, { force: true });
+  // the seam's agent, provisioned as every other agent (decision 13); the pause-linked roster is the run's project copy
+  const projectDir = env.EPAM_PROJECT_CONFIG_DIR;
+  const art = { orch, projectDir, checkpoint: projectDir, scripts: path.join(orch, 'scripts'), agentsDir: path.join(orch, 'agents'),
+    registry: path.join(orch, 'agents', 'invocation-profiles.json'), set: a.set || 'claude' };
+  const d = agents.definitionFor(art, 'codeline-bridge-agent', path.resolve(a.codeline), fs.mkdtempSync(path.join(out, 'scratch-')), {});
+  const pj = path.join(out, 'bridge.json');
+  fs.writeFileSync(pj, JSON.stringify({ bridgeOut, lane: a.lane }));
+  const defs = {};
+  for (let k = 0; k <= maxRetries; k += 1) {
+    const name = `codeline-bridge-agent-a${k}`;
+    defs[name] = { ...d.frontmatter, name: undefined, description: `${d.frontmatter.description} Bridge attempt ${k + 1}.`,
+      hooks: { PreToolUse: [{ matcher: 'StructuredOutput', hooks: [{ type: 'command',
+        command: [process.execPath, path.join(__dirname, 'bridge-hook.js'), '--bridge', pj, '--attempt', String(k), '--last', String(k === maxRetries ? 1 : 0)].map(q).join(' ') }] }] },
+      prompt: d.body.trim() };
+    delete defs[name].name;
+  }
+  // the hub's path rewrite of every prompt it hands a runner (llm-handler.sh:236–238)
+  const { relativizeLocalPaths } = require(path.join(orch, 'scripts', 'lib', 'relative-paths.js'));
+  const bases = [env.PROJECT_ROOT, env.JIRA_CODELINE_ROOT].filter(Boolean);
+  const word = (t) => relativizeLocalPaths(t.split('{out}').join(bridgeOut).split('{wt}').join(path.resolve(a.codeline)), bases);
+  const plan = { lane: a.lane, bridgeOut, maxRetries, base: relativizeLocalPaths(base, bases), bases, model: d.frontmatter.model,
+    blockOnFailure: env.CODELINE_BRIDGE_BLOCK_ON_FAILURE === 'true',
+    notes: {
+      // :499–507 — the correction for the next attempt, as the call site words it
+      failed: word('run_orch_prompt exited with code {rc}. You must call WriteFile to write the contract to {out} before finishing.'),
+      missing: word('The file {out} was NOT written. You MUST call WriteFile with path={out} to produce the contract — do not finish without writing it.'),
+      empty: word('The file {out} was written but is EMPTY. The source directory {wt} contains TypeScript files — read them and extract their exports before writing the contract.'),
+    },
+    codeline: path.resolve(a.codeline) };
+  fs.writeFileSync(path.join(out, 'agents-bridge.json'), JSON.stringify(defs, null, 2));
+  fs.mkdirSync(path.join(out, 'workflows'), { recursive: true });
+  fs.writeFileSync(path.join(out, 'workflows', 'bridge.js'), emit(plan));
+  fs.writeFileSync(path.join(out, 'bridge-plan.json'), JSON.stringify(plan, null, 2));
+  return plan;
+}
+
+function emit(plan) {
+  return `export const meta = {
+  name: 'bridge',
+  description: 'The codeline bridge: the completed codeline\\'s exported surface, as the cross-codeline contract the next lanes read',
+  phases: [{ title: 'Bridge' }],
+}
+// GENERATED by driver/generate-bridge.js — do not edit. lib/codeline-lanes.sh _run_codeline_bridge :464–534.
+const PLAN = ${JSON.stringify(plan)}
+const SCHEMA = { type: 'object', required: ['contract'], properties: { contract: { type: 'string' } } }
+phase('Bridge')
+let note = ''
+for (let k = 0; k <= PLAN.maxRetries; k++) {
+  const prompt = (note ? \`CORRECTION REQUIRED — YOUR PREVIOUS ATTEMPT FAILED: \${note}\\n\\n\` : '') + PLAN.base
+  const a = await agent(prompt, { agentType: \`codeline-bridge-agent-a\${k}\`, schema: SCHEMA, model: PLAN.model, label: \`bridge \${PLAN.lane} #\${k + 1}\` })
+  // an agent that ended without an answer is the call that failed (:497); its exit code is the runtime's, not a runner's
+  const res = a && a.result ? a.result : { ok: false, why: 'failed' }
+  if (res.ok) return { status: 'ok', exit: 0, lane: PLAN.lane, contract: PLAN.bridgeOut, attempts: k + 1 }
+  note = (PLAN.notes[res.why] || PLAN.notes.failed).split('{rc}').join('(the agent ended without an answer)')
+  if (k < PLAN.maxRetries) log(\`[bridge] Attempt \${k + 1}/\${PLAN.maxRetries} failed for '\${PLAN.lane}' — retrying with corrective prompt\`)
+}
+// :516–533 — out of attempts: fatal only when the project asks for it
+return PLAN.blockOnFailure
+  ? { status: 'failed', exit: 1, lane: PLAN.lane, reason: \`contract extraction failed after \${PLAN.maxRetries + 1} attempt(s) and CODELINE_BRIDGE_BLOCK_ON_FAILURE=true\` }
+  : { status: 'no-contract', exit: 0, lane: PLAN.lane, reason: \`contract extraction failed after \${PLAN.maxRetries + 1} attempt(s) — downstream codelines proceed without it\` }
+`;
+}
+
+module.exports = { main, emit };
+if (require.main === module) {
+  try { main(args(process.argv.slice(2))); } catch (e) { process.stderr.write(`${e.stack || e.message}\n`); process.exit(1); }
+}

package/driver/launch-env.js

@@ -0,0 +1,50 @@
+'use strict';
+// THE RUN'S LAUNCH SETTINGS, RECORDED AND REPLAYED (operator decision, 2026-10-16). The pipeline reads its behaviour from
+// the environment it is launched with (pauses, skips, retries, provider set …); a resume launched with a different
+// environment is a different run. The first launch records the settings it ran with (<run dir>/launch-env.json); every
+// resume replays them — a setting given again on the resume's own command line wins, and each resume's record says which
+// it changed. Secrets are never recorded. The Writer generator records the same settings in its plan (`launchEnv`); the
+// driver reads that field and refuses a plan made under other settings (driver/stages.js), never re-derives it.
+const fs = require('fs');
+const path = require('path');
+
+// The families the pipeline reads as launch settings (lib/run-modes.sh snapshot_operator_env records every exported name;
+// these are the ones the engine's own docs and config.env name). Exact names, not patterns, are added where a family
+// would sweep in a credential.
+const FAMILIES = /^(EPAM_|SKIP_|SPEC_|VC_|CODEGRAPH_|ORCH_|TICKET_LINK_|BRIDGE_|CODELINE_|REPRO_|SEAM_|STRICT_|RUNCLAUDE_|JIRA_)/;
+const NEVER = /(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|_KEY$|AUTH|COOKIE|CREDENTIAL|EMAIL)/i;   // secrets, and no PII
+// named settings a credential pattern would otherwise sweep out
+const ALSO = new Set(['JIRA_PROJECT_KEY']);
+const RUN_LOCAL = new Set(['EPAM_RESUME_RUN', 'EPAM_DRIVER_LIVE_APPROVED', 'EPAM_OPERATOR_SET_VARS', 'EPAM_PROJECT_CONFIG_DIR']);
+// launch settings outside the families: the Node heap every pipeline process inherits (run 9's launcher sets it,
+// launch-live-claude.sh:12; a codeline's sibling build can run out of heap without it)
+const NAMED = new Set(['NODE_OPTIONS']);
+
+function pick(env) {
+  const keep = (k) => NAMED.has(k) || (FAMILIES.test(k) && (ALSO.has(k) || !NEVER.test(k)) && !RUN_LOCAL.has(k));
+  return Object.fromEntries(Object.entries(env).filter(([k]) => keep(k)).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function record(runDir, env, log) {
+  const f = path.join(runDir, 'launch-env.json');
+  if (fs.existsSync(f)) throw new Error(`${f} exists: this run was launched before — resume it (--resume), or use a new run folder`);
+  const values = pick(env);
+  fs.writeFileSync(f, JSON.stringify({ recordedAt: new Date().toISOString(), values }, null, 2));
+  if (log) log(`[launch] recorded ${Object.keys(values).length} launch setting(s) → ${f}`);
+  return { env: values, changed: [] };
+}
+
+function replay(runDir, env, log) {
+  const f = path.join(runDir, 'launch-env.json');
+  if (!fs.existsSync(f)) throw new Error(`no recorded launch settings at ${f}: this run was never launched by the driver`);
+  const rec = JSON.parse(fs.readFileSync(f, 'utf8')).values;
+  const now = pick(env);
+  const out = { ...rec }; const changed = [];
+  for (const [k, v] of Object.entries(now)) if (rec[k] !== v) { out[k] = v; changed.push({ key: k, was: rec[k] === undefined ? null : rec[k], now: v }); }
+  const n = fs.readdirSync(runDir).filter((x) => /^launch-env\.resume-\d+\.json$/.test(x)).length + 1;
+  fs.writeFileSync(path.join(runDir, `launch-env.resume-${n}.json`), JSON.stringify({ resumedAt: new Date().toISOString(), changed, values: out }, null, 2));
+  if (log) log(`[launch] replayed ${Object.keys(rec).length} recorded setting(s); changed on this resume: ${changed.map((c) => c.key).join(', ') || 'none'}`);
+  return { env: out, changed };
+}
+
+module.exports = { record, replay, pick };

package/driver/phase-audits.js

@@ -0,0 +1,53 @@
+'use strict';
+// STEPS 11 AND 12, ONCE PER PHASE BEFORE ITS STORIES (run-agent-orchestration.sh:3094–3323), by the pipeline's own scans:
+//   Step 11 run_skills_audit_scan <profiles.json>: duplicate skill notes removed from the profiles; the self-contradictory
+//           ones would go to the skills-coordinator — whose seam is declared nowhere, so its call can never run
+//           (pipeline backlog B41): said, not run
+//   Step 12 run_tools_audit_scan <codeline>/.epam/dynamic-tools <log>: a broken tool would go to the tools-coordinator (the
+//           same: B41) and is recorded as the pipeline records it; a duplicate pair is flagged for manual review — both in
+//           <log>/tools-coordinator-audit.jsonl (RAO:3283–3318)
+// A failed scan is a warning, never a stop (RAO:3100–3104, 3203–3207). SKIP_SKILLS_AUDIT / SKIP_TOOLS_AUDIT skip each.
+const fs = require('fs');
+const path = require('path');
+const { bash } = require('./pipeline.js');
+
+const truthy = (v) => /^(1|true|yes|on)$/i.test(String(v || ''));
+const json = (t, fallback) => { try { return JSON.parse(String(t).trim().split('\n').pop()); } catch { return fallback; } };
+
+function runPhaseAudits(env, { wt, phase }, log) {
+  const out = { skills: null, tools: null };
+  if (truthy(env.SKIP_SKILLS_AUDIT)) log('[orch] Step 11: Skills coordinator audit skipped (SKIP_SKILLS_AUDIT=1)');
+  else {
+    const r = bash(env, 'run_skills_audit_scan', [env.AGENT_PROFILES_FILE], { log });
+    const ok = r.status === 0;
+    const res = ok ? json(r.stdout, null) : null;
+    out.skills = { ok: ok && !!res, ...(res || { duplicates_removed: 0, contradictions: [] }) };
+    if (!out.skills.ok) log(`  [SkillsAudit] scan failed — profiles.json was NOT audited this phase: ${(r.stdout + r.stderr).trim().slice(-300)}`);
+    if (out.skills.duplicates_removed > 0) log(`  [SkillsAudit] Removed ${out.skills.duplicates_removed} duplicate skill note(s) from profiles.json`);
+    const n = (out.skills.contradictions || []).length;
+    if (n) log(`  [SkillsAudit] ${n} suspected self-contradictory skill note(s) found — the skills-coordinator would rewrite them; its seam is declared nowhere, so the pipeline's call can never run (backlog B41) — not run`);
+    log(`[orch] Step 11: Skills coordinator audit → ${out.skills.ok ? 'pass' : 'warn'}`);
+  }
+  if (truthy(env.SKIP_TOOLS_AUDIT)) log('[orch] Step 12: Tools coordinator audit skipped (SKIP_TOOLS_AUDIT=1)');
+  else {
+    const r = bash(env, 'run_tools_audit_scan', [path.join(wt, '.epam', 'dynamic-tools'), env.LOG_DIR], { log });
+    const ok = r.status === 0;
+    const res = ok ? json(r.stdout, null) : null;
+    out.tools = { ok: ok && !!res, ...(res || { broken: [], duplicates: [] }) };
+    if (!out.tools.ok) log(`  [ToolsAudit] scan failed — dynamic tools were NOT audited this phase: ${(r.stdout + r.stderr).trim().slice(-300)}`);
+    const audit = path.join(env.LOG_DIR, 'tools-coordinator-audit.jsonl');
+    const at = new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+    for (const b of out.tools.broken || []) {
+      log(`  [ToolsAudit] broken tool ${b.tool}: ${b.reason} — the tools-coordinator's seam is declared nowhere (backlog B41) — not run`);
+      fs.appendFileSync(audit, `${JSON.stringify({ timestamp: at, phase: phase || 'unknown', tool: b.tool, reason: b.reason, event: 'broken_tool_rewrite' })}\n`);
+    }
+    for (const d of out.tools.duplicates || []) {
+      log(`  [ToolsAudit] Duplicate tools detected: ${d.tool_a}.sh and ${d.tool_b}.sh solve overlapping problems — flagged for manual review (not auto-merged)`);
+      fs.appendFileSync(audit, `${JSON.stringify({ timestamp: at, phase: phase || 'unknown', tool_a: d.tool_a, tool_b: d.tool_b, event: 'duplicate_flagged' })}\n`);
+    }
+    log(`[orch] Step 12: Tools coordinator audit → ${out.tools.ok ? 'pass' : 'warn'}`);
+  }
+  return out;
+}
+
+module.exports = { runPhaseAudits };

package/driver/phase-gate.js

@@ -0,0 +1,19 @@
+'use strict';
+// RAO:4237–4311 — STEP 5, THE PHASE GATE, by the pipeline's own check-phase-gate.sh as the orchestrator runs it
+// (SKIP_TESTS=true): review status, story completion, deliverables, cost variance. RETRY exits 1, ESCALATE exits 2; any
+// other code goes on (the pipeline's `case` has no default). Returns the phase's exit: 1, 2, or 0.
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function phaseGate(env, phase, log) {
+  const pg = spawnSync('bash', [path.join(env.SCRIPT_DIR, 'check-phase-gate.sh'), phase], { encoding: 'utf8', env: { ...env, SKIP_TESTS: 'true' }, maxBuffer: 64 * 1024 * 1024 });
+  fs.mkdirSync(env.LOG_DIR, { recursive: true });
+  fs.writeFileSync(path.join(env.LOG_DIR, `phase-gate-${phase}.log`), `${pg.stdout || ''}${pg.stderr || ''}`);
+  log(`[orch] Step 5: phase gate for '${phase}' → ${pg.status}`);
+  if (pg.status === 1) { log('[orch] Phase gate: RETRY — pipeline blocked'); return 1; }
+  if (pg.status === 2) { log('[orch] Phase gate: ESCALATE'); return 2; }
+  return 0;
+}
+
+module.exports = { phaseGate };

package/driver/pipeline.js

@@ -0,0 +1,49 @@
+'use strict';
+// THE PIPELINE'S OWN CODE, CALLED UNCHANGED FROM THE DRIVER: its bash functions (driver/bash.sh, in the run's
+// environment) and its node handlers (orchestrations/scripts/lib/handlers/*.js). No AI.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function writeEnv(dir, env) {
+  fs.mkdirSync(dir, { recursive: true });
+  const f = path.join(dir, `env-${process.pid}-${Math.floor(Math.random() * 1e9)}.json`);
+  fs.writeFileSync(f, JSON.stringify(env));
+  return f;
+}
+
+/** One bash function; returns {status, stdout, stderr, env (after the call, when asked)}. */
+function bash(env, fn, args = [], opts = {}) {
+  const tmp = env.TMPDIR || os.tmpdir();
+  const envFile = writeEnv(tmp, env);
+  const envOut = opts.exports ? path.join(tmp, `env-out-${process.pid}-${Date.now()}.json`) : '';
+  const r = spawnSync('bash', [path.join(__dirname, 'bash.sh'), envFile, fn, ...args.map(String)],
+    { encoding: 'utf8', env: { PATH: process.env.PATH, HOME: process.env.HOME, ...(envOut ? { BASH_CALL_ENV_OUT: envOut } : {}) },
+      maxBuffer: 256 * 1024 * 1024, cwd: opts.cwd || env.PROJECT_ROOT || tmp });
+  fs.rmSync(envFile, { force: true });
+  let after = null;
+  if (envOut && fs.existsSync(envOut)) { after = JSON.parse(fs.readFileSync(envOut, 'utf8')); fs.rmSync(envOut, { force: true }); }
+  if (opts.log) opts.log(`[pipeline] ${fn} ${args.join(' ')} → ${r.status}${r.stderr ? `\n${r.stderr.trim()}` : ''}`);
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '', env: after };
+}
+
+/** One node handler (lib/handlers/<name>.js). */
+function handler(env, name, args = [], opts = {}) {
+  const r = spawnSync(env.NODE_BIN || process.execPath, [path.join(env.SCRIPT_DIR, 'lib', 'handlers', `${name}.js`), ...args.map(String)],
+    { encoding: 'utf8', env, maxBuffer: 256 * 1024 * 1024, cwd: opts.cwd || env.PROJECT_ROOT || env.TMPDIR });
+  if (opts.log) opts.log(`[pipeline] ${name} ${args.join(' ')} → ${r.status}${r.stderr ? `\n${r.stderr.trim()}` : ''}`);
+  return { status: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+/** The env lines a function printed (KEY=VALUE), applied over env without overwriting a key already set (apply_run_mode). */
+function applyAssignments(env, text) {
+  const out = { ...env };
+  for (const line of String(text).split('\n')) {
+    const i = line.indexOf('='); if (i <= 0) continue;
+    const k = line.slice(0, i); if (!(k in out) || out[k] === '') out[k] = line.slice(i + 1);
+  }
+  return out;
+}
+
+module.exports = { bash, handler, applyAssignments };