Document Konflux dependency update process in CLAUDE.md #3063

What happened

PR #3035 required updating 6+ interdependent files (pyproject.toml, uv.lock, .konflux/requirements-build.txt, .konflux/requirements.hashes.source.txt, .konflux/requirements.hashes.wheel.txt, .tekton/*.yaml) when bumping pydantic-ai to 2.38.0. The author pushed 7 commits over 2 days, each fixing one file or issue discovered after the previous push. Two additional PRs (#3048, #3053) were created by two developers to address the same underlying problem. CodeRabbit caught stale uv.lock (comment), missing dependencies, and dropped transitive deps across 4 review rounds.

What could go better

The CLAUDE.md and CONTRIBUTING.md contain no guidance on the Konflux dependency update workflow. The repo has a scripts/konflux_resolve.py script for Hermeto/Cachi2 resolution, but the complete multi-step process — and the order in which files must be regenerated — is undocumented. This gap directly caused the high rework rate: the developer fixed files one at a time because there was no checklist of all required changes. Now that fullsend is installed, the code agent will face the same gap if tasked with dependency updates. Confidence is high that this documentation gap contributed to the rework — the iterative fix pattern (7 commits, each addressing one reviewer finding or CI failure) is characteristic of an undocumented multi-step process.

Proposed change

Add a 'Dependency Update Process' section to CLAUDE.md under 'Development Workflow' documenting the complete Konflux dependency update checklist:

1. Update pyproject.toml with new version constraints
2. Run uv lock to regenerate uv.lock
3. Run python3 scripts/konflux_resolve.py --profile cpu to regenerate .konflux/requirements.*.txt
4. Verify .tekton/*.yaml prefetch package lists match the updated dependency set (add/remove packages as needed)
5. Check for dropped transitive dependencies: if a dependency is removed, verify no source files import packages that were only available as transitive deps of the removed package
6. Run uv run make verify to confirm type checking passes with the updated deps

This gives both the code agent and human developers a systematic process to follow. It also enables fullsend-ai/fullsend#2995 for this repo — the review agent can enforce companion changes only if the required companion changes are documented.

Validation criteria

The next dependency update PR on this repo (whether human- or agent-authored) should touch all required files in a single commit or small number of commits, rather than the 7-commit iterative pattern seen on PR #3035. Measure: fewer than 3 commits needed to achieve a passing CI status on the next Konflux dependency alignment PR.

Related issues checked

Searched: CLAUDE.md dependency guidance; Konflux dependency lockfile update process
Considered: fullsend-ai/fullsend#2995
fullsend-ai/fullsend#2995 proposes that the review agent should enforce companion changes documented in CLAUDE.md. This proposal provides the prerequisite content: the documentation itself. They are complementary, not overlapping.

Generated by retro agent from #3035