initial

Author: denisecase

.editorconfig

@@ -0,0 +1,122 @@
+# 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.
+# CUSTOM: Adjust indent_size defaults only if organizational standards change; keep stable across projects.
+# NOTE: Sections are ordered by editorial importance, not strict alphabetical order.
+# EditorConfig is documented at https://editorconfig.org
+
+[*.{editorconfig}]
+root = true
+
+# === Global defaults (always apply) ===
+
+[*]
+# WHY: Normalize line endings and encoding across Windows, macOS, and Linux.
+end_of_line = lf
+charset = utf-8
+
+# WHY: Newline at EOF avoids noisy diffs and tool warnings.
+insert_final_newline = true
+
+# WHY: Remove accidental whitespace noise in diffs.
+trim_trailing_whitespace = true
+
+# WHY: Default to 2 spaces for configs and markup; language-specific overrides follow.
+indent_style = space
+indent_size = 2
+
+
+# === Build systems (special rules) ===
+
+[Makefile]
+# WHY: Makefiles require tabs.
+indent_style = tab
+
+[*.mk]
+# WHY: Makefile includes require tabs.
+indent_style = tab
+
+
+# === Citation and metadata ===
+
+[CITATION.cff]
+# WHY: Citation tooling expects stable YAML formatting.
+indent_size = 2
+indent_style = space
+
+
+# === Markup and documentation ===
+
+[*.md]
+# WHY: Keep Markdown clean; use explicit <br> for hard line breaks.
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.{tex,cls,sty}]
+# WHY: LaTeX convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.xml]
+# WHY: XML convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{yml,yaml}]
+# WHY: YAML convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Data and configuration ===
+
+[*.{json,jsonc,jsonl,ndjson}]
+# WHY: JSON tooling typically expects 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.toml]
+# WHY: TOML often follows 4-space indentation in many projects.
+indent_size = 4
+indent_style = space
+
+
+# === Programming languages ===
+
+[*.{js,ts}]
+# WHY: JS/TS ecosystem commonly uses 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{py,pyi}]
+# WHY: Python convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.ps1]
+# WHY: PowerShell convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{c,cpp,h,java,cs,go,rs}]
+# WHY: Many C-family and systems languages commonly use 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{sh,bash}]
+# WHY: Shell script convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Proof assistants and formal languages ===
+
+[*.lean]
+# WHY: Lean 4 convention is 2 spaces; matches Mathlib and stdlib style.
+indent_size = 2
+indent_style = space
+
+[*.{v,vo}]
+# WHY: Coq convention is 2 spaces.
+indent_size = 2
+indent_style = space

.gitattributes

@@ -0,0 +1,33 @@
+# WHY-FILE: Normalize line endings and GitHub language classification
+# to ensure cross-platform consistency and predictable CI behavior.
+
+# === Core: Text normalization ===
+* text=auto
+
+# WHY-SECTION: Explicit EOL rules avoid platform-specific diffs and tool failures.
+
+# === Scripts ===
+# Python and shell scripts must always use LF (CI, Linux, macOS, containers)
+*.py  text eol=lf
+*.sh  text eol=lf
+
+# PowerShell scripts follow Windows convention
+*.ps1 text eol=crlf
+
+# === Docs and configs ===
+# Cross-platform; tooling expects LF
+*.md   text eol=lf
+*.yaml text eol=lf
+*.yml  text eol=lf
+*.json text eol=lf
+*.toml text eol=lf
+.pre-commit-config.yaml text eol=lf
+.yamllint.yml           text eol=lf
+
+# === GitHub Linguist ===
+# Improve language statistics and UI without affecting builds
+docs/** linguist-documentation
+
+# Jupyter notebooks: custom diff/merge drivers (if configured)
+*.ipynb diff=jupyternotebook
+*.ipynb merge=jupyternotebook

.github/dependabot.yml

@@ -0,0 +1,21 @@
+# 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.
+# ALT: Dependabot could be omitted if workflows are pinned and reviewed manually.
+# CUSTOM: Update interval if CI cadence or security posture changes.
+
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+
+    # WHY: Monthly cadence balances stability with security updates.
+    # ALT: Use "weekly" for higher-security environments.
+    schedule:
+      interval: "monthly"
+
+    # WHY: Clear commit prefix simplifies changelog review and filtering.
+    commit-message:
+      prefix: "(deps)"

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+# WHY-FILE: Minimal checks for specification repositories.
+# REQ: Any check that can be run locally MUST be available locally via pre-commit.
+# REQ: CI MUST NOT introduce arbitrary rules that are not reproducible locally.
+# OBS: CI does not introduce additional style rules beyond repo configuration.
+
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  hygiene:
+    name: Repository checks
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: 1) Checkout repository code
+        # WHY: Needed to access files for checks.
+        uses: actions/checkout@v6
+
+      - name: 2) Run pre-commit (all files)
+        # WHY: Single source of truth for locally runnable quality gates.
+        # OBS: Fails if hooks would modify files; does not commit changes.
+        uses: pre-commit/[email protected]
+        with:
+          extra_args: --all-files

.github/workflows/links.yml

@@ -0,0 +1,94 @@
+# 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.
+
+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)
+
+concurrency:
+  # WHY: Prevent multiple simultaneous link checks on same ref
+  group: link-check-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lychee:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: 1) Checkout repository code
+        uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
+
+      - name: 2) Check links with Lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >
+            --config lychee.toml
+            --user-agent "${{ github.repository }}/lychee"
+            './**/*.bib'
+            './**/*.md'
+            './**/*.html'
+            './**/*.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'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
+            const comment = [
+              "## Link Check Results",
+              "",
+              `Some links appear broken. Check the workflow logs: ${runUrl}`,
+            ].join("\n");
+
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: comment,
+            });
+
+      - 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'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            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,
+              labels: "broken-links",
+              state: "open",
+            });
+
+            if (existing.data.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ["maintenance", "broken-links"],
+              });
+            }

.gitignore

@@ -0,0 +1,38 @@
+# REQ.UNIVERSAL: Spec repositories MUST ignore editor, OS, and transient artifacts.
+# WHY: Prevent accidental commits of local or generated noise.
+# ALT: Expand only if the repository adds tooling that generates artifacts.
+
+# === OS artifacts ===
+.DS_Store
+Thumbs.db
+
+# === Editor artifacts ===
+*.swp
+*.swo
+*.bak
+*~
+.vscode/
+.idea/
+
+# === Temporary files ===
+.tmp/
+.temp/
+
+# === LaTeX build artifacts (if SPEC is rendered locally) ===
+*.aux
+*.bbl
+*.blg
+*.log
+*.out
+*.toc
+*.fls
+*.fdb_latexmk
+
+# === PDF previews ===
+*.pdf
+
+# === Proof assistant artifacts (defensive, non-binding) ===
+*.olean
+*.ilean
+*.trace
+.lake/