From ebeaf9d87d76c776751c2ce2dbf8db590474d817 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Thu, 29 Oct 2026 13:48:32 +0000
Subject: [PATCH] LCORE-0000: Document Konflux dependency update process in
 AGENTS.md

Add a 'Dependency Update Process (Konflux)' subsection under
'Development Workflow' in AGENTS.md (which CLAUDE.md symlinks to).
This documents the complete multi-step checklist for updating Python
dependencies in a Konflux hermetic build environment:

1. Update pyproject.toml with new constraints
2. Regenerate uv.lock
3. Run scripts/konflux_resolve.py --profile cpu to regenerate
   .konflux/requirements*.txt files
4. Verify .tekton/*.yaml prefetch package lists
5. Check for dropped transitive dependencies
6. Run uv run make verify

Closes #3063
---
 AGENTS.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 0019f41e3..28cd806ef 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -426,3 +426,35 @@ Allowed prefixes: `LCORE-`, `RSPEED-`, `MGTM-`, `OLS-`, `RHIDP-`, `LEADS-`, `CWF
 4. Follow existing code patterns in the module you're modifying
 5. Write unit tests covering new functionality
 6. Run format and verify before completion
+
+### Dependency Update Process (Konflux)
+
+When bumping or adding Python dependencies, the Konflux hermetic build requires
+several files to be regenerated **in order**. Complete all of these steps in a
+single PR to avoid iterative CI failures.
+
+1. **Update `pyproject.toml`** with the new version constraints.
+2. **Regenerate `uv.lock`** — run `uv lock` to sync the lockfile with the
+   updated constraints.
+3. **Regenerate Konflux requirement files** — run
+   `python3 scripts/konflux_resolve.py --profile cpu` to regenerate the hashed
+   requirement files under `.konflux/`:
+   - `.konflux/requirements.hashes.wheel.txt` (RHOAI wheels)
+   - `.konflux/requirements.hashes.source.txt` (PyPI sdists)
+   - `.konflux/requirements.hashes.wheel.pypi.txt` (PyPI wheel fallbacks)
+   - `.konflux/requirements-build.txt` (build dependencies for sdist packages)
+
+   This script requires `podman` and network access. See
+   `scripts/konflux_resolve.py --help` for additional options (`--verbose`,
+   `--quiet`). Build profiles are defined in `.konflux/profiles.toml`.
+4. **Verify `.tekton/*.yaml` prefetch package lists** — the resolve script
+   patches the `"packages"` field in the Tekton pipeline files listed in
+   `.konflux/profiles.toml` (`tekton_files`). Confirm that the package list in
+   `.tekton/lightspeed-stack-0-8-pull-request.yaml` and
+   `.tekton/lightspeed-stack-0-8-push.yaml` reflects the updated dependency set
+   (packages added or removed as needed).
+5. **Check for dropped transitive dependencies** — if a dependency is removed
+   or downgraded, verify that no source files import packages that were only
+   available as transitive dependencies of the removed/changed package.
+6. **Run `uv run make verify`** to confirm linting and type checking pass with
+   the updated dependencies.