chore: update badge URLs to commit b5c21b71 [skip ci]

CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.55.2] - 2026-09-19
+
+### Bug Fixes
+
+- *(ci)* Supply git identity for dep-PR manifest commits
+
+## [0.55.1] - 2026-09-19
+
+### Bug Fixes
+
+- *(ci)* Resolve dep-PR container digest via registry v2 API
+
+## [0.55.0] - 2026-09-19
+
+### Features
+
+- *(ci)* Retry dep-PR container verification until publish lands
+
+## [0.54.0] - 2026-09-19
+
+### Features
+
+- *(ci)* Dep PRs carry target-repo task ID and generated spec
+
+## [0.53.3] - 2026-09-19
+
+### Bug Fixes
+
+- *(ci)* Check out API-created dep branch via remote-tracking ref
+
+## [0.53.2] - 2026-09-19
+
+### Bug Fixes
+
+- *(ci)* Create dep-PR branches via POST /branches
+
+## [0.53.1] - 2026-09-19
+
+### Bug Fixes
+
+- *(ci)* Handle list-shaped ref response in create_dependency_pr
+
+## [0.53.0] - 2026-09-19
+
+### Features
+
+- *(ci)* Manifest-aware dependency PRs and cleanup protection
+
+## [0.52.0] - 2026-09-19
+
+### Features
+
+- *(ci)* Verify producer container artifact before opening dependency PR
+
+## [0.51.12] - 2026-09-19
+
+### Bug Fixes
+
+- Create_dependency_pr clones target repo instead of editing producer checkout
+
+## [0.51.11] - 2026-09-19
+
+### Bug Fixes
+
+- *(ci)* Retry Vikunja lookups and surface self-approval merge failures
+
 ## [0.51.10] - 2026-09-17
 
 ### Bug Fixes

README.md

@@ -16,12 +16,12 @@ quality badges.
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/python.svg)](https://www.python.org/downloads/)
 
 ## Why devx?
 
@@ -87,7 +87,7 @@ extra index and list devx in your dependencies:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.51.10",
+    "devx>=0.55.2",
 ]
 
 [tool.pip]
@@ -101,8 +101,8 @@ pip install -e .
 ```
 
 > **Note:** If your project requires a specific devx version, pin it in
-> `dependencies` (for example, `"devx==0.51.10"`) or use a version constraint
-> (for example, `"devx>=0.51.10,<0.52"`).
+> `dependencies` (for example, `"devx==0.55.2"`) or use a version constraint
+> (for example, `"devx>=0.55.2,<0.56"`).
 
 ### Optional extras
 

docs/index.md

@@ -12,12 +12,12 @@ project to be reusable across all oblachno-oss repositories.
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/ef6e8cf76365d1332a88437ae62a93ef63335e68/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/devx/raw/commit/b5c21b71a4c057aa45a871c5cef1ddddd07458d5/python.svg)](https://www.python.org/downloads/)
 
 ## Overview
 
@@ -74,14 +74,14 @@ Add devx to your `pyproject.toml` dependencies and configure the registry:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.51.10",
+    "devx>=0.55.2",
 ]
 
 [tool.pip]
 extra-index-url = "https://git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple"
 ```
 
-Pin a specific version if needed: `"devx==0.51.10"` or `"devx>=0.51.10,<0.52"`.
+Pin a specific version if needed: `"devx==0.55.2"` or `"devx>=0.55.2,<0.56"`.
 
 ### Optional extras
 

docs/specs/DEVX-166.md

@@ -1,27 +1,47 @@
-# DEVX-166: Exclude docs/plans/* from PR size check
+# DEVX-166: create_dependency_pr must clone the target repo
 
 ## Problem
-Planning docs in `docs/plans/` are legitimately large (700+ lines) but
-fail the PR size check (max 500 lines). This blocks PRs that only add
-planning documents.
+
+`create_dependency_pr` resolves the pinned-version file and runs all
+git operations in the current working directory. Producer post-merge
+workflows (grm, sso-bridge) invoke it from the *producer* checkout, so
+it searches/modifies the wrong repository: `find_pinned_version` reads
+files that do not exist there, and the git fetch/checkout/commit/push
+sequence runs in the producer clone. The failure is silent — producer
+workflows append `|| echo warning`, so a no-op looks like success.
 
 ## Approach
-REQ-1: Add `docs/plans/*` to `DEFAULT_EXCLUDED_PATTERNS` in
-  `src/devx/ci/check_pr_size.py`
-REQ-2: Add test coverage for the new exclusion pattern
+
+REQ-1: Clone the target repo (`--repo`) into a temporary directory with
+an authenticated `http.extraHeader`, then run every file lookup and git
+operation (fetch, checkout, add, commit, push) inside that clone. The
+push uses the same auth header config.
+
+REQ-2: Tests mock `subprocess.run` so no real clone happens in the unit
+suite (test-isolation gate).
+
+## Files Affected
+
+- `src/devx/ci/create_dependency_pr.py`
+- `tests/unit/test_create_dependency_pr.py`
 
 ## Test Plan
