ci: make lychee link checking robust and consistent

CI workflow (.github/workflows/linkcheck.yml):
Two link-check runs (push + the matching pull_request) fired within a
couple of seconds, both queried for an open report issue, both found
none, and both created one - producing duplicate "Link Checker Report"
issues (e.g. github.com//issues/44 and /45).
- Restrict issue create/close to the default branch (schedule, push to
  master, manual dispatch); PR and feature-branch runs only surface the
  lychee output in the job log.  This removes the noise source and, since
  only master-ref runs touch issues, the race itself.
- Add a concurrency group keyed on the ref to serialise same-ref runs.
- Fold any pre-existing duplicate open issues into the oldest one, and
  close all open report issues (not just the first) when links are healthy.
- More resilience: --timeout 30, --max-retries 6, --retry-wait-time 2.

Local pre-commit hook (.pre-commit-config.yaml):
The hook was silently dead - `types: [markdown, rst]` is an AND, so it
required a file to be both markdown and rst at once, matching nothing;
and the lychee-docker image for the pinned rev was never published.  That
is why the broken doc links below were only ever caught by CI, not locally.
Replace it with the canonical block shared across my projects: the
auto-installing `id: lychee` (no docker), latest rev lychee-v0.24.2, a
whole-tree scan (args end in '.', pass_filenames: false) so all file types
are checked rather than only md/rst, run at the pre-push stage.

lychee only auto-discovers a non-dot `lychee.toml`, so rename .lychee.toml
-> lychee.toml; the hook then needs no --config, and the CI workflow points
at the new name.  Gitignore the .lycheecache the hook writes locally.

Doc fixes: the docs/CALENDAR_SERVER_RECOMMENDATIONS.md references in
USER_GUIDE.md and TASK_MANAGEMENT.md were missing the leading C (and the
docs/ prefix) - genuinely broken links the checker was flagging.

prompt: lychee is set up in an annoying way, it's creating new issues on every run if lychee fails. Please make the lychee setup more robust (more caching, more retries, don't create new issues if there already exists open issues, etc)
followup-prompt: fix tingbok and icalendar-searcher too. Things should be as similar as possible on all three projects, so lychee should run latest version, it should check all files (not only *.rst / *.md) and it should run from pre-commit before pushing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: tobixen

.github/workflows/linkcheck.yml

@@ -2,11 +2,20 @@ name: Link check
 
 on:
   push:
+    branches:
+      - master
   pull_request:
   workflow_dispatch:
   schedule:
    - cron: "03 22 * * *"
 
+# Serialise runs that share a ref so two link-check runs never race to create
+# the "Link Checker Report" issue.  (The old setup let a push and the matching
+# pull_request run both file an issue at the same second - cf. issues #44/#45.)
+concurrency:
+  group: linkcheck-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   linkcheck:
     runs-on: ubuntu-latest
@@ -26,29 +35,43 @@ jobs:
       with:
         fail: false
         args: >-
-          --config .lychee.toml
-          --timeout 20
-          --max-retries 3
+          --config lychee.toml
+          --timeout 30
+          --max-retries 6
+          --retry-wait-time 2
           --cache
           --max-cache-age 14d
           .
+
+    # Issue management only happens on the default branch (scheduled run, push
+    # to master, or manual dispatch).  PR and feature-branch runs only surface
+    # the lychee output in the job log: this avoids issue noise from transient
+    # branch states and removes the duplicate-issue race entirely, since only
+    # master-ref runs touch issues and the concurrency group serialises those.
     - name: Create or update Link Checker issue
-      if: steps.lychee.outputs.exit_code != 0
+      if: steps.lychee.outputs.exit_code != 0 && github.ref == 'refs/heads/master'
       env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
