Initial commit

Author: gracecode42

.annotations/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>

.editorconfig

@@ -0,0 +1,195 @@
+# ============================================================
+# .editorconfig (ALL-REPOS)
+# ============================================================
+# Updated: 2026-06-27
+#
+# REQ: All professional GitHub project repositories MUST include .editorconfig.
+# WHY: Establish a cross-editor baseline so diffs stay clean and formatting
+# is consistent across editors and IDEs.
+# 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.
+# EditorConfig: https://editorconfig.org
+
+root = true
+
+
+# === Core defaults ===
+
+[*]
+# WHY: Normalize line endings and encoding across Windows, macOS, and Linux.
+charset = utf-8
+end_of_line = lf
+
+# WHY: Default to 2 spaces for configs and markup; language-specific overrides follow.
+indent_size = 2
+indent_style = space
+
+# 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
+
+
+# === Named root and metadata files ===
+
+[CITATION.cff]
+# WHY: Citation tooling expects stable YAML formatting.
+indent_size = 2
+indent_style = space
+
+[CODEOWNERS]
+# WHY: CODEOWNERS is a structured text file; keep formatting simple and stable.
+indent_size = 2
+indent_style = space
+
+[LICENSE]
+# WHY: License text should remain plain, stable, and editor-neutral.
+indent_size = 2
+indent_style = space
+
+
+# === Build systems ===
+
+[Makefile]
+# WHY: Makefiles require tabs.
+indent_style = tab
+
+[*.mk]
+# WHY: Makefile includes require tabs.
+indent_style = tab
+
+
+# === Markup and documentation ===
+
+[*.md]
+# WHY: Keep Markdown clean; use explicit <br> for hard line breaks.
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.qmd]
+# WHY: Quarto Markdown follows Markdown-style formatting.
+indent_size = 2
+indent_style = space
+
+[*.rst]
+# WHY: reStructuredText documentation benefits from stable 2-space indentation.
+indent_size = 2
+indent_style = space
+
+[*.{bib,cls,sty,tex}]
+# WHY: LaTeX and BibTeX convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{css,html,xml}]
+# WHY: Web and XML markup convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Configuration and structured text ===
+
+[*.env]
+# WHY: Environment templates should remain simple line-oriented text.
+indent_size = 2
+indent_style = space
+
+[*.{cfg,ini}]
+# WHY: INI-style configuration convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{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
+
+[*.{yaml,yml}]
+# WHY: YAML convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+
+# === Programming languages and scripts ===
+
+[*.bat]
+# WHY: Windows batch files commonly use tabs or editor defaults; keep simple.
+indent_size = 2
+indent_style = space
+
+[*.{bash,sh}]
+# WHY: Shell script convention is 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.{c,cpp,cs,go,h,hpp,java,rs}]
+# WHY: Many C-family and systems languages commonly use 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.jl]
+# WHY: Julia convention commonly uses 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{js,ts}]
+# WHY: JS/TS ecosystem commonly uses 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.mojo]
+# WHY: Mojo uses Python-like syntax and commonly follows 4-space indentation.
+indent_size = 4
+indent_style = space
+
+[*.ps1]
+# WHY: PowerShell convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{py,pyi}]
+# WHY: Python convention is 4 spaces.
+indent_size = 4
+indent_style = space
+
+[*.{r,R}]
+# WHY: R convention commonly uses 2 spaces.
+indent_size = 2
+indent_style = space
+
+[*.sql]
+# WHY: SQL formatting varies, but 2 spaces is a stable shared baseline.
+indent_size = 2
+indent_style = space
+
+
+# === Formal, math, and proof languages ===
+
+[*.lean]
+# WHY: Lean 4 convention is 2 spaces; matches Mathlib and stdlib style.
+indent_size = 2
+indent_style = space
+
+
+# === Notebooks ===
+
+[*.ipynb]
+# WHY: Jupyter notebooks are JSON documents; keep embedded formatting stable.
+indent_size = 2
+indent_style = space
+
+
+# === Text and tabular data ===
+
+[*.{csv,dat,psv,tsv,txt}]
+# WHY: Text and tabular data should remain simple line-oriented text.
+indent_size = 2
+indent_style = space

.gitattributes