-- `make pytest-cov` passes with 100% coverage
-- `make lint-all` passes
+
+- Existing CLI tests keep passing with the subprocess mock in place.
+- Verify the clone command targets the `--repo` URL and that git ops
+  run with `cwd=<clone>` (asserted via the mock's call list).
 
 ## Deploy Plan
-- Merge to master → post-merge auto-publishes new devx version
-- Infra PR #1179 picks up the fix once devx is bumped
+
+Merge via auto-merge after green CI. The fix takes effect the next time
+a producer post-merge workflow invokes `create_dependency_pr`.
 
 ## Rollback Plan
-- Revert the merge commit
+
+Revert the squash-merge commit on master; the previous (broken) CWD
+behavior returns, which is strictly worse — no state is created.
 
 ## Acceptance Criteria
-- [x] REQ-1: Add `docs/plans/*` to `DEFAULT_EXCLUDED_PATTERNS` in
-  `src/devx/ci/check_pr_size.py`
-- [x] REQ-2: Add test coverage for the new exclusion pattern
+
+- [x] REQ-1: target repo cloned to tempdir; all file/git ops run in the clone
+- [x] REQ-2: unit tests never spawn a real git subprocess

docs/specs/DEVX-167-skills-historical.md

@@ -0,0 +1,64 @@
+# DEVX-167: Add dependency-graph, deployment-coordination, and skill-creation skills
+
+## Problem
+Agents working across the oblachno ecosystem lack shared, persistent
+context for three recurring pain points:
+
+1. **Cross-repo dependency ordering** — agents frequently merge
+   downstream PRs before the upstream publish job completes, or forget
+   to bump infra. There is no single reference for which repo produces
+   what and in what order changes must propagate.
+2. **devx release coordination** — devx is the base package pinned by
+   grm, sso-bridge, and infra. Agents repeatedly merge devx PRs and
+   immediately merge downstream bumps without waiting for the PyPI
+   publish job, or bump only one consumer when a change affects all
+   three.
+3. **Skill quality drift** — skills are created ad hoc with inconsistent
+   structure, vague advice, and no automated validation reference. New
+   skills miss required sections, reference nonexistent make targets,
+   and drift across repos.
+
+## Approach
+Add three SKILL.md files under `.devin/skills/`:
+
+REQ-1: `dependency-graph` — shared skill mapping the oblachno ecosystem
+(repos, what each produces, consumers, release triggers, correct
+cross-repo change order, state verification checklist)
+
+REQ-2: `deployment-coordination` — devx-specific skill covering the
+devx release flow, downstream consumers, manual bump procedure, and
+common mistakes when coordinating a devx change
+
+REQ-3: `skill-creation` — shared skill defining skill structure,
+quality standards, scope rules, automated validation reference, and a
+creation checklist
+
+## Files Affected
+- `.devin/skills/dependency-graph/SKILL.md` (new)
+- `.devin/skills/deployment-coordination/SKILL.md` (new)
+- `.devin/skills/skill-creation/SKILL.md` (new)
+- `docs/specs/DEVX-167.md` (new)
+
+## Test Plan
+- Verify all three SKILL.md files follow the required structure (H1
+  title, When to Invoke, Prerequisites sections)
+- Verify referenced make targets and file paths exist
+- Run `make pytest-cov` — skill validation tests must pass
+
+## Deploy Plan
+- Merge to master; skills are consumed by agents immediately on next
+  invocation — no build or deploy step required
+
+## Rollback Plan
+- Revert the merge commit; remove the three skill directories
+
+## Acceptance Criteria
+- [x] REQ-1: dependency-graph skill exists with ecosystem map, repo
+      table, dependency chain, cross-repo change order, and state
+      verification checklist
+- [x] REQ-2: deployment-coordination skill exists with devx release
+      flow, downstream consumer table, coordination steps, and common
+      mistakes
+- [x] REQ-3: skill-creation skill exists with structure template,
+      quality standards, scope rules, validation reference, and
+      creation checklist

docs/specs/DEVX-167.md

@@ -1,64 +1,57 @@
-# DEVX-167: Add dependency-graph, deployment-coordination, and skill-creation skills
+# DEVX-167: S03 artifact integrity — verify producer artifact + cleanup protection
 
 ## Problem
-Agents working across the oblachno ecosystem lack shared, persistent
-context for three recurring pain points:
 
-1. **Cross-repo dependency ordering** — agents frequently merge
-   downstream PRs before the upstream publish job completes, or forget
-   to bump infra. There is no single reference for which repo produces
-   what and in what order changes must propagate.
-2. **devx release coordination** — devx is the base package pinned by
-   grm, sso-bridge, and infra. Agents repeatedly merge devx PRs and
-   immediately merge downstream bumps without waiting for the PyPI
-   publish job, or bump only one consumer when a change affects all
-   three.
-3. **Skill quality drift** — skills are created ad hoc with inconsistent
-   structure, vague advice, and no automated validation reference. New
-   skills miss required sections, reference nonexistent make targets,
-   and drift across repos.
+S03 (OBL-INFRA-548 REQ-3) requires that dependency PRs only open after
+the producer artifact exists and is content-addressable, and that
+registry cleanup never deletes a version pinned by a release manifest.
+Two gaps:
+
+1. `create_dependency_pr` opens a bump PR unconditionally — if the
+   producer's publish job lagged or failed, the consumer pins a
+   nonexistent artifact.
+2. The sso-bridge image tag is derived from `__init__.py.__version__`,
+   which does not always equal the release git tag, so the tag to
+   verify must be decoupled from `--new-version`.
 
 ## Approach
-Add three SKILL.md files under `.devin/skills/`:
 
-REQ-1: `dependency-graph` — shared skill mapping the oblachno ecosystem
-(repos, what each produces, consumers, release triggers, correct
-cross-repo change order, state verification checklist)
+REQ-1: `create_dependency_pr` gains `--verify-container <owner/name>`
+and `--container-tag <tag>`: before any branch/PR work it resolves the
+OCI digest of the image tag via the Gitea packages API (`manifest.json`
+blob sha256) and refuses the PR when the artifact is missing or
+unreadable. `--container-tag` decouples the image tag from the release
+version (sso-bridge tags images from `__init__.py.__version__`, not the
+git tag).
 
-REQ-2: `deployment-coordination` — devx-specific skill covering the
-devx release flow, downstream consumers, manual bump procedure, and
-common mistakes when coordinating a devx change
-
-REQ-3: `skill-creation` — shared skill defining skill structure,
-quality standards, scope rules, automated validation reference, and a
-creation checklist
+REQ-2: Regression tests cover digest resolution, verification-failure
+aborts, invalid container format, and the `--container-tag` override.
 
 ## Files Affected
-- `.devin/skills/dependency-graph/SKILL.md` (new)
-- `.devin/skills/deployment-coordination/SKILL.md` (new)
-- `.devin/skills/skill-creation/SKILL.md` (new)
-- `docs/specs/DEVX-167.md` (new)
+
+- `src/devx/ci/create_dependency_pr.py`
+- `src/devx/translations.json`
+- `tests/unit/test_create_dependency_pr.py`
 
 ## Test Plan
-- Verify all three SKILL.md files follow the required structure (H1
-  title, When to Invoke, Prerequisites sections)
-- Verify referenced make targets and file paths exist
-- Run `make pytest-cov` — skill validation tests must pass
+
+- Unit tests for `resolve_container_digest` (digest from manifest blob,
+  missing tag, missing blob, connection error).
+- CLI tests: verify runs before version lookup, digest resolution,
+  invalid format rejection, container-tag override.
 
 ## Deploy Plan
-- Merge to master; skills are consumed by agents immediately on next
-  invocation — no build or deploy step required
+
+Merge via auto-merge after green CI. Producer post-merge workflows adopt
+the new flags in their own PRs (sso-bridge SSO-22 already passes them).
 
 ## Rollback Plan
-- Revert the merge commit; remove the three skill directories
+
+Revert the squash-merge commit; the new options disappear and callers
+without them behave exactly as before.
 
 ## Acceptance Criteria
-- [x] REQ-1: dependency-graph skill exists with ecosystem map, repo
-      table, dependency chain, cross-repo change order, and state
-      verification checklist
-- [x] REQ-2: deployment-coordination skill exists with devx release
-      flow, downstream consumer table, coordination steps, and common
-      mistakes
-- [x] REQ-3: skill-creation skill exists with structure template,
-      quality standards, scope rules, validation reference, and
-      creation checklist
+
+- [x] REQ-1: pre-PR OCI digest verification with --verify-container/--container-tag
+- [x] REQ-2: regression tests for all new behavior
+

docs/specs/DEVX-168.md

@@ -0,0 +1,35 @@
+# DEVX-168: Fix create_dependency_pr master-ref parsing
+
+## Problem
+
+`devx.ci.create_dependency_pr` crashes with
+`AttributeError: 'list' object has no attribute 'get'` when creating the
+dependency branch. Gitea's `GET /repos/{o}/{r}/git/refs/heads/master`
+returns a JSON **array** of matching refs, not a single object. Observed
+in production when sso-bridge v0.4.1's post-merge dep-PR step ran.
+
+## Approach
+
+REQ-1: Normalize the ref response — if it is a list, select the entry
+whose `ref` field equals `refs/heads/master` or fall back to the first
+entry; proceed to extract `object.sha` as before. An empty or absent
+SHA still fails closed.
+
+## Test Plan
+
+- Unit test: list-shaped response resolves SHA and creates the PR.
+- Unit test: empty list fails with the master-SHA error message.
+
+## Deploy Plan
+
+devx releases as a version tag; sso-bridge/infra pin bumps pick it up via
+their normal dep-PR flow.
+
+## Rollback Plan
+
+Revert the commit; dep-PR creation stays broken on Gitea (status quo).
+
+## Acceptance Criteria
+
+- [x] REQ-1: list-shaped ref response is handled; SHA extraction works;
+  empty list still errors. Covered by unit tests at 100% coverage.

docs/specs/DEVX-169.md

@@ -0,0 +1,33 @@
+# DEVX-169: create_dependency_pr uses branches API
+
+## Problem
+
+After DEVX-168, dep-PR creation fails at `POST /git/refs` with
+`HTTP 405 Method Not Allowed` — this Gitea version does not implement the
+createRef endpoint. Observed creating the sso_bridge 0.4.1 infra
+dependency PR.
+
+## Approach
+
+REQ-1: Create the dependency branch via `POST /branches` with
+`new_branch_name`/`old_branch_name` (from master). An already-exists
+error is tolerated; other API errors fail closed.
+
+## Test Plan
+
+- Branch creation calls `POST /branches` with the expected payload.
+- 422 already-exists is tolerated and the PR is still created.
+- Other API errors abort with a branch-creation failure.
+
+## Deploy Plan
+
+devx release tag; producers pick it up via pin bumps.
+
+## Rollback Plan
+
+Revert; dep-PR creation stays broken (status quo).
+
+## Acceptance Criteria
+
+- [x] REQ-1: branch creation uses the branches API; already-exists
+  tolerated; failures surface. Covered by unit tests at 100% coverage.

docs/specs/DEVX-170.md

@@ -0,0 +1,33 @@
+# DEVX-170: create_dependency_pr checks out the API-created branch
+
+## Problem
+
+After DEVX-169 the dependency branch is created via `POST /branches`, but
+`git fetch origin <branch>` only populates `FETCH_HEAD`. The follow-up
+`git checkout <branch>` fails silently (`check=False`), commits land on
+the wrong ref, and `git push origin <branch>` fails with
+`src refspec does not match any`. Observed creating the sso_bridge 0.4.1
+infra dependency PR.
+
+## Approach
+
+REQ-1: Fetch the API-created branch into `refs/remotes/origin/<branch>`
+and force-create the local branch with `git checkout -B <branch>
+origin/<branch>`, both with `check=True` so failures surface.
+
+## Test Plan
+
+- Unit test asserts the fetch refspec and `checkout -B` invocations.
+
+## Deploy Plan
+
+devx release tag; producers pick it up via pin bumps.
+
+## Rollback Plan
+
+Revert; dep-PR creation stays broken (status quo).
+
+## Acceptance Criteria
+
+- [x] REQ-1: the clone checks out the API-created branch so commit and
+  push target `deps/<pkg>-<version>`; covered by unit tests.

docs/specs/DEVX-171.md

@@ -0,0 +1,36 @@
+# DEVX-171: create_dependency_pr uses target-project task ID + generated spec
+
+## Problem
+
+Dep PRs fail target-repo validation: infra requires `OBL-INFRA-N` in the
+branch name and `docs/specs/<TASK>.md` in the diff. The tool created the
+Vikunja task in the *producer's* project and named the branch
+`deps/<pkg>-<ver>` with no task ID, and wrote no spec.
+
+## Approach
+
+REQ-1: Create the tracking task before branch creation, in the target
+repo's Vikunja project via `--task-project-id` (default:
+DEVX_VIKUNJA_PROJECT_ID). Embed the returned identifier in the branch
+name (`deps/<TASK>-<pkg>-<ver>`) and PR title, and commit a generated
+`docs/specs/<TASK>.md` with the required sections alongside the pin bump.
+
+## Test Plan
+
+- Branch name and PR title carry the target task ID; spec file added.
+- `create_vikunja_task(project_id=N)` passes N to VikunjaClient.
+- Existing no-task behavior preserved when Vikunja is unreachable.
+
+## Deploy Plan
+
+devx release tag; producer workflows pass `--task-project-id` for infra
+(project 3).
+
+## Rollback Plan
+
+Revert; dep PRs keep failing target validation (status quo).
+
+## Acceptance Criteria
+
+- [x] REQ-1: `--task-project-id` supported; branch/spec/PR title embed
+  the target task ID; covered by unit tests at 100% coverage.

