gaia-framework 1.83.2 → 1.105.0

package/_gaia/core/validators/dev-story-security-controls.js

@@ -0,0 +1,264 @@
+/**
+ * Dev-Story Security Controls (E20-S13)
+ *
+ * Pure, deterministic invariants that harden the dev-story CI integration
+ * against the threats identified in Threat Model v1.3.0. These functions are
+ * the single source of truth for the four security controls — Steps 13-16 of
+ * the dev-story workflow MUST delegate to these helpers rather than inlining
+ * their own check logic. This keeps the bypass-attempt test matrix in one
+ * place and prevents drift between the workflow engine and the security
+ * contract.
+ *
+ * Threats mitigated:
+ *   - T25 (High)  — PR target manipulation              → resolvePrTargetBase
+ *   - T26 (Med/H) — Unexpected CI check bypass          → classifyCiCheck / evaluateMergeGate
+ *   - T27 (High)  — Force-merge attack                  → evaluateMergeGate
+ *   - TB-10       — Credential leakage via CLI args/env → verifyAuthHygiene
+ *
+ * Architecture references:
+ *   - ADR-033: Multi-Environment Promotion Chain
+ *   - architecture §10.24.5 Steps 14 (Create PR), 15 (Wait for CI), 16 (Merge PR)
+ *   - FR-249 (wait-for-ci allowlist), FR-250 (merge-gate enforcement)
+ *
+ * Design principles:
+ *   - Pure functions: no I/O, no filesystem, no network. Inputs in, decision out.
+ *   - No silent defaults — missing config throws, never falls back to `main`.
+ *   - Bypass flags are NEVER honored at the merge gate. YOLO mode is an
+ *     explicit carve-out: it accelerates user interaction but MUST NOT
+ *     weaken security invariants (see E20-S13 story Dev Notes).
+ *   - Halt messages are verbatim contracts — negative-path tests assert the
+ *     exact wording so downstream tooling (audit log parsers, run-book docs)
+ *     can rely on it.
+ *
+ * @module dev-story-security-controls
+ */
+
+// ─── T25 — PR target pinning ─────────────────────────────────────
+
+/**
+ * Resolve the `--base` branch for `gh pr create` by reading ONLY from the
+ * workflow-loaded global.yaml `ci_cd.promotion_chain[0].branch`. Any runtime
+ * source (env vars, CLI flags, user input) is ignored by construction —
+ * the `runtime` argument is accepted for API symmetry and is deliberately
+ * not consulted beyond preserving the call site signature.
+ *
+ * @param {object} globalConfig — Parsed global.yaml.
+ * @param {object} [_runtime]   — Runtime context (env, cliFlags, userInput). Ignored by design.
+ * @returns {string} The pinned base branch name.
+ * @throws If `promotion_chain[0]` or its `branch` field is missing.
+ */
+// T25 — see E20-S13 AC1: base branch is bound once from promotion_chain[0].branch.
+export function resolvePrTargetBase(globalConfig, _runtime) {
+  const chain = globalConfig?.ci_cd?.promotion_chain;
+  if (!Array.isArray(chain) || chain.length === 0) {
+    throw new Error(
+      "T25: promotion_chain[0] is not defined in global.yaml. " +
+        "Dev-story Step 14 requires a pinned base branch — no default to main is allowed.",
+    );
+  }
+  const first = chain[0];
+  const branch = first && first.branch;
+  if (!branch || typeof branch !== "string") {
+    throw new Error(
+      "T25: promotion_chain[0].branch is missing or not a string. " +
+        "Cannot construct a safe --base for gh pr create.",
+    );
+  }
+  return branch;
+}
+
+// ─── T26 — CI check name allowlist ───────────────────────────────
+
+/**
+ * Classify a CI check name as expected (in the allowlist) or unexpected.
+ *
+ * @param {string} name
+ * @param {string[]} allowlist — The resolved `promotion_chain[0].ci_checks`.
+ * @returns {"expected"|"unexpected"}
+ */
+// T26 — see E20-S13 AC2: unexpected checks never count toward PASS.
+export function classifyCiCheck(name, allowlist) {
+  if (!Array.isArray(allowlist)) return "unexpected";
+  return allowlist.includes(name) ? "expected" : "unexpected";
+}
+
+// ─── T27 — Merge gate enforcement ────────────────────────────────
+
+const FAILED_STATES = new Set(["failure", "cancelled", "timed_out"]);
+
+/**
+ * Evaluate whether a merge is allowed given the current CI check states.
+ *
+ * Rules (AC2 + AC3):
+ *   1. Build an index of returned checks. Any check whose name is NOT in
+ *      `requiredChecks` is classified unexpected — WARNING emitted, never
+ *      counted toward PASS.
+ *   2. For each name in `requiredChecks`, look up its status. Status must
+ *      be "success". `failure`, `cancelled`, `timed_out`, and missing are
+ *      all treated as NOT PASSED.
+ *   3. If any required check is not passed, `halt = true` and `haltMessage`
+ *      contains the canonical verbatim text. Bypass flags (`force`, `yolo`,
+ *      `env.GAIA_FORCE_MERGE`, `userConfirmation`) are NEVER honored — if
+ *      they are set while the gate is failing, the halt still fires.
+ *
+ * @param {{name:string, status:string}[]} checks — Live states from `gh pr checks`.
+ * @param {string[]} requiredChecks — Allowlist from promotion_chain[0].ci_checks.
+ * @param {object} [bypassAttempt] — Hostile inputs: force, yolo, env, userConfirmation. All ignored.
+ * @returns {{
+ *   allRequiredPassed: boolean,
+ *   halt: boolean,
+ *   haltMessage: string|null,
+ *   warnings: string[],
+ *   unexpected: string[],
+ * }}
+ */
+// T27 — see E20-S13 AC3: merge is refused on any failing required check.
+// Bypass flags (force, yolo, env, userConfirmation) are deliberately not
+// consulted — they are accepted for API symmetry so callers can't silently
+// drop them and believe a "stricter" call path exists.
+export function evaluateMergeGate(checks, requiredChecks, bypassAttempt = {}) {
+  void bypassAttempt; // explicit: bypass inputs are accepted and ignored (E20-S13 AC3)
+
+  const warnings = [];
+  const unexpected = [];
+  const checkIndex = new Map();
+  const requiredList = Array.isArray(requiredChecks) ? requiredChecks : [];
+
+  // Index returned checks and flag unexpected ones.
+  for (const c of checks || []) {
+    if (!c || typeof c.name !== "string") continue;
+    const classification = classifyCiCheck(c.name, requiredList);
+    if (classification === "unexpected") {
+      if (!unexpected.includes(c.name)) {
+        unexpected.push(c.name);
+        warnings.push(
+          `WARNING [dev-story/step-15]: unexpected CI check '${c.name}' ` +
+            `returned by gh pr checks but not declared in ` +
+            `promotion_chain[0].ci_checks. Excluded from merge-gate PASS calculation.`,
+        );
+      }
+      continue; // never counts toward PASS
+    }
+    // Expected — record status (last write wins on duplicates).
+    checkIndex.set(c.name, c.status);
+  }
+
+  // Evaluate each required check.
+  for (const name of requiredList) {
+    const status = checkIndex.get(name);
+    if (status === "success") continue;
+
+    const effective = status === undefined ? "missing" : status;
+    // Either a failing state or simply absent — both refuse the merge.
+    if (effective === "missing" || FAILED_STATES.has(effective) || status !== "success") {
+      return {
+        allRequiredPassed: false,
+        halt: true,
+        haltMessage:
+          `Merge refused: required CI check ${name} is in state ${effective}. ` +
+          `No bypass is supported.`,
+        warnings,
+        unexpected,
+      };
+    }
+  }
+
+  return {
+    allRequiredPassed: true,
+    halt: false,
+    haltMessage: null,
+    warnings,
+    unexpected,
+  };
+}
+
+// ─── TB-10 — Credential hygiene ──────────────────────────────────
+
+// Matches GitHub personal access tokens and fine-grained tokens.
+const GITHUB_TOKEN_PATTERN = /\b(ghp_|gho_|ghu_|ghs_|ghr_|github_pat_)[A-Za-z0-9_]{16,}\b/;
+// Matches any "Authorization:" header value on an argv position.
+const AUTH_HEADER_PATTERN = /Authorization\s*:\s*(Bearer|token)\s+\S+/i;
+// Matches a URL with userinfo credentials (user:pass@host).
+const URL_USERINFO_PATTERN = /\bhttps?:\/\/[^/\s@]*:[^/\s@]+@/i;
+// Environment variables that, if set, imply a token is sitting on the
+// process table and may leak. `gh` uses its own keyring — GH_TOKEN bypasses
+// that and is disallowed for dev-story CI calls.
+const FORBIDDEN_ENV_KEYS = new Set([
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_ENTERPRISE_TOKEN",
+  "GITHUB_ENTERPRISE_TOKEN",
+]);
+
+/**
+ * Verify a planned shell invocation does not leak credentials via argv,
+ * URLs, or the process environment. Returns `{ ok: true }` on pass.
+ *
+ * Rules (AC4):
+ *   1. The `curl` / `wget` / `http` / `https` binaries are disallowed for
+ *      GitHub interactions — use `gh` or `gh api` instead.
+ *   2. No argv position may contain a recognizable GitHub token.
+ *   3. No argv position may contain an Authorization header.
+ *   4. No argv position may be a URL with `user:pass@host` userinfo.
+ *   5. No forbidden env key (GH_TOKEN, GITHUB_TOKEN, etc.) may be present.
+ *
+ * @param {{command:string, args:string[], env:Record<string,string>}} invocation
+ * @returns {{ok:boolean, violation:(string|null)}}
+ */
+// TB-10 — see E20-S13 AC4: credentials must never appear in argv or env.
+export function verifyAuthHygiene(invocation) {
+  const { command, args, env } = invocation || {};
+  const argList = Array.isArray(args) ? args : [];
+  const envMap = env && typeof env === "object" ? env : {};
+
+  // Rule 1: disallowed commands for GitHub API interactions.
+  if (command === "curl" || command === "wget") {
+    // Check if the invocation targets GitHub.
+    const joined = argList.join(" ");
+    if (
+      /github\.com/i.test(joined) ||
+      /api\.github\.com/i.test(joined) ||
+      AUTH_HEADER_PATTERN.test(joined)
+    ) {
+      return {
+        ok: false,
+        violation: `curl/wget may not be used for GitHub API calls — use 'gh' or 'gh api'. Command: ${command}`,
+      };
+    }
+  }
+
+  // Rules 2-4: scan every argv position.
+  for (const arg of argList) {
+    if (typeof arg !== "string") continue;
+    if (GITHUB_TOKEN_PATTERN.test(arg)) {
+      return {
+        ok: false,
+        violation: `token-like value present in command arguments: <redacted>`,
+      };
+    }
+    if (AUTH_HEADER_PATTERN.test(arg)) {
+      return {
+        ok: false,
+        violation: `Authorization header present in command arguments — move to gh auth keyring`,
+      };
+    }
+    if (URL_USERINFO_PATTERN.test(arg)) {
+      return {
+        ok: false,
+        violation: `URL embeds userinfo credentials — use gh auth keyring instead`,
+      };
+    }
+  }
+
+  // Rule 5: forbidden env vars.
+  for (const key of Object.keys(envMap)) {
+    if (FORBIDDEN_ENV_KEYS.has(key)) {
+      return {
+        ok: false,
+        violation: `credential env var ${key} set — gh CLI must use its keyring, not process env`,
+      };
+    }
+  }
+
+  return { ok: true, violation: null };
+}

