@getarbiter/cli 0.5.0

package/dist/templates/scripts/record-agent-return.mjs.ejs

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// CATALOG: E1 (#1943, M8 core) — agent-return envelope recorder. The orchestrator pipes a
+// CATALOG: sub-agent's JSON return through this recorder, which (a) validates it against
+// CATALOG: schemas/agent-return.schema.json BEFORE writing — a malformed return fails at
+// CATALOG: hand-back time, not at gate time; (b) stamps branch/sha/ts itself (never trusted
+// CATALOG: from input, same authority model as gate-pass.json written by check-all.mjs);
+// CATALOG: (c) writes .arbiter/evidence/agent-returns/<sanitized-task>/<agent>-<n>.json.
+// CATALOG: Rejected fold-in into check-agent-return.mjs: that VALIDATES the persisted corpus
+// CATALOG: at gate time; this RECORDS a single return at hand-back time with authority-stamped
+// CATALOG: provenance. Different lifecycle (write-path vs read-path), shared validator lib.
+//
+//INV-138 (advisory at land-time per design §0).
+// Exit codes (INV-53): 0 written, 1 invalid input (schema/M12 violation — nothing written),
+// 2 ERROR (self / IO failure).
+//
+// Usage:
+//   node scripts/record-agent-return.mjs --task '#NNN' [--evidence-dir=<path>]
+//                                       [--repo-root=<path>] < return.json
+import {
+  constants as fsConstants,
+  closeSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { resolve, join } from 'node:path'
+import { execSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { validateSchema, enforceCitations, loadSchema } from './lib/agent-return-validate.mjs'
+import { arg } from './lib/gate-args.mjs'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const repoDefault = resolve(__dirname, '..')
+
+const argv = process.argv.slice(2)
+const TASK_ID = arg('task', argv)
+const PROVENANCE_VENDOR = arg('provenance-vendor', argv)
+const PROVENANCE_CLI = arg('provenance-cli', argv)
+const PROVENANCE_CLI_VERSION = arg('provenance-cli-version', argv)
+const PROVENANCE_DISPATCH = arg('provenance-dispatch', argv)
+const REPO_ROOT = arg('repo-root', argv) ? resolve(arg('repo-root', argv)) : repoDefault
+const EVIDENCE_DIR = arg('evidence-dir', argv)
+  ? resolve(arg('evidence-dir', argv))
+  : join(REPO_ROOT, '.arbiter', 'evidence', 'agent-returns')
+const SCHEMA_PATH = join(repoDefault, 'schemas', 'agent-return.schema.json')
+
+function readStdin() {
+  return new Promise((resolveRead) => {
+    let data = ''
+    process.stdin.setEncoding('utf-8')
+    process.stdin.on('data', (chunk) => {
+      data += chunk
+    })
+    process.stdin.on('end', () => resolveRead(data))
+    process.stdin.on('error', () => resolveRead(''))
+  })
+}
+
+function stampProvenance() {
+  let branch = 'unknown'
+  let sha = '0000000'
+  try {
+    branch =
+      execSync('git rev-parse --abbrev-ref HEAD', {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 4000,
+      }).trim() || 'unknown'
+    // FAIL-OPEN-INTENT: git rev-parse --abbrev-ref HEAD failed — non-git fixture dir; branch defaults to "unknown" (stamped, not trusted from input).
+  } catch {
+    /* non-git fixture */
+  }
+  try {
+    sha =
+      execSync('git rev-parse HEAD', {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 4000,
+      })
+        .trim()
+        .slice(0, 40) || '0000000'
+    // FAIL-OPEN-INTENT: git rev-parse HEAD failed — non-git fixture dir; sha defaults to "0000000" (stamped, not trusted from input).
+  } catch {
+    /* non-git fixture */
+  }
+  return { branch, sha, ts: new Date().toISOString() }
+}
+
+function stampAgentProvenance() {
+  const provenance = {
+    vendor: PROVENANCE_VENDOR ?? 'anthropic',
+    dispatch: PROVENANCE_DISPATCH ?? 'subagent',
+  }
+  if (PROVENANCE_CLI !== null) provenance.cli = PROVENANCE_CLI
+  if (PROVENANCE_CLI_VERSION !== null) provenance.cliVersion = PROVENANCE_CLI_VERSION
+  return provenance
+}
+
+function descriptorPath(fd) {
+  return `${process.platform === 'linux' ? '/proc/self/fd' : '/dev/fd'}/${fd}`
+}
+
+function openContainedDirectory(rootDir, childParts) {
+  if (process.platform === 'win32') {
+    throw new Error('secure agent-return recording is unsupported on Windows')
+  }
+  const flags = fsConstants.O_RDONLY | fsConstants.O_DIRECTORY | fsConstants.O_NOFOLLOW
+  const absoluteRoot = resolve(rootDir)
+  let fd = -1
+  try {
+    fd = openSync('/', flags)
+    for (const part of [...absoluteRoot.split('/').filter(Boolean), ...childParts]) {
+      const child = join(descriptorPath(fd), part)
+      try {
+        mkdirSync(child)
+      } catch (err) {
+        if (err?.code !== 'EEXIST') throw err
+      }
+      const next = openSync(child, flags)
+      closeSync(fd)
+      fd = next
+    }
+    return fd
+  } catch (err) {
+    if (fd !== -1) closeSync(fd)
+    throw err
+  }
+}
+
+function writeEnvelopeShard(dirPath, evidenceDir, task, agent, filename, content) {
+  const path = join(dirPath, filename)
+  let fileFd = -1
+  try {
+    fileFd = openSync(
+      path,
+      fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+      0o600,
+    )
+    writeFileSync(fileFd, content, 'utf8')
+    closeSync(fileFd)
+    fileFd = -1
+    return join(evidenceDir, task, filename)
+  } catch (err) {
+    if (fileFd !== -1) {
+      try {
+        closeSync(fileFd)
+        // FAIL-OPEN-INTENT: cleanup close failure must not replace the primary write error.
+      } catch {
+        // Preserve the primary write error.
+      }
+    }
+    if (err?.code === 'EEXIST') return null
+    try {
+      unlinkSync(path)
+      // FAIL-OPEN-INTENT: best-effort cleanup must not replace the primary write error.
+    } catch {
+      // Preserve the primary write error.
+    }
+    throw err
+  }
+}
+
+function writeEnvelopeContained(evidenceDir, task, agent, content) {
+  let dirFd = -1
+  try {
+    dirFd = openContainedDirectory(evidenceDir, [task])
+    const dirPath = descriptorPath(dirFd)
+    let n = 0
+    try {
+      n = readdirSync(dirPath).filter(
+        (f) => f.startsWith(`${agent}-`) && f.endsWith('.json'),
+      ).length
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err
+      // A freshly opened task directory may be empty; its first shard is zero.
+    }
+    for (let attempt = 0; attempt < 10_000; attempt++, n++) {
+      const filename = `${agent}-${n}.json`
+      const outPath = writeEnvelopeShard(dirPath, evidenceDir, task, agent, filename, content)
+      if (outPath !== null) return outPath
+    }
+    throw new Error(`too many agent-return shards for ${agent}`)
+  } finally {
+    if (dirFd !== -1) closeSync(dirFd)
+  }
+}
+
+function parseInput(raw) {
+  try {
+    return { parsed: JSON.parse(raw) }
+  } catch (err) {
+    process.stdout.write(
+      `[record-agent-return] FAIL: invalid JSON stdin: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return { exitCode: 1 }
+  }
+}
+
+function loadReturnSchema() {
+  try {
+    return { schema: loadSchema(SCHEMA_PATH) }
+  } catch (err) {
+    process.stderr.write(
+      `[record-agent-return] ERROR: cannot load schema: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return { exitCode: 2 }
+  }
+}
+
+function stampAndValidate(parsed, schema) {
+  // The agent supplies everything EXCEPT authority fields (branch/sha/ts/provenance). The
+  // recorder stamps those itself — never trusted from input — then validates the FULL stamped
+  // envelope against the schema before writing. A malformed return fails at hand-back time.
+  const stamped = stampProvenance()
+  const env = /** @type {Record<string, unknown>} */ (parsed)
+  env['branch'] = stamped.branch
+  env['sha'] = stamped.sha
+  env['ts'] = stamped.ts
+  env['provenance'] = stampAgentProvenance()
+  const schemaErrors = validateSchema(env, schema, schema, '<stdin>')
+  if (schemaErrors.length > 0) {
+    for (const error of schemaErrors) process.stdout.write(`[record-agent-return] FAIL: ${error}\n`)
+    return null
+  }
+  const citationErrors = enforceCitations(env, REPO_ROOT, '<stdin>')
+  if (citationErrors.length > 0) {
+    for (const error of citationErrors) process.stdout.write(`[record-agent-return] FAIL: ${error}\n`)
+    return null
+  }
+  return env
+}
+
+async function main() {
+  if (!TASK_ID || !/^#[0-9]+$/.test(TASK_ID)) {
+    process.stderr.write(
+      `[record-agent-return] ERROR: --task must be a GitHub issue id like '#1943' (got: ${String(TASK_ID)})\n`,
+    )
+    return 2
+  }
+  const raw = await readStdin()
+  const input = parseInput(raw)
+  if ('exitCode' in input) return input.exitCode
+  const schemaResult = loadReturnSchema()
+  if ('exitCode' in schemaResult) return schemaResult.exitCode
+  const env = stampAndValidate(input.parsed, schemaResult.schema)
+  if (env === null) return 1
+  const sanitizedTask = TASK_ID.replace(/[^0-9A-Za-z-]/g, '_')
+  const agent =
+    typeof env['agent'] === 'string' ? String(env['agent']).replace(/[^0-9A-Za-z-]/g, '-') : 'agent'
+  try {
+    const outPath = writeEnvelopeContained(
+      EVIDENCE_DIR,
+      sanitizedTask,
+      agent,
+      `${JSON.stringify(env, null, 2)}\n`,
+    )
+    process.stdout.write(`[record-agent-return] OK — wrote ${outPath}\n`)
+    return 0
+  } catch (err) {
+    process.stderr.write(
+      `[record-agent-return] ERROR: cannot write evidence: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    return 2
+  }
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write(
+      `[record-agent-return] ERROR: ${err instanceof Error ? err.message : String(err)}\n`,
+    )
+    process.exit(2)
+  })

package/dist/templates/scripts/record-journey-evidence.mjs.ejs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// <%= projectName %> — record a completed acceptance journey against the built artifact (#2382, ADR-037).
+// The journey runner remains project-specific; this command binds its result to this checkout.
+
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+
+const usage =
+  'Usage: node scripts/record-journey-evidence.mjs --task-id <id> --spec <command-or-spec> --target artifact\n';
+
+function fail(message) {
+  process.stderr.write(`[record-journey-evidence] ERROR: ${message}\n${usage}`);
+  process.exit(2);
+}
+
+const values = {};
+const allowed = new Set(['task-id', 'spec', 'target']);
+for (let i = 2; i < process.argv.length; i += 1) {
+  const arg = process.argv[i];
+  if (arg === '--help') {
+    process.stdout.write(usage);
+    process.exit(0);
+  }
+  const name = arg.startsWith('--') ? arg.slice(2) : '';
+  if (!allowed.has(name) || i + 1 >= process.argv.length) fail(`invalid argument: ${arg}`);
+  values[name] = process.argv[++i];
+}
+
+const taskId = String(values['task-id'] ?? '').trim();
+const spec = String(values.spec ?? '').trim();
+const target = String(values.target ?? '').trim();
+if (taskId.length === 0) fail('--task-id is required');
+if (spec.length === 0) fail('--spec is required');
+if (target !== 'artifact') fail('--target must be exactly "artifact"; dev-server runs are not accepted');
+
+const rootResult = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+  cwd: process.cwd(),
+  encoding: 'utf8',
+});
+if (rootResult.status !== 0) fail('must run inside a git checkout');
+const root = resolve(rootResult.stdout.trim());
+const git = (args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+const branchResult = git(['branch', '--show-current']);
+const shaResult = git(['rev-parse', 'HEAD']);
+if (branchResult.status !== 0 || shaResult.status !== 0) fail('could not resolve the current branch and HEAD sha');
+
+const branch = branchResult.stdout.trim();
+const sha = shaResult.stdout.trim();
+if (branch.length === 0 || sha.length === 0) fail('could not resolve the current branch and HEAD sha');
+
+const safeTaskId = taskId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64) || 'unknown';
+const evidenceDir = join(root, '.arbiter', 'evidence', 'journey');
+const evidencePath = join(evidenceDir, `${safeTaskId}.json`);
+const temporaryPath = `${evidencePath}.tmp-${process.pid}`;
+const evidence = { branch, sha, spec, target };
+
+try {
+  mkdirSync(evidenceDir, { recursive: true });
+  writeFileSync(temporaryPath, JSON.stringify(evidence, null, 2) + '\n', 'utf8');
+  renameSync(temporaryPath, evidencePath);
+} catch (error) {
+  const message = `could not write ${evidencePath}: ${error instanceof Error ? error.message : String(error)}`;
+  process.stderr.write(`[record-journey-evidence] ERROR: ${message}\n${usage}`);
+  process.exit(2);
+}
+
+process.stdout.write(`[record-journey-evidence] wrote ${evidencePath}\n`);

package/dist/templates/scripts/rework-log.mjs.ejs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// rework-log.mjs — rework telemetry (acceptance-anchor P4).
+//
+// Every redone PR / REWORK verdict is data, not noise: tag it with WHY (taxonomy) and
+// WHERE it was caught (review | gate | post-merge). After 10–15 entries the report
+// points at the exact issue-template section that is too loose — the pipeline becomes
+// self-correcting. Ledger: .arbiter/rework/ledger.jsonl (COMMITTED — paired gitignore
+// negations; merge=union via .gitattributes).
+//
+// Usage:
+//   node scripts/rework-log.mjs add --issue N [--pr N] --reason <r> --caught <c> [--note "…"]
+//   node scripts/rework-log.mjs report
+//
+// Exit codes (INV-53): 0 OK · 1 invalid entry · 2 usage/unexpected error
+import { readFileSync, existsSync, mkdirSync, appendFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+export const REWORK_REASONS = [
+  'misread-intent',
+  'missing-edge-case',
+  'scope-creep',
+  'design-mismatch',
+  'underspecified-issue',
+  'flaky-infra',
+  'other',
+]
+export const CAUGHT_STAGES = ['review', 'gate', 'post-merge']
+
+export const LEDGER_REL_PATH = join('.arbiter', 'rework', 'ledger.jsonl')
+
+// reason → which part of the issue template / process is too loose
+const TEMPLATE_HINTS = {
+  'misread-intent': 'Objective/AC wording ambiguous — tighten the Acceptance criteria field',
+  'missing-edge-case': 'AC lack edge-case criteria — add explicit AC-N lines for boundaries',
+  'scope-creep': 'Non-goals section absent or weak — make exclusions explicit',
+  'design-mismatch': 'Files/contracts + design references missing from the issue',
+  'underspecified-issue':
+    'Issue skipped the readiness gate — enforce issue-readiness before dispatch',
+  'flaky-infra': 'Not a template problem — track the infra flake as its own issue',
+  other: 'Unclassified — review the entry notes',
+}
+
+function isPositiveInt(value) {
+  return Number.isInteger(value) && value > 0
+}
+
+/** Pure entry validation; returns an error list (empty = valid). */
+export function validateEntry(entry) {
+  const e = entry === null || typeof entry !== 'object' ? {} : entry
+  const errors = []
+  if (!isPositiveInt(e.issue)) errors.push('issue: required positive integer (--issue N)')
+  if (e.pr != null && !isPositiveInt(e.pr)) errors.push('pr: must be a positive integer when given')
+  if (!REWORK_REASONS.includes(e.reason))
+    errors.push(`reason: must be one of ${REWORK_REASONS.join('|')}`)
+  if (!CAUGHT_STAGES.includes(e.caught))
+    errors.push(`caught: must be one of ${CAUGHT_STAGES.join('|')}`)
+  return errors
+}
+
+/** Pure aggregation over raw JSONL lines. */
+export function aggregateLedger(lines) {
+  const byReason = {}
+  const byCaught = {}
+  let total = 0
+  let malformed = 0
+  for (const line of lines) {
+    if (!line.trim()) continue
+    let entry
+    try {
+      entry = JSON.parse(line)
+      // FAIL-OPEN-INTENT: malformed ledger lines are COUNTED (agg.malformed) and reported by `report` — skipping one line never hides the corruption.
+    } catch {
+      malformed += 1
+      continue
+    }
+    total += 1
+    byReason[entry.reason] = (byReason[entry.reason] ?? 0) + 1
+    byCaught[entry.caught] = (byCaught[entry.caught] ?? 0) + 1
+  }
+  const hints = Object.entries(byReason)
+    .sort((a, b) => b[1] - a[1])
+    .map(([reason, count]) => `${reason} (${count}) → ${TEMPLATE_HINTS[reason] ?? '—'}`)
+  return { total, malformed, byReason, byCaught, hints }
+}
+
+function parseFlags(args) {
+  const out = {}
+  for (let i = 0; i < args.length; i += 1) {
+    const m = /^--([a-z-]+)$/.exec(args[i])
+    if (m) {
+      out[m[1]] = args[i + 1]
+      i += 1
+    }
+  }
+  return out
+}
+
+function headSha(cwd) {
+  try {
+    const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf-8' })
+    return r.status === 0 ? r.stdout.trim() : null
+    // FAIL-OPEN-INTENT: telemetry sha enrichment must never block recording an entry outside a git context — sha:null is the surfaced signal.
+  } catch {
+    return null // telemetry must never fail on a missing git context
+  }
+}
+
+function runAdd(rest, root, ledgerPath) {
+  const flags = parseFlags(rest)
+  const entry = {
+    ts: new Date().toISOString(),
+    issue: flags.issue ? Number(flags.issue) : undefined,
+    pr: flags.pr ? Number(flags.pr) : null,
+    reason: flags.reason,
+    caught: flags.caught,
+    note: flags.note ?? '',
+    sha: headSha(root),
+  }
+  const errors = validateEntry(entry)
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`FAIL rework-log: ${e}\n`)
+    return 1
+  }
+  mkdirSync(dirname(ledgerPath), { recursive: true })
+  appendFileSync(ledgerPath, `${JSON.stringify(entry)}\n`, 'utf-8')
+  console.log(`rework-log: recorded ${entry.reason}/${entry.caught} for #${entry.issue}`)
+  return 0
+}
+
+function runReport(ledgerPath) {
+  if (!existsSync(ledgerPath)) {
+    console.log('rework-log: no rework entries recorded yet')
+    return 0
+  }
+  const agg = aggregateLedger(readFileSync(ledgerPath, 'utf-8').split('\n'))
+  console.log(
+    `rework entries: ${agg.total}${agg.malformed ? ` (malformed skipped: ${agg.malformed})` : ''}`,
+  )
+  console.log('by caught stage:')
+  for (const stage of CAUGHT_STAGES) {
+    console.log(`  ${stage}: ${agg.byCaught[stage] ?? 0}`)
+  }
+  console.log('by reason → template hint:')
+  for (const hint of agg.hints) console.log(`  ${hint}`)
+  return 0
+}
+
+function main() {
+  const [subcommand, ...rest] = process.argv.slice(2)
+  const root = process.cwd()
+  const ledgerPath = join(root, LEDGER_REL_PATH)
+
+  if (subcommand === 'add') return runAdd(rest, root, ledgerPath)
+  if (subcommand === 'report') return runReport(ledgerPath)
+
+  process.stderr.write(
+    'ERROR rework-log: usage: rework-log.mjs add --issue N [--pr N] --reason <r> --caught <c> [--note "…"] | report\n',
+  )
+  return 2
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    process.exit(main())
+  } catch (err) {
+    console.error(`ERROR rework-log: ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(2)
+  }
+}

package/dist/templates/scripts/run-postman-tests.sh.ejs

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# run-postman-tests.sh — Execute Postman/Newman contract tests
+#
+# Generated by arbiter (#894) — F7: Postman/Newman contract test template
+# Emitted when contractType=rest-owned for Java projects.
+#
+# Prerequisites:
+#   npm install -g newman
+#   POSTMAN_COLLECTION env var must point to a valid .postman_collection.json
+#   SERVICE_BASE_URL must be set (e.g. http://localhost:8080)
+#
+# Exit codes:
+#   0 — all tests passed
+#   1 — one or more tests failed
+#   2 — environment error (missing collection, service not reachable)
+
+set -euo pipefail
+
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+COLLECTION="${POSTMAN_COLLECTION:-postman/<%= projectName ? projectName.replace(/[^a-z0-9_-]/gi, '-').toLowerCase() : 'api' %>.postman_collection.json}"
+BASE_URL="${SERVICE_BASE_URL:-http://localhost:8080}"
+ENVIRONMENT_FILE="${POSTMAN_ENVIRONMENT:-}"
+RESULTS_DIR="${RESULTS_DIR:-.arbiter/evidence/contract}"
+REPORTERS="cli,junit"
+JUNIT_OUTPUT="${RESULTS_DIR}/newman-results.xml"
+TIMEOUT_MS="${NEWMAN_TIMEOUT_MS:-30000}"
+MAX_RETRIES="${NEWMAN_MAX_RETRIES:-2}"
+
+# ─── Validation ───────────────────────────────────────────────────────────────
+
+if ! command -v newman &>/dev/null; then
+  echo "[run-postman-tests] ERROR: newman not found. Install: npm install -g newman" >&2
+  exit 2
+fi
+
+if [[ ! -f "${COLLECTION}" ]]; then
+  echo "[run-postman-tests] ERROR: collection not found: ${COLLECTION}" >&2
+  echo "  Set POSTMAN_COLLECTION to the path of your .postman_collection.json" >&2
+  exit 2
+fi
+
+# Wait for the service to be reachable (avoids false failures in CI startup races)
+HEALTH_URL="${BASE_URL}/actuator/health"
+MAX_WAIT=30
+elapsed=0
+until curl -sf "${HEALTH_URL}" &>/dev/null || [[ ${elapsed} -ge ${MAX_WAIT} ]]; do
+  sleep 2
+  elapsed=$((elapsed + 2))
+done
+
+if ! curl -sf "${HEALTH_URL}" &>/dev/null; then
+  echo "[run-postman-tests] WARNING: service health check failed at ${HEALTH_URL}" >&2
+  echo "  Continuing with tests — individual failures will surface below." >&2
+fi
+
+# ─── Set up output directory ──────────────────────────────────────────────────
+
+mkdir -p "${RESULTS_DIR}"
+
+# ─── Build newman arguments ───────────────────────────────────────────────────
+
+NEWMAN_ARGS=(
+  run "${COLLECTION}"
+  --base-url "${BASE_URL}"
+  --reporters "${REPORTERS}"
+  --reporter-junit-export "${JUNIT_OUTPUT}"
+  --timeout-request "${TIMEOUT_MS}"
+  --bail
+)
+
+if [[ -n "${ENVIRONMENT_FILE}" && -f "${ENVIRONMENT_FILE}" ]]; then
+  NEWMAN_ARGS+=(--environment "${ENVIRONMENT_FILE}")
+fi
+
+if [[ "${INJECT_PACT_SAMPLES:-false}" == "true" ]]; then
+  echo "[run-postman-tests] Injecting Pact samples before test run..."
+  bash "$(dirname "$0")/inject-pact-samples.sh"
+fi
+
+# ─── Execute with retry ───────────────────────────────────────────────────────
+
+attempt=0
+exit_code=0
+
+while [[ ${attempt} -le ${MAX_RETRIES} ]]; do
+  attempt=$((attempt + 1))
+  echo "[run-postman-tests] Attempt ${attempt} / $((MAX_RETRIES + 1))..."
+  set +e
+  newman "${NEWMAN_ARGS[@]}"
+  exit_code=$?
+  set -e
+
+  if [[ ${exit_code} -eq 0 ]]; then
+    break
+  fi
+
+  if [[ ${attempt} -le ${MAX_RETRIES} ]]; then
+    echo "[run-postman-tests] Attempt ${attempt} failed (exit ${exit_code}), retrying in 5s..." >&2
+    sleep 5
+  fi
+done
+
+# ─── Summary ──────────────────────────────────────────────────────────────────
+
+if [[ ${exit_code} -eq 0 ]]; then
+  echo "[run-postman-tests] All contract tests passed. Results: ${JUNIT_OUTPUT}"
+else
+  echo "[run-postman-tests] Contract tests failed (exit ${exit_code}). Results: ${JUNIT_OUTPUT}" >&2
+fi
+
+exit ${exit_code}