ci: consolidate cicd workflow lanes, clean up helpers, and align CI docs (#86)

## Summary
This PR simplifies the CICD workflow by merging related lanes, reducing duplicated script logic, and keeping the same overall pipeline behavior and gates. It also updates CI documentation to match the new job topology.

## What Changed

### Workflow consolidation
- Merged base and complete CICD image publication into one producer job:
  - Build and Push CICD Images
- Merged dependency audits into one informational lane:
  - Dependency Audits (Informational)
- Merged runtime image build lanes into one release producer:
  - Build Release Images
- Merged tester image build lanes into one tester producer:
  - Build Tester Images

### Dependency/gate rewiring
- Updated downstream needs to consume merged producers.
- Kept output contracts for deployable and tester image references.
- Updated production and postmortem gates to the new job IDs.

### Cleanup/simplification
- Removed duplicate helper-function definition(s) in CICD scripts.
- Replaced a manual docker login retry loop with existing retry helper usage.
- Removed redundant shell option declarations where behavior was unchanged.
- Removed one unused E2E environment variable.

### Documentation alignment
- Updated CI architecture documentation to reflect merged workflow lanes.
- Updated troubleshooting guidance to reference current job sequencing.

## Why
- Reduce job startup overhead on self-hosted runners.
- Keep behavior consistent while lowering workflow complexity.
- Improve maintainability by removing duplicated/unused script fragments.
- Keep docs in sync with operational workflow reality.

## Validation
- Workflow file checks passed with pre-commit.
- Documentation checks passed with pre-commit (including markdownlint/prettier).
- No diagnostics/errors reported for updated workflow/docs files.

## Risk and Impact
- Low-to-medium operational risk due to job-ID/needs rewiring.
- Mitigated by preserving output keys consumed by integration and e2e lanes.
- Audit lane remains informational-only (non-blocking), same intent as before.

Co-authored-by: copilotcoder <copilotcoder@darkhelm.org>
Reviewed-on: #86

docs/DEVELOPMENT.md

@@ -17,10 +17,11 @@ This document outlines how to set up your development environment and work with
 
 - **[Poe Task Reference](POE_TASK_REFERENCE.md)** - Complete guide to unified development tasks
 - **[CI/CD Multi-Stage Build Architecture](CICD_MULTI_STAGE_BUILD.md)** - Technical details of the optimized build system
-- **[CI/CD Troubleshooting](GITEA_ACTIONS_TROUBLESHOOTING.md)** - Common issues and solutions
+- **[CI/CD Troubleshooting](CICD_TROUBLESHOOTING_GUIDE.md)** - Current CI lane failures and remediation paths
 - **[Secure Docker CI/CD](SECURE_DOCKER_CICD.md)** - Security considerations and practices
 - **[Deployable Runtime Contract](DEPLOYABLE_RUNTIME_CONTRACT.md)** - Canonical backend/frontend runtime artifact contract and exclusion rules
 - **[ADR003: Deployable Runtime Image Contract Boundaries](adr/ADR003-deployable_runtime_image_contract.md)** - Decision record for deployable runtime boundaries
+- **[ADR004: Registry Image Resolution and Auth Resilience Policy](adr/ADR004-registry-image-resolution-and-auth-resilience.md)** - Cross-workflow reliability policy for registry/auth/image fallback behavior
 
 ## Deployable Runtime Artifacts
 
@@ -209,7 +210,7 @@ git push
 1. Push your feature branch to the remote repository
 2. Navigate to the Gitea web interface
 3. Create a Pull Request from your feature branch to `main`
-4. Ensure all CI checks pass (100% green required)
+4. Ensure required CI checks pass (informational audit warnings do not block merge)
 5. Request review from team members
 6. Merge only after approval and passing CI
 
@@ -388,58 +389,68 @@ pre-commit run end-of-file-fixer --all-files
 
 ### Pipeline Overview
 
-The CI/CD pipeline uses a **multi-stage build architecture** for optimal performance:
+The canonical CI workflow is `.gitea/workflows/cicd.yaml`.
 
-- **Stage 1**: Source-level fast checks (format, lint, type-check) - **hard promotion gate**
-- **Stage 2**: Build base image (system dependencies, Python, Node.js) - **cached across runs**
-- **Stage 3**: Build complete image (project code and dependencies) - **rebuilt every time**
+Current triggers:
 
-Pipeline triggers:
+- Push on `main` and `develop`
+- Pull requests targeting `main` and `develop`
+- Manual `workflow_dispatch`
 
-- Push to any branch
-- Pull requests to `main` or `develop`
+Current dispatch inputs:
 
-### Multi-Stage Build Benefits ✅ **VALIDATED SUCCESSFUL**
+- `head_sha`: commit SHA to process
+- `force_rebuild_base`: force base image publication
 
-**Performance Gains**:
+### Current Job Topology
 
-- **85% build time improvement**: 3-5 minutes (down from 15-25 minutes)
-- Base image cached when `Dockerfile.cicd-base` unchanged (~95% of runs)
-- **100% success rate** achieved with optimized dependency management
-- Raspberry Pi 4GB workers handle builds efficiently with resource optimization
+The pipeline is intentionally staged so expensive image jobs run only after source checks and required gates pass:
 
-**Architecture**:
+1. Producer lane:
+   `Build and Push CICD Images` computes base hash, checks registry, and publishes both CICD base and complete CICD images.
+2. Source + audit lanes:
+   `Source Checks` and `Dependency Audits (Informational)` run after producer completion. Audit failures are intentionally non-blocking so both frontend and backend audits always report.
+3. Runtime image lanes:
+   `Build Release Images` publishes `deployable-backend-staging` and `deployable-frontend-staging`; `Build Tester Images` publishes integration/e2e tester images; then `Production Images Complete` gates downstream runtime tests.
+4. Runtime validation lanes:
+   `Runtime Black-Box Integration Tests` and `End-to-End Tests` validate staged runtime artifacts.
+5. Promotion lane:
+   `Promote Release Images` runs only for automated `push` events on `main`. It retags validated staging artifacts to release repos (`deployable-backend`, `deployable-frontend`) with `latest`, `v<major>.<minor>.0`, `v<major>.<minor>.<patch>`, and `v<major>.<minor>.<patch>-<7-char-short-sha>` tags. If the `main` commit is untagged, CI creates the next patch tag automatically; if no prior semver tag exists, the bootstrap baseline is `v0.0.0`.
+6. Postmortem lanes:
+   targeted postmortem jobs run when key lanes fail to capture diagnostics even when primary jobs fail early.
 
-- `cicd-base:latest` - System dependencies (Python 3.14, Node.js 24, build tools, pre-installed dev packages)
-- `cicd:latest` - Complete environment (project code + optimized dependency installation)
+### Reliability and Traceability Behavior
 
-**Recent Optimizations** (November 2025):
+Current workflow behavior includes:
 
-- **Dependency-first build pattern** prevents cache invalidation on code changes
-- **Yarn PnP state regeneration** ensures reliable frontend builds
-- **Network-resilient E2E testing** with simplified Docker operations
-- **Memory-optimized frontend installations** with proper swap configuration
+- registry auth realm host pinning from `WWW-Authenticate` challenge when registry tokens are issued from a different host
+- bounded retry logic for docker login/pull/push operations in image lanes
+- digest/tag contract checks for deployable image references before runtime black-box tests
+- release-note summary generation in the promotion lane (commit bullets since the previous release tag, or from the `v0.0.0` bootstrap baseline on first release)
+- context hydration for image-build lanes by copying `/workspace` from the published CICD image
+- runner split between `ubuntu-act` and `ubuntu-act-8gb` based on lane resource requirements
 
-For detailed technical information, see [CI/CD Multi-Stage Build Architecture](CICD_MULTI_STAGE_BUILD.md).
+For details of base/complete image build strategy, see [CI/CD Multi-Stage Build Architecture](CICD_MULTI_STAGE_BUILD.md).
+For incident handling, see [CI/CD Troubleshooting](CICD_TROUBLESHOOTING_GUIDE.md).
 
-### Pipeline Jobs
+### Operator Quick Reference
 
-All jobs run in parallel after the setup phases:
+Use workflow dispatch when you need deterministic reruns on a specific commit:
 
-1. **Source Fast Gate**:
-   Backend source checks (Ruff format/lint, Pyright), frontend source checks (Prettier, ESLint, TypeScript), and dispatches downstream build only on success.
+```bash
+# Example: rerun CI against an explicit commit
+# input head_sha=<commit>
 
-2. **Setup Base**: Builds and pushes base Docker image (conditional)
-3. **Setup Complete**: Builds and pushes complete CI/CD Docker image
-4. **Code Quality**:
-   Trailing whitespace check, end-of-file formatting, YAML syntax validation, and TOML syntax validation.
+# Example: force base image republish
+# input force_rebuild_base=true
+```
 
-5. **Backend Validation**:
-   Ruff formatting check, Ruff linting, Pyright type checking, Darglint docstring validation, unit tests with coverage, integration tests, and doctests (xdoctest).
+Recommended rerun order during flaky infrastructure incidents:
 
-6. **Frontend Validation**:
-   Prettier formatting check, ESLint linting, TypeScript compilation, and unit tests with coverage.
-   - E2E tests (Playwright)
+1. `Build and Push CICD Images`
+2. failing runtime image lane (`Build Release Images` or `Build Tester Images`)
+3. downstream integration/e2e lanes
+4. `Promote Release Images` (if staging validation succeeded but promotion failed)
 
 ### Local CI/CD Testing
 
@@ -477,7 +488,7 @@ Build and test CI/CD images locally:
 1. Navigate to your pull request in Gitea
 2. Check the "Checks" tab for detailed results
 3. Click on individual job names to see logs
-4. All jobs must pass (100% green) before merging
+4. All required jobs must pass before merging (informational dependency-audit findings are non-blocking)
 
 ## Branch Protection and Merge Requirements
 
@@ -486,7 +497,7 @@ Build and test CI/CD images locally:
 The `main` branch is protected with the following requirements:
 
 1. **No Direct Pushes**: All changes must come through pull requests
-2. **CI Must Pass**: All CI/CD jobs must be 100% green
+2. **CI Must Pass**: All required CI/CD jobs must pass (dependency audits are informational)
 3. **Review Required**: At least one team member approval needed
 4. **Up-to-date Branch**: Feature branch must be current with main
 
@@ -497,7 +508,7 @@ The `main` branch is protected with the following requirements:
 3. Address any CI failures by pushing fixes to the feature branch
 4. Request and receive code review approval
 5. Ensure branch is up-to-date with main
-6. Merge pull request (only available when all requirements met)
+6. Merge pull request (available when required jobs pass; informational audit failures do not block merge)
 
 ### If CI Fails