package/_gaia/core/validators/promotion-chain-env-resolver.js

@@ -0,0 +1,140 @@
+/**
+ * Promotion Chain Environment Resolver (E20-S10)
+ *
+ * Cross-references `test-environment.yaml` tier entries with
+ * `ci_cd.promotion_chain[]` entries declared in `global.yaml`, enriching the
+ * Test Execution Bridge context with CI provider, branch, and ci_checks when
+ * a valid mapping exists.
+ *
+ * Architecture references:
+ *   - ADR-028: Test Execution Bridge Protocol
+ *   - ADR-033: Multi-Environment Promotion Chain
+ *   - FR-244 / MPC-39: E17 Tier Mapping — Test Environment Integration
+ *   - NFR-045: Backward compatibility (no ci_cd block → silent ignore)
+ *
+ * Design principles:
+ *   - Opt-in at both layers: the caller must provide `global.ci_cd.promotion_chain`
+ *     AND a tier entry must set `promotion_chain_env_id`. Missing either layer
+ *     falls back to the pre-E20 tier-local resolution path.
+ *   - WARNING-level diagnostics — never HALTs. Orphaned references are
+ *     ignored and the bridge falls back to tier-local config.
+ *   - Silent backward compat: when `ci_cd` is absent from global.yaml, all
+ *     `promotion_chain_env_id` fields are ignored with no warning.
+ *
+ * @module promotion-chain-env-resolver
+ */
+
+/**
+ * Look up a promotion chain entry by id.
+ *
+ * @param {string} envId — The id to search for (from tier entry).
+ * @param {object} globalConfig — Parsed global.yaml content.
+ * @returns {object|null} The matching chain entry, or null if not found.
+ */
+export function resolvePromotionChainEnv(envId, globalConfig) {
+  if (!envId || !globalConfig) return null;
+  const chain = globalConfig?.ci_cd?.promotion_chain;
+  if (!Array.isArray(chain) || chain.length === 0) return null;
+  return chain.find((entry) => entry && entry.id === envId) || null;
+}
+
+/**
+ * Resolve the bridge execution context for a tier entry, optionally enriched
+ * from the promotion chain.
+ *
+ * Behavior matrix:
+ *   1. No `promotion_chain_env_id` on the tier entry → pre-E20 fallback,
+ *      no warnings, no enrichment.
+ *   2. `promotion_chain_env_id` set but `global.ci_cd` absent → silent ignore
+ *      (NFR-045 backward compat), id recorded on context for audit.
+ *   3. `promotion_chain_env_id` set and matches a chain entry → enrich the
+ *      context with ci_provider, branch, and ci_checks from the chain entry.
+ *   4. `promotion_chain_env_id` set but does NOT match any chain entry
+ *      (orphan) → emit WARNING naming the tier, orphaned id, and known ids;
+ *      fall back to tier-local config.
+ *
+ * @param {object} tierEntry — A single runner/tier definition from test-environment.yaml.
+ * @param {object} globalConfig — Parsed global.yaml content.
+ * @returns {{
+ *   promotion_chain_env_id: (string|null),
+ *   ci_provider: (string|undefined),
+ *   branch: (string|undefined),
+ *   ci_checks: (string[]|undefined),
+ *   warnings: string[]
+ * }}
+ */
+export function resolveBridgeContext(tierEntry, globalConfig) {
+  const context = {
+    promotion_chain_env_id: null,
+    warnings: [],
+  };
+
+  if (!tierEntry || typeof tierEntry !== "object") {
+    return context;
+  }
+
+  const envId = tierEntry.promotion_chain_env_id;
+
+  // Case 1: field not set / null — pre-E20 fallback, no warnings
+  if (envId === undefined || envId === null || envId === "") {
+    return context;
+  }
+
+  // Record the id on context regardless of resolution outcome — used by
+  // evidence JSON for audit (even orphaned references are surfaced).
+  context.promotion_chain_env_id = envId;
+
+  // Case 2: ci_cd absent → silent ignore (NFR-045)
+  const ciCd = globalConfig && globalConfig.ci_cd;
+  if (!ciCd) {
+    return context;
+  }
+
+  const chain = ciCd.promotion_chain;
+
+  // Case 2b: ci_cd present but promotion_chain not defined → treat like
+  // no ci_cd (silent). This guards partial ci_cd blocks.
+  if (chain === undefined || chain === null) {
+    return context;
+  }
+
+  // Case 4: empty chain or no match → orphan WARNING
+  if (!Array.isArray(chain) || chain.length === 0) {
+    context.warnings.push(formatOrphanWarning(tierEntry, envId, []));
+    return context;
+  }
+
+  const match = chain.find((entry) => entry && entry.id === envId);
+
+  if (!match) {
+    const knownIds = chain.map((e) => (e && e.id) || "?").filter(Boolean);
+    context.warnings.push(formatOrphanWarning(tierEntry, envId, knownIds));
+    return context;
+  }
+
+  // Case 3: valid mapping — enrich context
+  context.ci_provider = match.ci_provider;
+  context.branch = match.branch;
+  context.ci_checks = Array.isArray(match.ci_checks) ? [...match.ci_checks] : undefined;
+
+  return context;
+}
+
+/**
+ * Format a human-readable orphaned-id warning.
+ *
+ * @param {object} tierEntry — Tier entry (for tier name).
+ * @param {string} orphanId — The orphaned promotion_chain_env_id value.
+ * @param {string[]} knownIds — The list of ids present in the chain.
+ * @returns {string}
+ */
+function formatOrphanWarning(tierEntry, orphanId, knownIds) {
+  const tierName = (tierEntry && tierEntry.name) || `tier-${tierEntry?.tier ?? "?"}`;
+  const knownList = knownIds.length > 0 ? `[${knownIds.join(", ")}]` : "[]";
+  return (
+    `WARNING [test-environment.yaml]: tier '${tierName}' references ` +
+    `promotion_chain_env_id '${orphanId}' which does not exist in ` +
+    `ci_cd.promotion_chain (known ids: ${knownList}). ` +
+    `Mapping ignored. Falling back to tier-local config.`
+  );
+}

