Skip changelog validation for release pull requests (#139)

* [changelog] Skip release PR entry validation (#138)

* Update wiki submodule pointer for PR #139

* [docs] Restore dependency workflow documentation updates (#138)

* [docs] Refresh changelog state and PR skill guidance (#138)

* Update wiki submodule pointer for PR #139

* [changelog] Record workflow docs and skill guidance follow-ups (#138)

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.agents/skills/github-pull-request/SKILL.md

@@ -19,6 +19,7 @@ Use this skill to take a Fast Forward issue from "ready to implement" to an open
 
 - Keep one branch and one PR per issue.
 - Branch from `main` or the repository integration branch, never from another feature branch.
+- When returning to `main` before starting a new implementation, always fetch and fast-forward from the remote before creating the next feature branch so release files, changelog state, and generated artifacts start from the latest published baseline.
 - Prefer local `git` for checkout, commit, and push.
 - Prefer connector-backed GitHub data for issue and PR context when available.
 - Use `phpunit-tests`, `package-readme`, and `sphinx-docs` when the change clearly affects tests or documentation.

.github/wiki

@@ -65,7 +65,7 @@ jobs:
     validate_pull_request:
         name: Validate PR Changelog
         needs: resolve_php
-        if: ${{ github.event.pull_request.number && github.event.pull_request.merged != true }}
+        if: ${{ github.event.pull_request.number && github.event.pull_request.merged != true && !startsWith(github.event.pull_request.head.ref, inputs.release-branch-prefix || 'release/v') }}
         runs-on: ubuntu-latest
         env:
             CHANGELOG_FILE: ${{ inputs.changelog-file || 'CHANGELOG.md' }}

.github/workflows/changelog.yml

@@ -181,6 +181,7 @@ composer dev-tools
 - **Documentation**: Sphinx-based docs in `docs/` directory
 - **Wiki**: GitHub wiki synced via `dev-tools wiki` and `dev-tools:sync`
 - **GitHub Actions**: Workflows in `.github/workflows/` (synced via `dev-tools:sync`)
+- **Dependency Health CI**: `.github/workflows/tests.yml` always runs the dependency-health job, and its default `max-outdated` input is `-1` so outdated packages are reported without failing CI on count alone
 - **Project Agents**: Packaged role prompts synchronized via `composer agents` and `dev-tools:sync`
 
 ## Skills Usage

AGENTS.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Skip pull-request changelog entry validation for generated release branches so release PRs can promote `Unreleased` without failing CI (#138)
+- Restore dependency workflow documentation so README, AGENTS, and command guides match the required CI dependency-health behavior (#138)
+- Require the GitHub pull-request skill to refresh `main` from the remote before branching for a new implementation so changelog and release state start from the latest baseline (#138)
+
 ## [1.15.0] - 2026-04-20
 
 ### Changed

CHANGELOG.md

@@ -147,11 +147,15 @@ composer update-composer-json --force
 composer dev-tools:sync
 ```
 
-The `dependencies` command ships with both dependency analyzers and
-`rector/jack` as direct
+The `dependencies` command ships with
+`shipmonk/composer-dependency-analyser` and `rector/jack` as direct
 dependencies of `fast-forward/dev-tools`, so it works without extra
 installation in the consumer project.
 
+The packaged `tests.yml` workflow runs dependency health as a required job and
+defaults to `--max-outdated=-1`, which keeps outdated-package findings visible
+in CI without failing the workflow for their count alone.
+
 The `metrics` command ships with `phpmetrics/phpmetrics` as a direct
 dependency of `fast-forward/dev-tools`, so consumer repositories can generate
 metrics reports without extra setup.
@@ -215,7 +219,7 @@ skills they depend on.
 |---------|---------|
 | `composer dev-tools` | Runs the full `standards` pipeline. |
 | `composer tests` | Runs PHPUnit with local-or-packaged configuration. |
-| `composer dependencies` | Previews Jack dependency updates, then reports missing, unused, and overly outdated Composer dependencies. |
+| `composer dependencies` | Previews Jack dependency updates, then reports missing, unused, misplaced, and outdated Composer dependencies. |
 | `composer metrics` | Runs PhpMetrics for the current project and generates requested report artifacts. |
 | `composer changelog:entry` | Adds one categorized changelog entry to `Unreleased` or a published release section. |
 | `composer changelog:check` | Verifies that a changelog file contains meaningful `Unreleased` notes, optionally against a git base reference. |

README.md

@@ -32,7 +32,7 @@ Options
 ``--max-outdated=<count>`` (optional)
    Maximum number of outdated packages allowed by ``jack breakpoint``.
 
-   Default: ``5``.
+   Default: ``5`` when you run the command directly.
 
    Use ``-1`` to keep the outdated dependency report in the output while
    ignoring Jack failures in the final command status.
@@ -134,6 +134,9 @@ Behavior
   the command.
 - ``--upgrade`` applies Jack's ``raise-to-installed`` and ``open-versions``
   commands before ``composer update -W`` and ``composer normalize``.
+- the packaged ``tests.yml`` workflow uses ``--max-outdated=-1`` by default so
+  dependency health remains a required CI job while outdated-package counts are
+  reported without failing the workflow on their own.
 - Returns a non-zero exit code when missing, unused, misplaced, or too many
   outdated dependencies are found.
 - Both tools must be available in ``vendor/bin/``.

docs/commands/dependencies.rst

@@ -97,7 +97,9 @@ used for recovery or exceptional maintenance.
 
 The same workflow also owns pull-request changelog validation. Regular feature
 and fix pull requests SHOULD expect ``changelog:check`` to run against the base
-branch and fail when no meaningful ``Unreleased`` entry is added.
+branch and fail when no meaningful ``Unreleased`` entry is added. Generated
+``release/v...`` pull requests are excluded from that validation because the
+release-preparation flow intentionally empties ``Unreleased`` after promotion.
 
 If maintainers must recover the release manually, create the tag from the
 verified ``main`` commit:

docs/internals/release-publishing.rst

@@ -74,6 +74,9 @@ Important details:
   outdated dependencies accumulate;
 - ``--max-outdated=-1`` keeps the Jack outdated report in the output but
   ignores Jack's failure so only dependency-analyser findings fail the command;
+- the packaged ``tests.yml`` workflow uses ``--max-outdated=-1`` by default,
+  so dependency health stays required in CI while outdated-package counts are
+  reported without failing the workflow on their own;
 - it previews ``jack raise-to-installed`` and ``jack open-versions`` before
   the analyzers;
 - ``--upgrade`` runs ``jack raise-to-installed``, ``jack open-versions``,

docs/running/specialized-commands.rst

@@ -68,7 +68,10 @@ The ``tests.yml`` workflow provides standard Continuous Integration.
 
 *   Runs PHPUnit tests across the supported PHP matrix.
 *   Resolves the minimum supported PHP minor version from ``composer.lock`` or ``composer.json`` and builds the test matrix from that floor upward.
-*   Runs dependency health as a separate non-blocking job when enabled.
+*   Runs dependency health as a separate required job.
+*   Defaults the dependency-health threshold to ``--max-outdated=-1`` so
+    outdated packages stay visible in CI without failing the workflow on count
+    alone.
 *   Uses PR-scoped concurrency so newer pushes cancel older in-progress runs for the same pull request.
 
 Fast Forward Changelog
@@ -92,7 +95,8 @@ wrapper in ``resources/github-actions/changelog.yml``.
         safely.
     *   Fetches the base branch changelog reference.
     *   Runs ``composer dev-tools changelog:check -- --against=<base-ref>`` against the base ref.
-    *   Fails when the current branch does not add a meaningful ``Unreleased`` change.
+    *   Fails when a normal non-release branch does not add a meaningful ``Unreleased`` change.
+    *   Skips the validation job for pull requests whose head branch matches the configured ``release-branch-prefix``, because release-preparation branches intentionally leave ``Unreleased`` empty after promotion.
 *   **Manual Release Preparation**:
     *   Checks out the repository default branch with full history.
     *   Resolves the next version from ``Unreleased`` unless a version input is provided.