chore

Author: denisecase

.editorconfig

@@ -1,3 +1,6 @@
+# ============================================================
+# .editorconfig (Standardize across editors and IDEs)
+# ============================================================
 # REQ.UNIVERSAL: All professional GitHub project repositories MUST include .editorconfig.
 # WHY: Establish a cross-editor baseline so diffs stay clean and formatting is consistent.
 # ALT: Repository may omit .editorconfig ONLY if formatting is enforced equivalently by CI and formatter tooling.

.gitattributes

@@ -1,7 +1,20 @@
-# WHY-FILE: Normalize line endings and GitHub language classification
-# to ensure cross-platform consistency and predictable CI behavior.
+# ============================================================
+# .gitattributes (Keep files consistent across operating systems)
+# ============================================================
 
-# === Core: Text normalization ===
+# REQ.UNIVERSAL: All professional GitHub project repositories MUST include .gitattributes.
+# WHY: Ensure consistent line endings, diff behavior, and file classification
+# across Windows, macOS, and Linux environments.
+# ALT: Repository may omit .gitattributes ONLY if equivalent normalization is
+# enforced reliably by tooling and CI (rare and fragile).
+# CUSTOM: Update file-type rules only when introducing new languages,
+# binary artifacts, or documentation formats.
+# NOTE: Rules are ordered by impact and generality, not alphabetically.
+# Git attributes are documented at https://git-scm.com/docs/gitattributes
+
+# === Core defaults (always apply) ===
+
+# WHY: Auto-detect text files and normalize line endings to avoid cross-platform drift.
 * text=auto
 
 # WHY-SECTION: Explicit EOL rules avoid platform-specific diffs and tool failures.

.github/dependabot.yml

@@ -1,21 +1,26 @@
+# ============================================================
+# .github/dependabot.yml (Check for GitHub Actions updates)
+# ============================================================
+# SOURCE: https://github.com/denisecase/templates
+#
 # REQ.PROJECT: This repository SHOULD track GitHub Actions updates automatically.
-# WHY: GitHub Actions are executable dependencies and may receive security or behavior updates.
-# OBS: This repository has no language-level dependencies (Python, JS, Rust, etc.).
-# OBS: GitHub Actions are the only dependency class currently in scope.
+# WHY-FILE: GitHub Actions are executable dependencies and may receive security or behavior updates.
+# OBS: Language-level dependencies (e.g., Python packages) are upgraded manually.
+# OBS: GitHub Actions are the only dependency class automated here.
 # ALT: Dependabot could be omitted if workflows are pinned and reviewed manually.
 # CUSTOM: Update interval if CI cadence or security posture changes.
 
-version: 2
+# NOTE: This file automatically updates the versions used in Actions workflows.
+# You don't need to modify this file.
+# To disable: Delete this file or set enabled: false below.
+# enabled: false # Uncomment to disable Dependabot
 
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
+version: 2 # Dependabot configuration version
 
-    # WHY: Monthly cadence balances stability with security updates.
-    # ALT: Use "weekly" for higher-security environments.
+updates:
+  - package-ecosystem: "github-actions" # Dependency type
+    directory: "/" # Location of GitHub Actions workflows
     schedule:
-      interval: "monthly"
-
-    # WHY: Clear commit prefix simplifies changelog review and filtering.
+      interval: "monthly" # ALT: Use "weekly" for higher security when needed
     commit-message:
-      prefix: "(deps)"
+      prefix: "(deps)"  # WHY: enable filtering by commit type

.github/workflows/ci-hygiene.yml