-        EXISTING=$(gh issue list --label "report" --state open --json number --jq '.[0].number' 2>/dev/null || echo "")
-        if [ -n "$EXISTING" ]; then
-          gh issue edit "$EXISTING" --body-file ./lychee/out.md
+        # Keep the oldest open report issue as the canonical one and fold any
+        # duplicates into it, so accumulated dupes self-heal over time.
+        ISSUES=$(gh issue list --label "report" --state open --json number --jq '.[].number' | sort -n)
+        CANON=$(printf '%s\n' "$ISSUES" | head -1)
+        for n in $(printf '%s\n' "$ISSUES" | tail -n +2); do
+          gh issue close "$n" --comment "Duplicate of #${CANON} - auto-closed by the link checker."
+        done
+        if [ -n "$CANON" ]; then
+          gh issue edit "$CANON" --body-file ./lychee/out.md
         else
           gh issue create --title "Link Checker Report" --body-file ./lychee/out.md --label "report"
         fi
     - name: Close Link Checker issue if all links are healthy
-      if: steps.lychee.outputs.exit_code == 0
+      if: steps.lychee.outputs.exit_code == 0 && github.ref == 'refs/heads/master'
       env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       run: |
-        EXISTING=$(gh issue list --label "report" --state open --json number --jq '.[0].number' 2>/dev/null || echo "")
-        if [ -n "$EXISTING" ]; then
-          gh issue close "$EXISTING" --comment "All links are now healthy."
-        fi
+        # Close every open report issue, not just the first, so stragglers from
+        # earlier races also get cleaned up.
+        for n in $(gh issue list --label "report" --state open --json number --jq '.[].number'); do
+          gh issue close "$n" --comment "All links are now healthy."
+        done

.gitignore

@@ -55,6 +55,9 @@ docs/build/
 tmp/
 *.log
 
+# lychee link checker local cache
+.lycheecache
+
 # OS
 .DS_Store
 Thumbs.db

.pre-commit-config.yaml

@@ -61,8 +61,13 @@ repos:
       stages: [commit-msg]
 
  - repo: https://github.com/lycheeverse/lychee
-   rev: lychee-v0.23.0
+   rev: lychee-v0.24.2
    hooks:
-    - id: lychee-docker
-      args: ["--no-progress", "--timeout", "10", "--config", ".lychee.toml"]
-      types: [markdown, rst]
+    - id: lychee
+      # Check links across the whole working tree (all file types, not just
+      # md/rst).  pass_filenames: false -> pre-commit passes only '.', so the
+      # whole repo is scanned rather than just the changed files.  lychee
+      # auto-discovers lychee.toml, so no --config needed.
+      args: ["--no-progress", "--timeout", "10", "--cache", "--max-cache-age", "1d", "."]
+      pass_filenames: false
+      stages: [pre-push]

TASK_MANAGEMENT.md

@@ -313,7 +313,7 @@ Those are not much relevant wrg of task handling in plann
 
 ## Daily task management and interactive mode
 
-This is specifically directed towards using plann for daily task management.  See also the [USER GUIDE](USER_GUIDE.md) for more generic user guide.  I will assume that your calendar server needs to support advanced CalDAV queries (see [CALENDAR SERVER RECOMMENDATIONS](docs/ALENDAR_SERVER_RECOMMENDATIONS.md)).
+This is specifically directed towards using plann for daily task management.  See also the [USER GUIDE](USER_GUIDE.md) for more generic user guide.  I will assume that your calendar server needs to support advanced CalDAV queries (see [CALENDAR SERVER RECOMMENDATIONS](docs/CALENDAR_SERVER_RECOMMENDATIONS.md)).
 
 ### Adding tasks
 

USER_GUIDE.md

@@ -32,7 +32,7 @@ Those commands are made mostly for making `plann` more convenient to use for the
 * interactive manage-tasks - go through your tasks and make suggestions
 * interactive update-config - (TODO: NOT IMPLEMENTED YET).  This one is not used by the primary author and is probably under-tested.  Its primary intention is to make it easy for others to use the tool.
 
-Note that many of those commands have only been tested on DAViCal (see the [`docs/ALENDAR_SERVER_RECOMMENDATIONS.md`](CALENDAR_SERVER_RECOMMENDATIONS.md) file)
+Note that many of those commands have only been tested on DAViCal (see the [`docs/CALENDAR_SERVER_RECOMMENDATIONS.md`](docs/CALENDAR_SERVER_RECOMMENDATIONS.md) file)
 
 
 ## Global options