docs/specs/DEVX-172.md

@@ -0,0 +1,32 @@
+# DEVX-172: dep-PR retries container verification until publish lands
+
+## Problem
+
+Post-merge dep-PR runs concurrently with the producer's image-build
+workflow. `--verify-container` hits HTTP 404 before the push lands and
+skips PR creation — observed for sso-bridge v0.4.1 and v0.4.3.
+
+## Approach
+
+REQ-1: `resolve_container_digest(..., timeout_s)` retries a 404 lookup
+every 15s until the deadline.
+REQ-2: `--verify-timeout` CLI option (default 600s, 0 disables) wires the
+retry into the dep-PR step.
+
+## Test Plan
+
+- Unit test: 404-then-200 resolves the digest without raising.
+- Existing no-retry path (timeout_s=0) still fails immediately.
+
+## Deploy Plan
+
+devx release tag; producers inherit the 600s default on next pin bump.
+
+## Rollback Plan
+
+Revert; dep-PR verification fails fast on 404 again (status quo).
+
+## Acceptance Criteria
+
+- [x] REQ-1: 404 responses retry until `timeout_s` deadline.
+- [x] REQ-2: `--verify-timeout` option exposed, default 600.

docs/specs/DEVX-173.md

@@ -0,0 +1,49 @@
+# DEVX-173: Resolve container digest via registry v2 API
+
+## Problem
+
+`resolve_container_digest` returns the sha256 of the `manifest.json`
+blob listed by the Gitea packages API (`/packages/<owner>/container/
+<name>/<tag>/files`). That blob digest is NOT the OCI manifest digest —
+`docker pull repo@sha256:<blob>` fails with "not found." Production
+deploy run 6251 died pulling `sso-bridge@sha256:5ca9...` which the dep
+PR had recorded in `deploy/sso-bridge-release.json`. The registry serves
+0.4.1 as `sha256:c0212ed1...` — different digest entirely.
+
+## Approach
+
+REQ-1: Keep the packages-API call as the existence check (it has the
+404-retry semantics needed for the publish race) but resolve the
+pullable digest via the registry v2 API: `GET /v2/token` with
+`scope=repository:<owner>/<name>:pull` (basic-auth with the Gitea
+token), then `GET /v2/<owner>/<name>/manifests/<tag>` with OCI/Docker
+manifest Accept headers and read `Docker-Content-Digest`. Registry base
+URL is derived from `GITEA_API_URL` (strip `/api/v1`).
+
+REQ-2: If the v2 digest lookup fails (non-2xx, missing header), fail
+closed with a ClickException — never record a blob sha256 as a pullable
+digest.
+
+## Test Plan
+
+- Mocked v2 token + manifest endpoints return digest; recorded value is
+  the `Docker-Content-Digest` header.
+- 404 retry semantics on the packages-API existence check unchanged.
+- Missing digest header / non-2xx manifest response → ClickException.
+- Unit tests cover token request scope and Accept headers.
+
+## Deploy Plan
+
+devx release tag; the sso-bridge dep-PR pin bump follows in its own PR.
+The wrong digest already recorded in infra's manifest is corrected by
+re-running the dep-PR with the fixed version.
+
+## Rollback Plan
+
+Revert; dep-PR records the (unpullable) blob digest again — deploys must
+then use tag pulls until a corrected manifest lands.
+
+## Acceptance Criteria
+
+- [x] REQ-1: Digest resolved from `Docker-Content-Digest` via v2 API.
+- [x] REQ-2: Lookup failures fail closed; no blob-sha256 fallback.

docs/specs/DEVX-174.md

@@ -0,0 +1,31 @@
+# DEVX-174: Set git identity in dep-PR target clone
+
+## Problem
+
+`create_dependency_pr` commits the manifest bump in a fresh clone of the
+target repo. The clone has no `user.name`/`user.email`, so `git commit`
+exits 128 ("Please tell me who you are") — observed in sso-bridge
+post-merge run 6284 after the digest and manifest bump both succeeded.
+
+## Approach
+
+REQ-1: Pass a CI bot identity inline (`git -c user.name=... -c
+user.email=... commit`) so the commit works in any environment without
+mutating global git config.
+
+## Test Plan
+
+- Unit test asserting the commit invocation carries `-c user.name` /
+  `-c user.email` arguments.
+
+## Deploy Plan
+
+devx release; sso-bridge picks it up via its devx pin on next bump.
+
+## Rollback Plan
+
+Revert; dep-PR commit fails again in containers without git identity.
+
+## Acceptance Criteria
+
+- [x] REQ-1: dep-PR commit supplies explicit identity flags.

