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,31 @@
+# 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
+
+# === 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/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: # WHY: Permissions needed for PR comments and issue creation
+      contents: read
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: 1) Checkout repository code # WHY: Needed to access files for link checking
+        uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
+
+      - name: 2) Check links with Lychee # WHY: Check documentation and config files for broken links
+        uses: lycheeverse/lychee-action@v2 # OBS: Pin to major for stability
+        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 # WHY: Provide helpful feedback on PRs with broken links
+        if: failure() && github.event_name == 'pull_request'
+        uses: actions/github-script@v8 # OBS: current as of Dec 2025
+        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 # OBS: current as of Dec 2025
+        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/

.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.
+# WHY: Provide fast, consistent local checks aligned with CI.
+# WHY: Keep local checks compatible with repository-wide formatting rules.
+# OBS: Formatting baselines are defined in 
+#      .editorconfig (whitespace/indentation) and
+#      .gitattributes (EOL normalization).
+# OBS: These hooks do not override .editorconfig or .gitattributes;
+#      they only prevent common diff noise.
+# ALT: CI-only checks are acceptable, but local pre-commit reduces cycle time
+#      and prevents avoidable churn.
+# CUSTOM: Keep the hook set minimal and non-destructive for normative Markdown specs.
+#
+# OPTIONAL LOCAL USAGE (no repo venv required):
+#   Install uv (once, user-level).
+#   uv self update
+#   uvx pre-commit install
+#   uvx pre-commit run --all-files
+#
+# NOTE: pre-commit is optional. 
+#       Repositories do not require Python, uv, or pre-commit to clone or commit.
+
+exclude: |
+  (?x)^(
+    \.DS_Store|
+    \.ipynb_checkpoints/|
+    \.mypy_cache/|
+    \.pytest_cache/|
+    \.ruff_cache/|
+    \.tox/|
+    \.venv/|
+    build/|
+    dist/|
+    node_modules/|
+    site/
+  )
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0 # OBS: v6 current as of Dec 30 2025
+    hooks:
+      - id: check-added-large-files # OBS: prevent large binary files
+      - id: trailing-whitespace # OBS: clean trailing whitespace per .editorconfig
+        args: [--markdown-linebreak-ext=md] # OBS: respect Markdown line breaks
+      - id: end-of-file-fixer # OBS: ensure files end with a newline per .gitattributes
+      - id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts
+      - id: check-yaml # OBS: validate YAML syntax
+        files: \.(yml|yaml|md)$
+
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.10 # OBS: v1.7.10 current as of Dec 30 2025
+    hooks:
+      - id: actionlint # OBS: validate GitHub Actions workflow syntax
+        files: ^\.github/workflows/.*\.(yml|yaml)$

ANNOTATIONS.md

@@ -0,0 +1,10 @@
+# Annotations
+
+<!--
+WHY: This repository uses the Structural Explainability Annotation Standard
+to document decisions, constraints, and alternatives directly alongside
+code and configuration.
+-->
+
+This repository uses the annotation standard defined at:
+<https://github.com/structural-explainability/.github/blob/main/ANNOTATIONS.md>