docs(agents): add downstream repository checklist to the PR template - #3298

  code_only="$(sed 's/#.*//' "$WORKFLOW")"
  normalized_code="$(printf '%s\n' "$code_only" | tr -d "[:space:]'\"")"

  # The block of the job that runs the unit tests, from its header to the next
  # job's. The condition has to sit on THAT job: pinning it file-wide would accept
  # the exact expression pasted into some other job while the unit-test job quietly
  # loses it.
  unit_job="$(printf '%s\n' "$code_only" | awk '
    /^  [a-zA-Z0-9_-]+:[[:space:]]*$/ { inside = ($0 ~ /^  checks:[[:space:]]*$/) }
    inside')"
  normalized_unit_job="$(printf '%s\n' "$unit_job" | tr -d "[:space:]'\"")"

  printf '%s\n' "$unit_job" | grep -q 'make unit-tests' || {
    echo "The 'checks' job in .github/workflows/pull-requests.yaml no longer runs 'make unit-tests'." >&2
    echo "This suite pins the trigger-map carve-out to that job. If the unit tests moved, point"
    echo "the checks below at their new job." >&2
    exit 1
  }

  # Three links carry the carve-out: the plan step names the map, the plan job
  # exports the flag, and the unit-test job gates on it. Cutting any one leaves the
  # other two looking perfectly wired, and none of them fails loudly — an unset or
  # unexported output dereferences to an empty string, so the condition is merely
  # false and the suite is skipped in silence, on exactly the PRs it guards, with
  # every test in this file still green. Pin all three.
  rel="${MAP_FILE#"$REPO_ROOT"/}"
  printf '%s\n' "$normalized_code" | grep -qF "$rel" || {
    echo "The plan step in .github/workflows/pull-requests.yaml does not name '$rel'." >&2
    echo "Without it, a PR that only edits the trigger map is treated as docs-only, the unit"
    echo "tests are skipped, and this file never runs — exactly when it is needed most." >&2
    echo "Fix: point the trigger_map detection at the map's new path." >&2
    exit 1
  }

  printf '%s\n' "$normalized_code" | grep -qF 'trigger_map:${{steps.p.outputs.trigger_map}}' || {
    echo "The plan job in .github/workflows/pull-requests.yaml does not export trigger_map." >&2
    echo "The step still computes it and the unit-test job still reads it, so this looks wired"
    echo "up, but an unexported output dereferences to an empty string: the job is skipped in"
    echo "silence on exactly the PRs this suite guards." >&2
    echo "Fix: restore 'trigger_map: \${{ steps.p.outputs.trigger_map }}' to the plan job's outputs." >&2
    exit 1
  }

  condition_norm="(needs.plan.outputs.code==true||needs.plan.outputs.trigger_map==true)"
  printf '%s\n' "$normalized_unit_job" | grep -qF "$condition_norm" || {
    echo "The job that runs 'make unit-tests' is not gated on:" >&2
    echo "  (needs.plan.outputs.code == 'true' || needs.plan.outputs.trigger_map == 'true')" >&2
    echo "Mentioning trigger_map in another job, or in a comment, does not count. Without that"
    echo "exact condition on that job, a PR which only edits the trigger map stays docs-only,"
    echo "skips the unit tests, and never runs this file — while every test here still passes." >&2
    exit 1
  }