docs/user/getting-started.md

@@ -48,12 +48,12 @@ Add devx to your `pyproject.toml`:
 ```toml
 [project]
 dependencies = [
-    "devx>=0.51.10",
+    "devx>=0.55.2",
 ]
 
 [project.optional-dependencies]
 dev = [
-    "devx>=0.51.10",
+    "devx>=0.55.2",
 ]
 ```
 

src/devx/__init__.py

@@ -6,4 +6,4 @@ create_dependency_pr, auto_merge, release, publish), developer tooling
 molecule testing helpers for Ansible projects.
 """
 
-__version__ = "0.51.10"
+__version__ = "0.55.2"

src/devx/ci/create_dependency_pr.py

@@ -21,6 +21,8 @@ from __future__ import annotations
 
 import re
 import subprocess  # nosec B404
+import tempfile
+import time
 from datetime import UTC, datetime
 from pathlib import Path
 
@@ -94,53 +96,108 @@ def update_pinned_version(file_path: str, package: str, old_version: str, new_ve
     return changed
 
 
-def resolve_container_digest(api_url: str, owner: str, name: str, tag: str, token: str) -> str:
-    """Resolve the OCI digest for a container image tag via the packages API.
+_MANIFEST_ACCEPT = (
+    "application/vnd.oci.image.index.v1+json, "
+    "application/vnd.docker.distribution.manifest.list.v2+json, "
+    "application/vnd.oci.image.manifest.v1+json, "
+    "application/vnd.docker.distribution.manifest.v2+json"
+)
 
-    Implements REQ-1: dependency PRs must only be opened after the producer
-    artifact exists — this raises ClickException when the tag is missing or
-    the registry call fails, so the PR is never opened against an artifact
-    that has not been published. The sha256 of the stored ``manifest.json``
-    blob is the manifest content digest (what ``docker pull`` reports).
+
+# Implements: REQ-1 — existence check via packages API (keeps the 404-retry
+# semantics for the publish race); the pullable digest is then resolved via
+# the registry v2 API's Docker-Content-Digest header.
+def resolve_container_digest(api_url: str, owner: str, name: str, tag: str, token: str, timeout_s: int = 0) -> str:
+    """Verify the container tag exists, then resolve its pullable OCI digest.
+
+    The packages API proves the tag was published (and 404s while the
+    producer's image-build workflow races us — ``timeout_s`` retries every
+    15s). The packages-API ``manifest.json`` blob sha256 is NOT pullable
+    via ``repo@sha256:...``, so the digest comes from the registry v2
+    ``Docker-Content-Digest`` header instead.
     """
     url = f"{api_url}/packages/{owner}/container/{name}/{tag}/files"
     headers = {"Authorization": f"token {token}"}
+    deadline = time.monotonic() + timeout_s
+    while True:
+        try:
+            resp = requests.get(url, headers=headers, timeout=30)  # nosec B310
+            resp.raise_for_status()
+        except requests.HTTPError as e:
+            if e.response is not None and e.response.status_code == 404 and time.monotonic() < deadline:
+                click.echo(
+                    _(
+                        "[dep-pr] {owner}/{name}:{tag} not published yet — retrying.",
+                        owner=owner,
+                        name=name,
+                        tag=tag,
+                    )
+                )
+                time.sleep(15)
+                continue
+            status = e.response.status_code if e.response is not None else "?"
+            raise click.ClickException(
+                _(
+                    "Container artifact {owner}/{name}:{tag} not found or unreadable (HTTP {status}). "
+                    "Refusing to open a dependency PR for an unpublished artifact.",
+                    owner=owner,
+                    name=name,
+                    tag=tag,
+                    status=status,
+                )
+            ) from e
+        except requests.RequestException as e:
+            raise click.ClickException(
+                _(
+                    "Registry lookup failed for {owner}/{name}:{tag}: {error}",
+                    owner=owner,
+                    name=name,
+                    tag=tag,
+                    error=e,
+                )
+            ) from e
+        break
+    return _resolve_registry_digest(api_url, owner, name, tag, token)
+
+
+# Implements: REQ-2 — v2 digest resolution fails closed: non-2xx, missing
+# token, or absent Docker-Content-Digest all raise; a blob sha256 is never
+# recorded as a pullable digest.
+def _resolve_registry_digest(api_url: str, owner: str, name: str, tag: str, token: str) -> str:
+    registry = api_url.removesuffix("/api/v1").removesuffix("/")
+    repo = f"{owner}/{name}"
     try:
-        resp = requests.get(url, headers=headers, timeout=30)  # nosec B310
-        resp.raise_for_status()
-    except requests.HTTPError as e:
-        status = e.response.status_code if e.response is not None else "?"
+        tok_resp = requests.get(  # nosec B310
+            f"{registry}/v2/token",
+            params={"service": "container_registry", "scope": f"repository:{repo}:pull"},
+            auth=("ci", token),
+            timeout=30,
+        )
+        tok_resp.raise_for_status()
+        bearer = tok_resp.json().get("token", "")
+        man_resp = requests.get(  # nosec B310
+            f"{registry}/v2/{repo}/manifests/{tag}",
+            headers={"Authorization": f"Bearer {bearer}", "Accept": _MANIFEST_ACCEPT},
+            timeout=30,
+        )
+        man_resp.raise_for_status()
+    except requests.RequestException as e:
+        status = getattr(getattr(e, "response", None), "status_code", "?")
         raise click.ClickException(
             _(
-                "Container artifact {owner}/{name}:{tag} not found or unreadable (HTTP {status}). "
-                "Refusing to open a dependency PR for an unpublished artifact.",
-                owner=owner,
-                name=name,
+                "Registry v2 digest lookup failed for {repo}:{tag} (HTTP {status}): {error}",
+                repo=repo,
                 tag=tag,
                 status=status,
-            )
-        ) from e
-    except requests.RequestException as e:
-        raise click.ClickException(
-            _(
-                "Registry lookup failed for {owner}/{name}:{tag}: {error}",
-                owner=owner,
-                name=name,
-                tag=tag,
                 error=e,
             )
         ) from e
-    for f in resp.json():
-        if f.get("name") == "manifest.json" and f.get("sha256"):
-            return f"sha256:{f['sha256']}"
-    raise click.ClickException(
-        _(
-            "Registry returned no manifest blob for {owner}/{name}:{tag}.",
-            owner=owner,
-            name=name,
-            tag=tag,
+    digest = man_resp.headers.get("Docker-Content-Digest", "")
+    if not digest:
+        raise click.ClickException(
+            _("Registry returned no Docker-Content-Digest for {repo}:{tag}.", repo=repo, tag=tag)
         )
-    )
+    return digest
 
 
 def update_manifest(file_path: str, section: str, fields: dict[str, str]) -> bool:
@@ -191,7 +248,7 @@ def read_manifest_version(file_path: str, section: str) -> str | None:
     return None
 
 
-def create_vikunja_task(title: str, description: str) -> str | None:
+def create_vikunja_task(title: str, description: str, project_id: int = 0) -> str | None:
     """Create a Vikunja task and return its identifier (e.g., OBL-INFRA-531)."""
     try:
         token = get_vikunja_token()
@@ -201,7 +258,7 @@ def create_vikunja_task(title: str, description: str) -> str | None:
     from devx.api_clients import VikunjaClient
 
     client = VikunjaClient(VIKUNJA_API_URL, token)
-    task = client.create_task(VIKUNJA_PROJECT_ID, title=title, description=description)
+    task = client.create_task(project_id or VIKUNJA_PROJECT_ID, title=title, description=description)
     return str(task.get("identifier", ""))
 
 
@@ -242,6 +299,24 @@ def create_vikunja_task(title: str, description: str) -> str | None:
         "__version__ tag vs a release git tag."
     ),
 )
