docs: Add executor starvation avoidance guide and tests

[mPokornyETM]

Summary

Documents the recommended pattern for using lockable resources in declarative pipelines without causing executor starvation, as discussed in #697.

Problem

When a pipeline uses agent any (or a specific label) at the top level together with options { lock(...) }, every build allocates an executor before acquiring the lock. Builds waiting for the lock hold their executors hostage, blocking other jobs.

Solution documented

Use agent none at the pipeline level and move agent into individual stages alongside options { lock(...) }:

pipeline {
  agent none
  stages {
    stage('Test') {
      options {
        lock('end-to-end-test-resource')
      }
      agent { label 'some-label' }
      steps {
        echo 'Running tests...'
      }
    }
  }
}

Changes

1. New example doc — avoiding-executor-starvation.md covering:

   • The anti-pattern (executor starvation)
   • The solution (agent none + stage-level agent)
   • Preparation stages without locks
   • Multiple stages under one lock
   • Scripted pipeline equivalent

2. Updated examples index — added link to the new guide in readme.md

3. New test class — DeclarativePipelineExecutorStarvationTest with four scenarios:

Test	Description
agentNoneWithStageLevelLockDoesNotConsumeExecutorWhileWaiting	Resource-name lock — waiter uses only flyweight executor, unrelated job runs freely
agentNoneWithStageLevelLabelLockDoesNotConsumeExecutor	Label-based lock — same behavior
preparationStageRunsWithoutLock	Build stage runs without lock, deploy stage acquires it
nestedStagesShareLockWithoutExecutorStarvation	Parent stage lock wraps nested stages, no executor starvation

Closes #697

[github-actions]

⏸️ Auto-merge countdown PAUSED: CI checks are not passing. The countdown will resume when all checks are green.