Add CPAN report publishing skill

.agents/skills/publish-cpan-reports/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: publish-cpan-reports
+description: Publish the four generated PerlOnJava CPAN compatibility report files through a lock-consistent commit, GitHub PR, and merge. Use when asked to save, publish, or submit current dev/cpan-reports compatibility results; do not use for editing tester code or classifying failures.
+---
+
+# Publish CPAN reports
+
+Publish one coherent snapshot of these generated files without stopping active
+`cpan_random_tester.pl` processes:
+
+- `dev/cpan-reports/cpan-compatibility-pass.dat`
+- `dev/cpan-reports/cpan-compatibility-fail.dat`
+- `dev/cpan-reports/cpan-compatibility-skip.dat`
+- `dev/cpan-reports/cpan-compatibility.md`
+
+## Safety boundary
+
+The generated files are the only dirty-tree exception for this workflow. If
+any other pre-existing path is modified or untracked, follow the normal dirty
+tree pre-flight before proceeding. Stage only the four paths above; never use
+`git add -A` for a report snapshot.
+
+Do not stop report generators, clean the checkout, restore files, or discard
+new report changes. Writers may update the worktree immediately after the
+snapshot; those later changes belong to the next report publication.
+
+## Locked snapshot
+
+Create a report publication branch before staging. Derive the lock path using
+the same `report_lock_name($project_root)` and `File::Spec->tmpdir` logic as
+`dev/tools/cpan_random_tester.pl`; do not guess a fixed `/tmp` path. Acquire an
+exclusive `flock` on that file, run `git add` for all four report paths while
+holding the lock, and release it only after `git add` exits.
+
+The tester holds this same lock while atomically replacing all four files, so
+the Git index is a coherent transaction even if the worktree changes after the
+lock is released. Commit from the index without restaging later updates.
+
+Before committing, verify:
+
+- the staged diff contains exactly the four report paths;
+- the line counts of the three staged `.dat` files equal the pass, fail, skip,
+  and total values in the staged Markdown summary;
+- `make check-links` passes;
+- `lychee --offline dev/cpan-reports/cpan-compatibility.md` passes because that
+  generated Markdown file is outside the paths covered by `make check-links`.
+
+Do not run `make` or runtime tests for this data-only publication.
+
+## Publish
+
+Commit with a report-refresh message, push the feature branch, and create a PR
+whose body records the staged totals and that only link validation was run.
+When the user asked to save or publish the reports, merge the report-only PR
+after verifying that it is open and contains exactly the four expected files.
+If the user asked only to open a PR, leave it open.
+
+Use the repository's normal merge method. After merging, do not switch branches
+or otherwise mutate a checkout where active testers have produced later report
+updates.

AGENTS.md

@@ -32,6 +32,22 @@
 ╚══════════════════════════════════════════════════════════════════════════════╝
 ```
 
+### Generated CPAN report publication exception
+
+When the only pre-existing changes are these generated report files and the
+user asks to save or publish them, do not create pre-flight patches or a WIP
+snapshot commit:
+
+- `dev/cpan-reports/cpan-compatibility-pass.dat`
+- `dev/cpan-reports/cpan-compatibility-fail.dat`
+- `dev/cpan-reports/cpan-compatibility-skip.dat`
+- `dev/cpan-reports/cpan-compatibility.md`
+
+Use the [publish-cpan-reports skill](.agents/skills/publish-cpan-reports/SKILL.md)
+to stage all four files while holding the tester's report lock. If any other
+pre-existing path is dirty, the normal mandatory pre-flight still applies.
+Never discard report updates that appear after the locked snapshot.
+
 ## ⚠️⚠️⚠️ FORBIDDEN COMMANDS ON A DIRTY TREE ⚠️⚠️⚠️
 
 ```
@@ -190,6 +206,12 @@
 ╚══════════════════════════════════════════════════════════════════════════════╝
 ```
 
+## Incident Log
+
+| Date | What happened | Root cause and prevention |
+|---|---|---|
+| 2026-08-25 | No source work was lost; an unintended `make` invocation failed before tests started because Gradle could not create its sandboxed lock file. | A Markdown search pattern containing backticks was placed inside a double-quoted shell command, so the shell treated `make` as command substitution. Keep backtick-containing arguments single-quoted or pass them without shell interpolation. |
+
 ## Project Rules
 
 ### Progress Tracking for Multi-Phase Work
@@ -253,6 +275,14 @@ PerlOnJava does **not** implement the following Perl features:
 
 ### Testing
 
+**Documentation-only exception:** Changes limited to documentation, generated
+CPAN report data, and non-executable agent skill instructions do not require
+`make` or runtime tests. When any Markdown file changes, run `make check-links`.
+For changed Markdown outside the paths covered by that target, also run
+`lychee --offline` on the changed files directly. If the diff includes source
+code, executable scripts, tests, build configuration, or other
+runtime-affecting files, the normal test requirements apply.
+
 **NEVER modify or delete existing tests.** Tests are the source of truth. If a test fails, fix the code, not the test. When in doubt, verify expected behavior with system Perl (`perl`, not `jperl`).
 
 **NEVER mutate a checkout while a build or test gate is running in it.** A gate
@@ -353,7 +383,9 @@ The perl_test_runner.pl sets these automatically based on the test file being ru
 
 **IMPORTANT: Never push directly to master. Always use feature branches and PRs.**
 
-**IMPORTANT: Always run `make` and ensure it passes before pushing commits or updating PRs.** This runs all unit tests and catches regressions early.
+**IMPORTANT: Except for the documentation-only case defined under Testing,
+always run `make` and ensure it passes before pushing commits or updating
+PRs.** This runs all unit tests and catches regressions early.
 
 1. **Create a feature branch** before making changes:
    ```bash