@@ -0,0 +1,170 @@
+# ============================================================
+# .gitattributes (ALL-REPOS)
+# ============================================================
+# Updated: 2026-06-27
+#
+# REQ: All professional GitHub repositories SHOULD include .gitattributes.
+# WHY: Keep line endings, diffs, and file classification consistent across
+# Windows, macOS, Linux, GitHub Actions, and environments.
+# CUSTOM: Add rules when new shared file types are introduced.
+# Git attributes: https://git-scm.com/docs/gitattributes
+
+
+# === Core defaults ===
+
+# WHY: Auto-detect text files and normalize text
+# unless a later rule is more specific.
+* text=auto eol=lf
+
+
+# === Named root and metadata files ===
+
+# WHY: Important extensionless repo files are text and should use LF.
+CODEOWNERS  text eol=lf
+LICENSE     text eol=lf
+
+
+# === Operating-system files ===
+
+# WHY: OS metadata files are binary/noisy and should not be normalized.
+.DS_Store    binary
+Thumbs.db    binary
+desktop.ini  binary
+
+
+# === Markup and documentation ===
+
+# WHY: Documentation, web, and math markup use LF for stable cross-platform diffs.
+*.bib   text eol=lf
+*.cls   text eol=lf
+*.css   text eol=lf
+*.html  text eol=lf
+*.md    text eol=lf
+*.qmd   text eol=lf
+*.rst   text eol=lf
+*.sty   text eol=lf
+*.tex   text eol=lf
+*.xml   text eol=lf
+
+
+# === Configuration and structured text ===
+
+# WHY: Config and structured text files should produce stable diffs.
+*.cfg     text eol=lf
+*.env     text eol=lf
+*.ini     text eol=lf
+*.json    text eol=lf
+*.jsonc   text eol=lf
+*.jsonl   text eol=lf
+*.ndjson  text eol=lf
+*.toml    text eol=lf
+*.txt     text eol=lf
+*.yaml    text eol=lf
+*.yml     text eol=lf
+
+
+# === Programming languages and scripts ===
+
+# WHY: Windows specific script types (.bat, .cmd)
+# are covered under the general LF text policy.
+
+# WHY: Source and script files use LF for CI, shells, containers, and tooling.
+*.c     text eol=lf
+*.cpp   text eol=lf
+*.cs    text eol=lf
+*.go    text eol=lf
+*.h     text eol=lf
+*.hpp   text eol=lf
+*.java  text eol=lf
+*.jl    text eol=lf
+*.js    text eol=lf
+*.mojo  text eol=lf
+*.ps1   text eol=lf
+*.py    text eol=lf
+*.r     text eol=lf
+*.R     text eol=lf
+*.rs    text eol=lf
+*.sh    text eol=lf
+*.sql   text eol=lf
+*.ts    text eol=lf
+
+
+# === Formal, math, and proof languages ===
+
+# WHY: Lean source files are text; Lean build artifacts are binary.
+*.ilean  binary
+*.lean   text eol=lf
+*.olean  binary
+*.trace  binary
+
+# WHY: Lake build output should not be normalized if accidentally tracked.
+.lake/**  binary
+
+
+# === Notebooks ===
+
+# WHY: Jupyter notebooks can contain Python, R, Julia, and other kernels.
+*.ipynb  text eol=lf
+
+
+# === Text and tabular data ===
+
+# WHY: Small text data files benefit from readable diffs.
+*.csv  text eol=lf
+*.dat  text eol=lf
+*.psv  text eol=lf
+*.tsv  text eol=lf
+
+
+# === Databases ===
+
+# WHY: Database files are binary; text diffs are not meaningful.
+*.db       binary
+*.duckdb   binary
+*.sqlite   binary
+*.sqlite3  binary
+
+
+# === Columnar and analytical data ===
+
+# WHY: Columnar/analytical formats are binary; text diffs are not meaningful.
+*.arrow    binary
+*.avro     binary
+*.feather  binary
+*.orc      binary
+*.parquet  binary
+
+
+# === Office, BI, PDF, and compressed artifacts ===
+
+# WHY: Office, BI, PDF, and archive files are binary.
+*.7z    binary
+*.bz2   binary
+*.docx  binary
+*.gz    binary
+*.pbix  binary
+*.pbit  binary
+*.pdf   binary
+*.pptx  binary
+*.rar   binary
+*.tar   binary
+*.tgz   binary
+*.xls   binary
+*.xlsm  binary
+*.xlsx  binary
+*.xz    binary
+*.zip   binary
+
+
+# === Logs and generated runtime output ===
+
+# WHY: Logs are generated runtime evidence; avoid normalization churn.
+*.log        binary
+project.log  binary
+
+
+# === GitHub metadata and UI ===
+
+# WHY: Exclude documentation and tests from GitHub language statistics.
+docs/**   linguist-documentation
+tests/**  linguist-documentation

.github/.yamllint.yml

@@ -0,0 +1,16 @@
+# ============================================================
+# .github/.yamllint.yml (Keep YAML files clean and consistent)
+# ============================================================
+# Updated: 2026-04-13
+
+# WHY: Enforce YAML correctness (.github/.yamllint.yml) without arbitrary style constraints.
+# OBS: Default yamllint rules conflict with GitHub Actions YAML.
+#      Line length, document start, truthy, and comment spacing are intentionally disabled.
+
+extends: default
+
+rules:
+  line-length: disable
+  document-start: disable
+  truthy: disable
+  comments: disable