+@click.option(
+    "--verify-timeout",
+    type=int,
+    default=600,
+    help=_(
+        "Seconds to keep retrying --verify-container while the artifact returns 404 "
+        "(the image build races this step). 0 disables retries."
+    ),
+)
+@click.option(
+    "--task-project-id",
+    type=int,
+    default=0,
+    help=_(
+        "Vikunja project for the tracking task (default: DEVX_VIKUNJA_PROJECT_ID). "
+        "Use the target repo's project so the generated branch/spec satisfy its validation."
+    ),
+)
 @click.option("--dry-run", is_flag=True, default=False, help=_("Show what would be done without creating PR"))
 def cli(
     repo: str,
@@ -253,6 +328,8 @@ def cli(
     verify_container: str,
     source_ref: str,
     container_tag: str,
+    verify_timeout: int,
+    task_project_id: int,
     dry_run: bool,
 ) -> None:
     """Create an infra PR to bump a pinned dependency version."""
@@ -272,7 +349,7 @@ def cli(
             )
         c_owner, c_name = verify_container.split("/", 1)
         image_tag = container_tag or new_version
-        image_digest = resolve_container_digest(GITEA_API_URL, c_owner, c_name, image_tag, token)
+        image_digest = resolve_container_digest(GITEA_API_URL, c_owner, c_name, image_tag, token, verify_timeout)
         click.echo(
             _(
                 "[dep-pr] Verified {container}:{version} -> {digest}",
@@ -283,10 +360,8 @@ def cli(
         )
 
     # Clone the target repo — this tool runs from the *producer* repo's CI,
-    # so every file lookup and git operation must happen in a clone of the
-    # target repo, not the producer checkout in CWD.
-    import tempfile
-
+    # so every file lookup and git operation must happen inside a clone of
+    # the target repo, not the producer checkout in CWD.
     workdir = Path(tempfile.mkdtemp(prefix="dep-pr-"))
     clone_url = f"{GITEA_API_URL.removesuffix('/api/v1')}/{repo}.git"
     auth_cfg = f"http.extraHeader=Authorization: token {token}"
@@ -333,8 +408,20 @@ def cli(
         click.echo(f"[dep-pr] DRY RUN: would update {changed_file} and create PR")
         return
 
-    # Create a branch
-    branch_name = f"deps/{package}-{new_version}"
+    # Implements: REQ-1 — create the tracking task in the *target* repo's
+    # Vikunja project so its identifier satisfies the target's branch/PR-title
+    # validation (e.g., OBL-INFRA-N for oblachno/infra).
+    task_title = f"Bump {package} to {new_version}"
+    task_desc = (
+        f"<p>Auto-created dependency bump PR.</p>"
+        f"<p>Package: {package}</p>"
+        f"<p>Version: {old_version} → {new_version}</p>"
+        f"<p>Source: {source_repo} (run #{source_run_id})</p>"
+    )
+    task_id = create_vikunja_task(task_title, task_desc, task_project_id)
+
+    # Create a branch — embed the task ID so target-repo validation accepts it.
+    branch_name = f"deps/{task_id}-{package}-{new_version}" if task_id else f"deps/{package}-{new_version}"
     base_branch = "master"
 
     # Check for existing PR (reuse from tools.create_pr)
@@ -345,20 +432,34 @@ def cli(
 
     # Create branch via API
     try:
-        master_ref = client._request("GET", "/git/refs/heads/master").json()
-        master_sha = master_ref.get("object", {}).get("sha", "")
-        if not master_sha:
-            raise click.ClickException("Could not get master SHA")
-        client._request("POST", "/git/refs", json={"ref": f"refs/heads/{branch_name}", "sha": master_sha})
+        # Implements: REQ-1 — Gitea lacks POST /git/refs; create the branch
+        # from master via the branches API.
+        client._request(
+            "POST",
+            "/branches",
+            json={"new_branch_name": branch_name, "old_branch_name": base_branch},
+        )
     except APIError as e:
         if "already exists" in str(e).lower():
             click.echo(f"[dep-pr] Branch {branch_name} already exists")
         else:
             raise click.ClickException(_("Failed to create branch: {error}", error=str(e))) from None
 
-    # Check out the API-created branch inside the target clone.
-    subprocess.run(["git", "fetch", "origin", f"{branch_name}"], check=False, capture_output=True, cwd=workdir)  # nosec B603 B607
-    subprocess.run(["git", "checkout", branch_name], check=False, capture_output=True, cwd=workdir)  # nosec B603 B607
+    # Check out the API-created branch inside the target clone. A plain
+    # fetch only populates FETCH_HEAD — fetch into the remote-tracking ref
+    # and force-create the local branch from it.
+    subprocess.run(  # nosec B603 B607
+        ["git", "fetch", "origin", f"{branch_name}:refs/remotes/origin/{branch_name}"],
+        check=True,
+        capture_output=True,
+        cwd=workdir,
+    )
+    subprocess.run(  # nosec B603 B607
+        ["git", "checkout", "-B", branch_name, f"origin/{branch_name}"],
+        check=True,
+        capture_output=True,
+        cwd=workdir,
+    )
 
     if manifest_path:
         fields = {
@@ -377,25 +478,55 @@ def cli(
         raise click.ClickException(_("Failed to update {file}", file=changed_file))
 
     assert changed_file is not None  # nosec B101 — narrowed by the early exit above
-    subprocess.run(["git", "add", changed_file], check=True, cwd=workdir)  # nosec B603 B607
+    add_files = [changed_file]
+    if task_id:
+        # Implements: REQ-1 — spec-driven validation requires a spec file.
+        spec_rel = f"docs/specs/{task_id}.md"
+        spec_file = workdir / spec_rel
+        spec_file.parent.mkdir(parents=True, exist_ok=True)
+        spec_file.write_text(
+            f"# {task_id}: {task_title}\n\n"
+            f"## Problem\n\n"
+            f"{source_repo} released {package} {new_version}; this repo pins {old_version}.\n\n"
+            f"## Approach\n\n"
+            f"REQ-1: Update `{changed_file}` to pin {package} {new_version} "
+            f"(auto-generated dependency PR).\n\n"
+            f"## Test Plan\n\n"
+            f"- Producer release CI verified the artifact "
+            f"({source_repo} run #{source_run_id or 'n/a'}).\n\n"
+            f"## Deploy Plan\n\n"
+            f"Merge updates the pin; the next deploy applies it.\n\n"
+            f"## Rollback Plan\n\n"
+            f"Revert the pin bump.\n\n"
+            f"## Acceptance Criteria\n\n"
+            f"- [x] REQ-1: `{changed_file}` pins {package} {new_version}.\n",
+            encoding="utf-8",
+        )
+        add_files.append(spec_rel)
+    subprocess.run(["git", "add", *add_files], check=True, cwd=workdir)  # nosec B603 B607
     commit_msg = f"deps: bump {package} from {old_version} to {new_version}"
-    subprocess.run(["git", "commit", "-m", commit_msg], check=True, cwd=workdir)  # nosec B603 B607
+    # Implements: REQ-1 — the fresh clone has no git identity in CI
+    # containers; supply it inline (same bot identity as push_badges).
+    subprocess.run(  # nosec B603 B607
+        [
+            "git",
+            "-c",
+            "user.name=gitea-actions-bot",
+            "-c",
+            "user.email=actions@oblachno.fyi",
+            "commit",
+            "-m",
+            commit_msg,
+        ],
+        check=True,
+        cwd=workdir,
+    )
     subprocess.run(  # nosec B603 B607
         ["git", "-c", auth_cfg, "push", "origin", branch_name],
         check=True,
         cwd=workdir,
     )
 
-    # Create Vikunja task for tracking
-    task_title = f"Bump {package} to {new_version}"
-    task_desc = (
-        f"<p>Auto-created dependency bump PR.</p>"
-        f"<p>Package: {package}</p>"
-        f"<p>Version: {old_version} → {new_version}</p>"
-        f"<p>Source: {source_repo} (run #{source_run_id})</p>"
-    )
-    task_id = create_vikunja_task(task_title, task_desc)
-
     # Create PR directly (dependency PRs have custom titles, not Vikunja-derived)
     pr_title = f"{task_id}: {task_title}" if task_id else task_title
     pr_body = (

src/devx/translations.json

@@ -2967,13 +2967,21 @@
     "ru": "Ошибка поиска в реестре для {owner}/{name}:{tag}: {error}",
     "zh": "注册表查询 {owner}/{name}:{tag} 失败：{error}"
   },
-  "Registry returned no manifest blob for {owner}/{name}:{tag}.": {
-    "bg": "Регистърът не върна manifest blob за {owner}/{name}:{tag}.",
-    "de": "Registry hat keinen Manifest-Blob für {owner}/{name}:{tag} zurückgegeben.",
-    "en": "Registry returned no manifest blob for {owner}/{name}:{tag}.",
-    "pl": "Rejestr nie zwrócił blobu manifestu dla {owner}/{name}:{tag}.",
-    "ru": "Реестр не вернул blob манифеста для {owner}/{name}:{tag}.",
-    "zh": "注册表未返回 {owner}/{name}:{tag} 的清单 blob。"
+  "Registry returned no Docker-Content-Digest for {repo}:{tag}.": {
+    "bg": "Регистърът не върна Docker-Content-Digest за {repo}:{tag}.",
+    "de": "Registry hat keinen Docker-Content-Digest für {repo}:{tag} zurückgegeben.",
+    "en": "Registry returned no Docker-Content-Digest for {repo}:{tag}.",
+    "pl": "Rejestr nie zwrócił Docker-Content-Digest dla {repo}:{tag}.",
+    "ru": "Реестр не вернул Docker-Content-Digest для {repo}:{tag}.",
+    "zh": "注册表未返回 {repo}:{tag} 的 Docker-Content-Digest。"
+  },
+  "Registry v2 digest lookup failed for {repo}:{tag} (HTTP {status}): {error}": {
+    "bg": "Неуспешна заявка за дайджест към регистър v2 за {repo}:{tag} (HTTP {status}): {error}",
+    "de": "Registry-v2-Digest-Abfrage für {repo}:{tag} fehlgeschlagen (HTTP {status}): {error}",
+    "en": "Registry v2 digest lookup failed for {repo}:{tag} (HTTP {status}): {error}",
+    "pl": "Zapytanie o skrót do rejestru v2 dla {repo}:{tag} nie powiodło się (HTTP {status}): {error}",
+    "ru": "Ошибка запроса дайджеста к реестру v2 для {repo}:{tag} (HTTP {status}): {error}",
+    "zh": "注册表 v2 摘要查询 {repo}:{tag} 失败 (HTTP {status})：{error}"
   },
   "Regular merge commit — running all post-merge jobs.": {
     "bg": "Обикновен merge комит — изпълняват се всички post-merge задачи.",
@@ -3159,6 +3167,14 @@
     "ru": "SSH_PRIVATE_KEY не задан — пропуск настройки SSH-ключа",
     "zh": "SSH_PRIVATE_KEY 未设置 — 跳过 SSH 密钥设置"
   },
+  "Seconds to keep retrying --verify-container while the artifact returns 404 (the image build races this step). 0 disables retries.": {
+    "bg": "Секунди за повторни опити на --verify-container, докато артефактът връща 404 (компилацията на изображението е конкурентна). 0 изключва повторните опити.",
+    "de": "Sekunden, die --verify-container bei HTTP 404 weiter versucht wird (der Image-Build läuft parallel). 0 deaktiviert Wiederholungen.",
+    "en": "Seconds to keep retrying --verify-container while the artifact returns 404 (the image build races this step). 0 disables retries.",
+    "pl": "Sekundy ponawiania --verify-container, gdy artefakt zwraca 404 (budowa obrazu jest współbieżna). 0 wyłącza ponawianie.",
+    "ru": "Секунды повторных попыток --verify-container, пока артефакт возвращает 404 (сборка образа идёт параллельно). 0 отключает повторы.",
+    "zh": "当构件返回 404 时 --verify-container 的重试秒数（镜像构建与此步骤并行）。0 禁用重试。"
+  },
   "Show what would be done without creating PR": {
     "bg": "Покажи какво би било направено без създаване на PR",
     "de": "Zeigen, was getan würde, ohne PR zu erstellen",
@@ -3495,6 +3511,14 @@
     "ru": "Ошибка Vikunja API (HTTP {status}): {message}. Задача {task_id} НЕ была обновлена. Слияние прошло успешно, но задачу Vikunja нужно обновить вручную.",
     "zh": "Vikunja API 错误（HTTP {status}）：{message}。任务 {task_id} 未更新。合并成功，但 Vikunja 任务需要手动更新。"
   },
+  "Vikunja project for the tracking task (default: DEVX_VIKUNJA_PROJECT_ID). Use the target repo's project so the generated branch/spec satisfy its validation.": {
+    "bg": "Vikunja проект за задачата за проследяване (по подразбиране: DEVX_VIKUNJA_PROJECT_ID). Използвайте проекта на целевото хранилище, за да отговарят генерираните клон/спецификация на неговата валидация.",
+    "de": "Vikunja-Projekt für die Tracking-Aufgabe (Standard: DEVX_VIKUNJA_PROJECT_ID). Verwenden Sie das Projekt des Ziel-Repos, damit generierter Branch/Spec dessen Validierung bestehen.",
+    "en": "Vikunja project for the tracking task (default: DEVX_VIKUNJA_PROJECT_ID). Use the target repo's project so the generated branch/spec satisfy its validation.",
+    "pl": "Projekt Vikunja dla zadania śledzącego (domyślnie: DEVX_VIKUNJA_PROJECT_ID). Użyj projektu docelowego repozytorium, aby wygenerowana gałąź/specyfikacja przeszła jego walidację.",
+    "ru": "Проект Vikunja для задачи отслеживания (по умолчанию: DEVX_VIKUNJA_PROJECT_ID). Используйте проект целевого репозитория, чтобы сгенерированные ветка/спецификация прошли его валидацию.",
+    "zh": "用于跟踪任务的 Vikunja 项目（默认：DEVX_VIKUNJA_PROJECT_ID）。使用目标仓库的项目，以便生成的分支/规范通过其验证。"
+  },
   "Vikunja task title '{title}' starts with '{prefix}:'. The task title should NOT include the '{prefix}' prefix — it is automatically added to the PR title. Update the Vikunja task title to remove the prefix.": {
     "bg": "Заглавието на задачата във Vikunja '{title}' започва с '{prefix}:'. Заглавието на задачата НЕ трябва да съдържа префикса '{prefix}' — той се добавя автоматично към заглавието на PR. Актуализирайте заглавието на задачата във Vikunja, за да премахнете префикса.",
     "de": "Der Vikunja-Aufgabentitel '{title}' beginnt mit '{prefix}:'. Der Aufgabentitel darf NICHT den Präfix '{prefix}' enthalten — er wird automatisch zum PR-Titel hinzugefügt. Aktualisieren Sie den Vikunja-Aufgabentitel, um den Präfix zu entfernen.",
@@ -3823,6 +3847,14 @@
     "ru": "[dep-pr] Проверено {container}:{version} -> {digest}",
     "zh": "[dep-pr] 已验证 {container}:{version} -> {digest}"
   },
+  "[dep-pr] {owner}/{name}:{tag} not published yet — retrying.": {
+    "bg": "[dep-pr] {owner}/{name}:{tag} още не е публикуван — повторен опит.",
+    "de": "[dep-pr] {owner}/{name}:{tag} noch nicht veröffentlicht — neuer Versuch.",
+    "en": "[dep-pr] {owner}/{name}:{tag} not published yet — retrying.",
+    "pl": "[dep-pr] {owner}/{name}:{tag} jeszcze nie opublikowano — ponawianie.",
+    "ru": "[dep-pr] {owner}/{name}:{tag} ещё не опубликован — повторная попытка.",
+    "zh": "[dep-pr] {owner}/{name}:{tag} 尚未发布 — 正在重试。"
+  },
   "[dep-pr] {pkg} already at {version} — no PR needed.": {
     "bg": "[dep-pr] {pkg} вече е на {version} — не е нужен PR.",
     "de": "[dep-pr] {pkg} bereits auf {version} — kein PR nötig.",

tests/unit/test_create_dependency_pr.py

@@ -17,7 +17,7 @@ from devx.ci.create_dependency_pr import (
 
 
 @pytest.fixture(autouse=True)
-def _mock_subprocess() -> MagicMock:
+def _mock_subprocess():
     """Mock subprocess so CLI tests never run a real git clone."""
     with patch("devx.ci.create_dependency_pr.subprocess.run") as m:
         yield m
@@ -189,24 +189,50 @@ class TestCreateVikunjaTask:
             result = create_vikunja_task("Test", "desc")
             assert result == "OBL-INFRA-999"
 
+    def test_explicit_project_id_used(self) -> None:
+        with (
+            patch("devx.ci.create_dependency_pr.get_vikunja_token", return_value="fake-token"),
+            patch("devx.api_clients.VikunjaClient") as mock_client_cls,
+        ):
+            mock_client = mock_client_cls.return_value
+            mock_client.create_task.return_value = {"identifier": "OBL-INFRA-1"}
+            create_vikunja_task("Test", "desc", project_id=3)
+            assert mock_client.create_task.call_args.args[0] == 3
+
+
+def _v2_mocks(digest: str = "sha256:deadbeef") -> list[MagicMock]:
+    """Token + manifest responses for the registry v2 digest lookup."""
+    tok = MagicMock()
+    tok.raise_for_status = MagicMock()
+    tok.json.return_value = {"token": "bearer-tok"}
+    man = MagicMock()
+    man.raise_for_status = MagicMock()
+    man.headers = {"Docker-Content-Digest": digest}
+    return [tok, man]
+
 
 class TestResolveContainerDigest:
-    """REQ-1: pre-PR artifact verification via the packages API."""
+    """REQ-1: existence check via packages API; digest via registry v2."""
 
-    def test_returns_digest_from_manifest_blob(self) -> None:
+    def test_returns_digest_from_registry_v2(self) -> None:
         from devx.ci.create_dependency_pr import resolve_container_digest
 
-        mock_resp = MagicMock()
-        mock_resp.raise_for_status = MagicMock()
-        mock_resp.json.return_value = [
-            {"name": "sha256_layer", "sha256": "abc"},
-            {"name": "manifest.json", "sha256": "deadbeef"},
-        ]
-        with patch("devx.ci.create_dependency_pr.requests.get", return_value=mock_resp):
+        files = MagicMock()
+        files.raise_for_status = MagicMock()
+        files.json.return_value = [{"name": "manifest.json", "sha256": "blob-not-pullable"}]
+        with patch(
+            "devx.ci.create_dependency_pr.requests.get",
+            side_effect=[files, *_v2_mocks()],
+        ) as mock_get:
             digest = resolve_container_digest(
                 "https://git.example.com/api/v1", "oblachno", "sso-bridge", "0.9.1", "tok"
             )
         assert digest == "sha256:deadbeef"
+        man_call = mock_get.call_args_list[2]
+        assert "manifests/0.9.1" in man_call.args[0]
+        assert "oci.image.index" in man_call.kwargs["headers"]["Accept"]
+        tok_call = mock_get.call_args_list[1]
+        assert tok_call.kwargs["params"]["scope"] == "repository:oblachno/sso-bridge:pull"
 
     def test_raises_when_version_missing(self) -> None:
         import requests
@@ -221,14 +247,38 @@ class TestResolveContainerDigest:
             with pytest.raises(click.ClickException, match="unpublished artifact"):
                 resolve_container_digest("https://git.example.com/api/v1", "oblachno", "sso-bridge", "9.9.9", "tok")
 
-    def test_raises_when_no_manifest_blob(self) -> None:
+    def test_raises_when_v2_digest_missing(self) -> None:
         from devx.ci.create_dependency_pr import resolve_container_digest
 
-        mock_resp = MagicMock()
-        mock_resp.raise_for_status = MagicMock()
-        mock_resp.json.return_value = [{"name": "sha256_layer", "sha256": "abc"}]
-        with patch("devx.ci.create_dependency_pr.requests.get", return_value=mock_resp):
-            with pytest.raises(click.ClickException, match="no manifest blob"):
+        files = MagicMock()
+        files.raise_for_status = MagicMock()
+        files.json.return_value = []
+        tok, man = _v2_mocks(digest="")
+        with patch(
+            "devx.ci.create_dependency_pr.requests.get",
+            side_effect=[files, tok, man],
+        ):
+            with pytest.raises(click.ClickException, match="no Docker-Content-Digest"):
+                resolve_container_digest("https://git.example.com/api/v1", "oblachno", "sso-bridge", "0.9.1", "tok")
+
+    def test_raises_when_v2_manifest_request_fails(self) -> None:
+        import requests
+
+        from devx.ci.create_dependency_pr import resolve_container_digest
+
+        files = MagicMock()
+        files.raise_for_status = MagicMock()
+        files.json.return_value = []
+        tok, _ = _v2_mocks()
+        err = requests.HTTPError("500")
+        err.response = MagicMock(status_code=500)
+        man = MagicMock()
+        man.raise_for_status.side_effect = err
+        with patch(
+            "devx.ci.create_dependency_pr.requests.get",
+            side_effect=[files, tok, man],
+        ):
+            with pytest.raises(click.ClickException, match="v2 digest lookup failed"):
                 resolve_container_digest("https://git.example.com/api/v1", "oblachno", "sso-bridge", "0.9.1", "tok")
 
     def test_raises_on_connection_error(self) -> None:
@@ -460,3 +510,179 @@ class TestCliManifestMode:
         assert result.exit_code == 0
         args = mock_digest.call_args[0]
         assert args[1:4] == ("oblachno", "sso-bridge", "0.2.4")
+
+
+class TestBranchCreation:
+    """Branch creation uses the branches API (Gitea lacks POST /git/refs)."""
+
+    def _invoke(self) -> object:
+        runner = CliRunner()
+        return runner.invoke(
+            cli,
+            [
+                "--package",
+                "sso_bridge",
+                "--new-version",
+                "0.9.1",
+                "--source-repo",
+                "oblachno/sso-bridge",
+                "--manifest",
+                "deploy/m.json",
+            ],
+        )
+
+    def _client(self, mock_client_cls: MagicMock) -> MagicMock:
+        client = mock_client_cls.return_value
+        client.create_pr.return_value = {"number": 1}
+        return client
+
+    @patch("devx.ci.create_dependency_pr.create_vikunja_task", return_value=None)
+    @patch("devx.ci.create_dependency_pr.update_manifest", return_value=True)
+    @patch("devx.ci.create_dependency_pr.read_manifest_version", return_value="0.9.0")
+    @patch("devx.ci.create_dependency_pr.find_existing_pr", return_value=None)
+    @patch("devx.ci.create_dependency_pr.GiteaClient")
+    @patch("devx.ci.create_dependency_pr.get_ci_token", return_value="tok")
+    def test_creates_branch_via_branches_api(
+        self,
+        _token: MagicMock,
+        mock_client_cls: MagicMock,
+        _find: MagicMock,
+        _read: MagicMock,
+        _update: MagicMock,
+        _task: MagicMock,
+    ) -> None:
+        client = self._client(mock_client_cls)
+        result = self._invoke()
+        assert result.exit_code == 0
+        assert "Created PR" in result.output
+        post = client._request.call_args
+        assert post.args[:2] == ("POST", "/branches")
+        assert post.kwargs["json"] == {
+            "new_branch_name": "deps/sso_bridge-0.9.1",
+            "old_branch_name": "master",
+        }
+
+    @patch("devx.ci.create_dependency_pr.create_vikunja_task", return_value=None)
+    @patch("devx.ci.create_dependency_pr.update_manifest", return_value=True)
+    @patch("devx.ci.create_dependency_pr.read_manifest_version", return_value="0.9.0")
+    @patch("devx.ci.create_dependency_pr.find_existing_pr", return_value=None)
+    @patch("devx.ci.create_dependency_pr.GiteaClient")
+    @patch("devx.ci.create_dependency_pr.get_ci_token", return_value="tok")
+    def test_existing_branch_tolerated(
+        self,
+        _token: MagicMock,
+        mock_client_cls: MagicMock,
+        _find: MagicMock,
+        _read: MagicMock,
+        _update: MagicMock,
+        _task: MagicMock,
+    ) -> None:
+        from devx.exceptions import APIError
+
+        client = self._client(mock_client_cls)
+        client._request.side_effect = APIError(422, "branch already exists")
+        result = self._invoke()
+        assert result.exit_code == 0
+        assert "already exists" in result.output.lower()
+
+    @patch("devx.ci.create_dependency_pr.create_vikunja_task", return_value=None)
+    @patch("devx.ci.create_dependency_pr.update_manifest", return_value=True)
+    @patch("devx.ci.create_dependency_pr.read_manifest_version", return_value="0.9.0")
+    @patch("devx.ci.create_dependency_pr.find_existing_pr", return_value=None)
+    @patch("devx.ci.create_dependency_pr.GiteaClient")
+    @patch("devx.ci.create_dependency_pr.get_ci_token", return_value="tok")
+    def test_branch_api_error_fails(
+        self,
+        _token: MagicMock,
+        mock_client_cls: MagicMock,
+        _find: MagicMock,
+        _read: MagicMock,
+        _update: MagicMock,
+        _task: MagicMock,
+    ) -> None:
+        from devx.exceptions import APIError
+
+        client = self._client(mock_client_cls)
+        client._request.side_effect = APIError(500, "boom")
+        result = self._invoke()
+        assert result.exit_code != 0
+        assert "Failed to create branch" in result.output
+
+    @patch("devx.ci.create_dependency_pr.create_vikunja_task", return_value=None)
+    @patch("devx.ci.create_dependency_pr.update_manifest", return_value=True)
+    @patch("devx.ci.create_dependency_pr.read_manifest_version", return_value="0.9.0")
+    @patch("devx.ci.create_dependency_pr.find_existing_pr", return_value=None)
+    @patch("devx.ci.create_dependency_pr.GiteaClient")
+    @patch("devx.ci.create_dependency_pr.get_ci_token", return_value="tok")
+    def test_checks_out_remote_tracking_branch(
+        self,
+        _token: MagicMock,
+        mock_client_cls: MagicMock,
+        _find: MagicMock,
+        _read: MagicMock,
+        _update: MagicMock,
+        _task: MagicMock,
+    ) -> None:
+        import subprocess
+
+        self._client(mock_client_cls)
+        result = self._invoke()
+        assert result.exit_code == 0
+        calls = [c.args[0] for c in subprocess.run.call_args_list]
+        assert ["git", "fetch", "origin", "deps/sso_bridge-0.9.1:refs/remotes/origin/deps/sso_bridge-0.9.1"] in calls
+        assert ["git", "checkout", "-B", "deps/sso_bridge-0.9.1", "origin/deps/sso_bridge-0.9.1"] in calls
+
+    @patch("devx.ci.create_dependency_pr.create_vikunja_task", return_value="OBL-INFRA-581")
+    @patch("devx.ci.create_dependency_pr.update_manifest", return_value=True)
+    @patch("devx.ci.create_dependency_pr.read_manifest_version", return_value="0.9.0")
+    @patch("devx.ci.create_dependency_pr.find_existing_pr", return_value=None)
+    @patch("devx.ci.create_dependency_pr.GiteaClient")
+    @patch("devx.ci.create_dependency_pr.get_ci_token", return_value="tok")
+    def test_task_id_in_branch_and_spec_committed(
+        self,
+        _token: MagicMock,
+        mock_client_cls: MagicMock,
+        _find: MagicMock,
+        _read: MagicMock,
+        _update: MagicMock,
+        mock_task: MagicMock,
+    ) -> None:
+        import subprocess
+
+        client = self._client(mock_client_cls)
+        result = self._invoke()
+        assert result.exit_code == 0
+        # Branch embeds the target-repo task ID
+        post = client._request.call_args
+        assert post.kwargs["json"]["new_branch_name"] == "deps/OBL-INFRA-581-sso_bridge-0.9.1"
+        # Spec file added alongside the manifest change
+        add = next(c for c in subprocess.run.call_args_list if c.args[0][:2] == ["git", "add"])
+        assert "docs/specs/OBL-INFRA-581.md" in add.args[0]
+        # PR title carries the task ID
+        assert client.create_pr.call_args.kwargs["title"] == "OBL-INFRA-581: Bump sso_bridge to 0.9.1"
+        mock_task.assert_called_once()
+        # Commit supplies an explicit identity (fresh clones have none)
+        commit = next(c for c in subprocess.run.call_args_list if "commit" in c.args[0])
+        assert "user.name=gitea-actions-bot" in commit.args[0]
+        assert "user.email=actions@oblachno.fyi" in commit.args[0]
+
+    def test_retries_404_until_published(self) -> None:
+        import requests
+
+        from devx.ci.create_dependency_pr import resolve_container_digest
+
+        err = requests.HTTPError("404")
+        err.response = MagicMock(status_code=404)
+        fail = MagicMock()
+        fail.raise_for_status.side_effect = err
+        ok = MagicMock()
+        ok.raise_for_status = MagicMock()
+        ok.json.return_value = [{"name": "manifest.json", "sha256": "cafe"}]
+        with (
+            patch("devx.ci.create_dependency_pr.requests.get", side_effect=[fail, ok, *_v2_mocks("sha256:cafe")]),
+            patch("devx.ci.create_dependency_pr.time.sleep"),
+        ):
+            digest = resolve_container_digest(
+                "https://git.example.com/api/v1", "oblachno", "sso-bridge", "0.9.1", "tok", timeout_s=60
+            )
+        assert digest == "sha256:cafe"