se std

Author: denisecase

.editorconfig

@@ -1,30 +1,122 @@
-# WHY: Ensures consistent formatting across editors and contributors
-# OBS: Default 4 spaces, but Markdown/YAML/JSON use 2
-# REQ: Keep this file for cross-platform formatting consistency
+# 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) ===
+
 [*]
-charset = utf-8
+# WHY: Normalize line endings and encoding across Windows, macOS, and Linux.
 end_of_line = lf
-indent_style = space
-indent_size = 4  # WHY: Python standard (PEP 8)
+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: Markdown uses 2-space indents for nested lists
+# 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 = false  # WHY: Allows 2 spaces for line breaks
+trim_trailing_whitespace = true
 
-# WHY: YAML/JSON tooling expects 2 spaces
-[*.{yml,yaml,json}]
+[*.{tex,cls,sty}]
+# WHY: LaTeX convention is 2 spaces.
 indent_size = 2
+indent_style = space
 
-# WHY: JavaScript ecosystem standard is 2 spaces
-[*.{js,ts}]
+[*.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
 
-# WHY: TOML follows Python convention (4 spaces)
 [*.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

.github/dependabot.yml

@@ -1,9 +1,21 @@
-# .github/dependabot.yml
+# 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

@@ -17,9 +17,9 @@ name: CI (Docs Site)
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
-    branches: [ main ]
+    branches: [main]
   workflow_dispatch:
 
 permissions:
@@ -64,4 +64,4 @@ jobs:
             uv run mkdocs build --strict
           else
             echo "No mkdocs config found; skipping docs build."
-          fi
+          fi

.github/workflows/deploy-docs.yml

@@ -7,7 +7,7 @@ name: Docs Deploy (MkDocs Python)
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   workflow_dispatch:
 
 permissions:

.github/workflows/links.yml

@@ -1,46 +1,40 @@
-# WHY: Automated link checking - behavior controlled by repo variable
-# OBS: Set IS_ACTIVE_REPO=true in GitHub Repository Settings > Secrets and variables > Actions > Variables
-# ALT: Default (no variable set) runs manual only - perfect for student repos
+# 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
 
-  schedule:
-    - cron: "0 6 1 * *" # WHY: Runs monthly (1st of month) if IS_ACTIVE_REPO=true
+  pull_request: # WHY: Validates PR links before merge
 
-  pull_request: # WHY: Validates PR links if IS_ACTIVE_REPO=true
+  schedule:
+    - cron: "0 6 1 * *" # WHY: Runs monthly (1st of month)
 
-# WHY: Prevent multiple simultaneous link checks on same ref
 concurrency:
+  # WHY: Prevent multiple simultaneous link checks on same ref
   group: link-check-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   lychee:
-    # WHY: Skip scheduled/PR runs unless IS_ACTIVE_REPO=true or manual trigger
-    # OBS: vars.IS_ACTIVE_REPO linted as error in VS Code but works on GitHub
-    if: github.event_name == 'workflow_dispatch' || vars.IS_ACTIVE_REPO == 'true'
-
     runs-on: ubuntu-latest
 
-    # WHY: Permissions needed for PR comments and issue creation
     permissions:
       contents: read
       issues: write
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
+      - name: 1) Checkout repository code
+        uses: actions/checkout@v6 # OBS: v6 current as of Dec 2025
 
-      # WHY: Check all documentation and config files for broken links
-      - name: Check links with Lychee
-        uses: lycheeverse/lychee-action@v2 # OBS: v2 current as of Dec 2025
+      - name: 2) Check links with Lychee
+        uses: lycheeverse/lychee-action@v2
         with:
           args: >
-            --verbose
-            --no-progress
+            --config lychee.toml
             --user-agent "${{ github.repository }}/lychee"
             './**/*.bib'
             './**/*.md'
@@ -52,47 +46,49 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # WHY: Provide helpful feedback on PRs with broken links
-      - name: Comment on PR if links broken
+      - name: 3) Comment on PR if links broken
         if: failure() && github.event_name == 'pull_request'
-        uses: actions/github-script@v8 # OBS: v8 current as of Dec 2025
+        uses: actions/github-script@v8
         with:
           script: |
-            const comment = `## Link Check Results
-
-            Some links appear broken. Check the [workflow logs](${context.payload.repository.html_url}/actions/runs/${context.runId}) for details.`;
-
-            github.rest.issues.createComment({
+            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
+              body: comment,
             });
 
-      # WHY: Track broken links found during scheduled checks
-      # OBS: Only creates issue if none already open with 'broken-links' label
-      - name: Create issue for scheduled failures
+      - 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: v8 current as of Dec 2025
+        uses: actions/github-script@v8
         with:
           script: |
-            const title = `Link Check Failed - ${new Date().toISOString().split('T')[0]}`;
-            const body = `Weekly link check found broken links. [Check logs](${context.payload.repository.html_url}/actions/runs/${context.runId})`;
+            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}`;
 
-            // WHY: Avoid duplicate issues
             const existing = await github.rest.issues.listForRepo({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              labels: 'broken-links',
-              state: 'open'
+              labels: "broken-links",
+              state: "open",
             });
 
             if (existing.data.length === 0) {
               await github.rest.issues.create({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                title: title,
-                body: body,
-                labels: ['maintenance', 'broken-links']
+                title,
+                body,
+                labels: ["maintenance", "broken-links"],
               });
             }

.gitignore

@@ -63,7 +63,7 @@ htmlcov/
 .ruff_cache/
 
 # ----------------------------------------
-# Documentation (MkDocs) — build output
+# Documentation (MkDocs) - build output
 # ----------------------------------------
 site/
 
@@ -86,7 +86,7 @@ reports/
 coverage.xml
 
 # generated by setuptools-scm
-src/python/src/civic_exchange_protocol/_version.py
+src/python/src/civic_evolution_protocol/_version.py
 
 # ----------------------------------------
 # Storage (runtime pulled data snapshots)