package/_gaia/core/validators/test-environment-validator.js

@@ -0,0 +1,292 @@
+/**
+ * test-environment.yaml Schema Validator
+ *
+ * Validates the test-environment.yaml manifest against the schema
+ * defined in architecture section 10.20.5 (ADR-028, FR-196).
+ *
+ * Design:
+ *   - Emits WARNINGs on schema violations — never throws errors.
+ *   - Missing or empty file is treated as valid (auto-discovery fallback).
+ *   - Includes a minimal YAML parser sufficient for the manifest schema.
+ *
+ * @module test-environment-validator
+ */
+
+// ─── Minimal YAML Parser ────────────────────────────────────────
+
+/**
+ * Parse a scalar YAML value into its JS equivalent.
+ * Handles booleans, null, integers, floats, and quoted strings.
+ */
+function parseScalar(raw) {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (raw === "null" || raw === "~") return null;
+  if (/^\d+$/.test(raw)) return parseInt(raw, 10);
+  if (/^\d+\.\d+$/.test(raw)) return parseFloat(raw);
+  // Strip surrounding quotes
+  if (
+    (raw.startsWith('"') && raw.endsWith('"')) ||
+    (raw.startsWith("'") && raw.endsWith("'"))
+  ) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+
+/**
+ * Parse an inline YAML flow sequence like `[a, b, c]` into an array of strings.
+ */
+function parseFlowSequence(raw) {
+  return raw
+    .slice(1, -1)
+    .split(",")
+    .map((s) => s.trim());
+}
+
+/**
+ * Flush the current nested structure (list or map) into the result object.
+ */
+function flushNested(result, key, isList, list, isMap, map) {
+  if (isList && key) result[key] = list;
+  else if (isMap && key) result[key] = map;
+}
+
+/**
+ * Parse a simple YAML string into a JS object.
+ *
+ * Supports: top-level scalars, lists of scalars, lists of maps (one level),
+ * nested maps (two levels), and inline flow sequences `[a, b]`.
+ *
+ * Limitations: does not support multi-line strings, anchors, aliases, or
+ * deeply nested structures. This is intentional — the manifest schema is flat.
+ */
+function parseSimpleYaml(text) {
+  const result = {};
+  const lines = text.split("\n");
+  let currentKey = null;
+  let currentList = null;
+  let currentMap = null;
+  let currentMapKey = null;
+  let inList = false;
+  let inMap = false;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/#.*$/, "").trimEnd();
+    if (line.trim() === "") continue;
+
+    const indent = line.length - line.trimStart().length;
+
+    // ── Top-level key ──────────────────────────────────────────
+    if (indent === 0 && line.includes(":")) {
+      flushNested(result, currentKey, inList, currentList, inMap, currentMap);
+      inList = false;
+      inMap = false;
+      currentList = null;
+      currentMap = null;
+      currentMapKey = null;
+
+      const colonIdx = line.indexOf(":");
+      const key = line.substring(0, colonIdx).trim();
+      const val = line.substring(colonIdx + 1).trim();
+      currentKey = key;
+
+      if (val === "") continue; // value on subsequent lines
+      result[key] = parseScalar(val);
+      currentKey = null;
+      continue;
+    }
+
+    // ── List item (dash prefix) ────────────────────────────────
+    if (line.trimStart().startsWith("- ") && currentKey) {
+      if (!inList && !inMap) {
+        inList = true;
+        currentList = [];
+      }
+      if (!inList) continue;
+
+      const itemText = line.trimStart().substring(2).trim();
+      if (itemText.includes(":")) {
+        const colonIdx = itemText.indexOf(":");
+        const k = itemText.substring(0, colonIdx).trim();
+        const v = itemText.substring(colonIdx + 1).trim();
+        currentList.push({ [k]: parseScalar(v) });
+      } else {
+        currentList.push(parseScalar(itemText));
+      }
+      continue;
+    }
+
+    // ── Indented key: value ────────────────────────────────────
+    if (indent > 0 && line.includes(":") && currentKey) {
+      const trimmed = line.trimStart();
+      const colonIdx = trimmed.indexOf(":");
+      const k = trimmed.substring(0, colonIdx).trim();
+      const v = trimmed.substring(colonIdx + 1).trim();
+
+      // Inside a list entry — append properties to the last entry
+      if (inList && currentList && currentList.length > 0) {
+        const lastEntry = currentList[currentList.length - 1];
+        if (typeof lastEntry === "object" && lastEntry !== null) {
+          lastEntry[k] =
+            v.startsWith("[") && v.endsWith("]")
+              ? parseFlowSequence(v)
+              : v === ""
+                ? {}
+                : parseScalar(v);
+        }
+        continue;
+      }
+
+      // Nested map
+      if (!inMap) {
+        inMap = true;
+        currentMap = {};
+      }
+
+      if (v === "" || v.startsWith("{")) {
+        // Sub-map key (e.g., tiers.1)
+        currentMapKey = k;
+        if (!currentMap[k]) currentMap[k] = {};
+      } else if (v.startsWith("[") && v.endsWith("]")) {
+        const target =
+          currentMapKey && currentMap[currentMapKey]
+            ? currentMap[currentMapKey]
+            : currentMap;
+        target[k] = parseFlowSequence(v);
+      } else {
+        const target =
+          currentMapKey && currentMap[currentMapKey]
+            ? currentMap[currentMapKey]
+            : currentMap;
+        target[k] = parseScalar(v);
+      }
+    }
+  }
+
+  flushNested(result, currentKey, inList, currentList, inMap, currentMap);
+  return result;
+}
+
+// ─── Runner Validation ──────────────────────────────────────────
+
+const RUNNER_REQUIRED_FIELDS = ["name", "command", "tier"];
+
+/**
+ * Validate a single runner entry and return any warning messages.
+ * @param {object} runner — Parsed runner object
+ * @param {number} index — Position in the runners array (for error messages)
+ * @returns {string[]} Warning messages (empty if valid)
+ */
+function validateRunnerEntry(runner, index) {
+  const warnings = [];
+  if (typeof runner !== "object" || runner === null) {
+    warnings.push(`Runner entry [${index}] is not a valid map.`);
+    return warnings;
+  }
+  for (const field of RUNNER_REQUIRED_FIELDS) {
+    if (runner[field] === undefined || runner[field] === null || runner[field] === "") {
+      warnings.push(
+        `Runner entry [${index}] is missing required field: '${field}'.`
+      );
+    }
+  }
+  return warnings;
+}
+
+// ─── Public API ─────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid    — true if no warnings (or file absent/empty)
+ * @property {string[]} warnings — list of WARNING-level schema violations
+ * @property {string} [info]    — informational message (e.g., auto-discovery fallback)
+ */
+
+/**
+ * Validate test-environment.yaml content against the manifest schema.
+ *
+ * @param {string|null} content — Raw YAML content, null if file absent, or empty string.
+ * @param {object} [options] — Optional cross-validation context.
+ * @param {object} [options.globalConfig] — Parsed global.yaml content. When provided
+ *   and `ci_cd.promotion_chain` exists, the validator cross-checks every
+ *   `promotion_chain_env_id` against chain ids and emits an orphan warning
+ *   if the id is not present (E20-S10, AC4).
+ * @returns {ValidationResult}
+ */
+export function validateTestEnvironment(content, options = {}) {
+  // AC5: Missing file is not an error — fallback to auto-discovery
+  if (content === null || content === undefined || content.trim() === "") {
+    return {
+      valid: true,
+      warnings: [],
+      info: "No test-environment.yaml found — using auto-discovery fallback (FR-196).",
+    };
+  }
+
+  const warnings = [];
+
+  let parsed;
+  try {
+    parsed = parseSimpleYaml(content);
+  } catch {
+    return {
+      valid: false,
+      warnings: [
+        "Failed to parse test-environment.yaml — invalid YAML syntax.",
+      ],
+    };
+  }
+
+  // AC2: Required field — version
+  if (parsed.version === undefined || parsed.version === null) {
+    warnings.push(
+      "Missing required field: 'version'. Expected an integer (e.g., version: 1)."
+    );
+  }
+
+  // AC2: Required field — runners (list of maps with name, command, tier)
+  if (!parsed.runners || !Array.isArray(parsed.runners)) {
+    warnings.push(
+      "Missing required field: 'runners'. Expected a list of runner entries with name, command, and tier."
+    );
+  } else {
+    for (let i = 0; i < parsed.runners.length; i++) {
+      warnings.push(...validateRunnerEntry(parsed.runners[i], i));
+    }
+  }
+
+  // E20-S10 AC4: Cross-validate promotion_chain_env_id references against
+  // the promotion chain when the caller provides a globalConfig. When
+  // `ci_cd` is absent (AC6 backward compat), this check is skipped entirely
+  // — promotion_chain_env_id fields are silently ignored.
+  const globalConfig = options && options.globalConfig;
+  const chain = globalConfig?.ci_cd?.promotion_chain;
+
+  if (Array.isArray(chain) && Array.isArray(parsed.runners)) {
+    const knownIds = chain
+      .map((entry) => (entry && entry.id ? entry.id : null))
+      .filter((id) => id !== null);
+
+    for (const runner of parsed.runners) {
+      if (!runner || typeof runner !== "object") continue;
+      const envId = runner.promotion_chain_env_id;
+      if (envId === undefined || envId === null || envId === "" || envId === "null") {
+        continue;
+      }
+      if (!knownIds.includes(envId)) {
+        const tierName = runner.name || `tier-${runner.tier ?? "?"}`;
+        warnings.push(
+          `WARNING [test-environment.yaml]: tier '${tierName}' references ` +
+            `promotion_chain_env_id '${envId}' which does not exist in ` +
+            `ci_cd.promotion_chain (known ids: [${knownIds.join(", ")}]).`
+        );
+      }
+    }
+  }
+
+  return {
+    valid: warnings.length === 0,
+    warnings,
+  };
+}