@@ -0,0 +1,74 @@
+# ============================================================
+# .github/workflows/ci-md.yml (Continuous Integration)
+# ============================================================
+# SOURCE: https://github.com/denisecase/templates
+#
+# WHY-FILE: Minimal checks for repositories where hygiene is the primary gate.
+# OBS: CI does not introduce additional style rules beyond repo configuration.
+# NOTE: This workflow intentionally avoids requiring Python or pre-commit for contributors.
+
+name: CI Hygiene (Markdown and YAML)
+
+# WHY: Validate repo contents on pushes to main branch and pull requests.
+
+on:
+  push:
+    branches: [main] # WHY: Run when pushing to main branch.
+  pull_request:
+    branches: [main] # WHY: Run on pull requests targeting main branch.
+  workflow_dispatch: # WHY: Allow manual triggering from Actions tab.
+
+permissions: # WHY: Use least privileges required.
+  contents: read
+
+jobs:
+  ci:
+    name: Repository checks (pre-commit)
+    runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
+    timeout-minutes: 10 # WHY: Prevent hanging jobs. If over, it is likely stuck.
+
+    steps:
+      # ============================================================
+      # ASSEMBLE: Get code
+      # ============================================================
+
+      - name: A1) Checkout repository code
+        # WHY: Needed to access files for checks.
+        uses: actions/checkout@v6
+
+      # ============================================================
+      # BASIC CHECKS: Run pre-commit checks
+      # ============================================================
+
+      - name: B1) Lint Markdown
+        # WHY: Enforce Markdown rules consistently (repo-config driven).
+        uses: DavidAnson/markdownlint-cli2-action@v22
+        with:
+          globs: |
+            **/*.md
+
+
+      - name: B2) Lint YAML (uses .yamllint.yml)
+        # WHY: Validate YAML correctness using repo-defined yamllint.yml rules.
+        # OBS: Ensures GitHub Actions YAML and other YAML files remain valid.
+        uses: ibiqlik/action-yamllint@v3
+        with:
+          config_file: yamllint.yml # WHY: Use repo policy; avoid drifting defaults.
+          file_or_dir: .            # WHY: Lint YAML across the repository.
+          no_warnings: true         # WHY: CI output should be actionable.
+
+      - name: B3) Detect CITATION.cff
+        # WHY: Verify presence of CITATION.cff for conditional validation.
+        id: detect_citation
+        shell: bash
+        run: |
+          if [ -f "CITATION.cff" ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: B4) Validate CITATION.cff (if present)
+        # WHY: Ensure CITATION.cff is well-formed without making it mandatory.
+        if: ${{ steps.detect_citation.outputs.present == 'true' }}
+        uses: dieghernan/cff-validator@v4

.github/workflows/ci-md.yml

@@ -1,3 +1,8 @@
+# ============================================================
+# .github/workflows/links.yml (Lychee Link Checker)
+# ============================================================
+# SOURCE: https://github.com/denisecase/templates
+#
 # WHY-FILE: Automated link checking.
 # OBS: Behavior is configured in lychee.toml in this repository.
 # OBS: Runs on pull requests and monthly on schedule; manual trigger always available.
@@ -6,9 +11,7 @@ name: Check Links
 
 on:
   workflow_dispatch: # WHY: Manual trigger - always available
-
   pull_request: # WHY: Validates PR links before merge
-
   schedule:
     - cron: "0 6 1 * *" # WHY: Runs monthly (1st of month)
 
@@ -17,22 +20,33 @@ concurrency:
   group: link-check-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read # WHY: Needed to checkout code.
+  issues: write # WHY: Needed to create issue on scheduled failures.
+  pull-requests: write # WHY: Needed to comment on PR if links broken.
+
+env:
+  PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
+  PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
+  REPORT_FAILURES: "true" # WHY: Enable PR comments and scheduled issues for link failures.
+
 jobs:
   lychee:
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: write
+    name: Link checks
+    runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
+    timeout-minutes: 20 # WHY: Prevent hanging jobs. If over time, likely stuck.
 
     steps:
       - name: 1) Checkout repository code
-        uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
+        uses: actions/checkout@v6
 
       - name: 2) Check links with Lychee
-        uses: lycheeverse/lychee-action@v2
+        id: lychee
+        uses: lycheeverse/lychee-action@v2.7.0
         with:
+          # WHY: Do not hard-fail this step; always run reporting steps.
+          # Instead, fail the job explicitly at the end if exit_code != 0.
+          fail: false
           args: >
             --config lychee.toml
             --user-agent "${{ github.repository }}/lychee"
@@ -42,12 +56,11 @@ jobs:
             './**/*.tex'
             './**/*.yml'
             './**/*.yaml'
-          lycheeVersion: latest # OBS: Always use latest lychee release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: 3) Comment on PR if links broken
-        if: failure() && github.event_name == 'pull_request'
+        if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'pull_request' && env.REPORT_FAILURES == 'true'
         uses: actions/github-script@v8
         with:
           script: |
@@ -65,30 +78,40 @@ jobs:
               body: comment,
             });
 
-      - name: 4) Create issue for scheduled failures # WHY: Track broken links found during scheduled checks
+      - name: 4) Create issue for scheduled failures
+        # WHY: Track broken links found during scheduled checks
         # OBS: Only creates issue if none already open with 'broken-links' label
-        if: failure() && github.event_name == 'schedule'
+        if: steps.lychee.outputs.exit_code != 0 && github.event_name == 'schedule' && env.REPORT_FAILURES == 'true'
         uses: actions/github-script@v8
         with:
           script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
             const date = new Date().toISOString().split("T")[0];
             const title = `Link Check Failed - ${date}`;
             const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
             const body = `Monthly link check found broken links.\n\nWorkflow logs: ${runUrl}`;
 
             const existing = await github.rest.issues.listForRepo({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
+              owner,
+              repo,
               labels: "broken-links",
               state: "open",
+              per_page: 1,
             });
 
             if (existing.data.length === 0) {
               await github.rest.issues.create({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
+                owner,
+                repo,
                 title,
                 body,
                 labels: ["maintenance", "broken-links"],
               });
             }
+
+      - name: 5) Fail job if broken links were found
+        if: steps.lychee.outputs.exit_code != 0
+        run: |
+          echo "Lychee found broken links (exit_code != 0). Failing workflow."
+          exit 1