initial

Author: denisecase

.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/action@v3.0.1
+        with:
+          extra_args: --all-files

.github/workflows/links.yml

@@ -21,20 +21,20 @@ jobs:
   lychee:
     runs-on: ubuntu-latest
 
-    permissions: # WHY: Permissions needed for PR comments and issue creation
+    permissions:
       contents: read
       issues: write
       pull-requests: write
 
     steps:
-      - name: 1) Checkout repository code # WHY: Needed to access files for link checking
+      - name: 1) Checkout repository code
         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
+      - name: 2) Check links with Lychee
+        uses: lycheeverse/lychee-action@v2
         with:
           args: >
-            --config lychee.toml 
+            --config lychee.toml
             --user-agent "${{ github.repository }}/lychee"
             './**/*.bib'
             './**/*.md'
@@ -46,9 +46,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: 3) Comment on PR if links broken # WHY: Provide helpful feedback on PRs with broken links
+      - name: 3) Comment on PR if links broken
         if: failure() && github.event_name == 'pull_request'
-        uses: actions/github-script@v8 # OBS: current as of Dec 2025
+        uses: actions/github-script@v8
         with:
           script: |
             const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
@@ -68,7 +68,7 @@ jobs:
       - 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
+        uses: actions/github-script@v8
         with:
           script: |
             const date = new Date().toISOString().split("T")[0];

.pre-commit-config.yaml

@@ -1,13 +1,13 @@
-# 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.
+# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.# REQ: Any check that can be run locally MUST be available here.# WHY: Provide fast, consistent local checks aligned with upstream quality gates.# 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 and validate repository metadata.# ALT: Checks that are inherently non-local are handled upstream.# 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## OBS: If a hook reports "files were modified", re-run last command to confirm a clean pass.## 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      - id: end-of-file-fixer # OBS: ensure files end with a newline per .gitattributes      - id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts        # WHY: Workflow files may intentionally include marker-like strings (e.g., >>>>).        exclude: ^\.github/workflows/.*\.(yml|yaml)$      - id: check-yaml # OBS: validate YAML syntax        files: \.(yml|yaml)$  - repo: https://github.com/adrienverge/yamllint    rev: v1.37.1 # OBS: pinned for reproducibility    hooks:      - id: yamllint # OBS: validate YAML structure and policy (no line-length enforcement)        args: [-c, .yamllint.yml]        files: \.(yml|yaml)$  - 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)$# REQ.PROJECT: This repository SHOULD include a .pre-commit-config.yaml when quality gates are required.
+# REQ: Any check that can be run locally MUST be available here.
+# WHY: Provide fast, consistent local checks aligned with upstream quality gates.
 # WHY: Keep local checks compatible with repository-wide formatting rules.
-# OBS: Formatting baselines are defined in 
+# 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.
+#      they only prevent common diff noise and validate repository metadata.
+# ALT: Checks that are inherently non-local are handled upstream.
 # CUSTOM: Keep the hook set minimal and non-destructive for normative Markdown specs.
 #
 # OPTIONAL LOCAL USAGE (no repo venv required):
@@ -16,7 +16,9 @@
 #   uvx pre-commit install
 #   uvx pre-commit run --all-files
 #
-# NOTE: pre-commit is optional. 
+# OBS: If a hook reports "files were modified", re-run last command to confirm a clean pass.
+#
+# NOTE: pre-commit is optional.
 #       Repositories do not require Python, uv, or pre-commit to clone or commit.
 
 exclude: |
@@ -36,19 +38,30 @@ exclude: |
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v6.0.0 # OBS: v6 current as of Dec 30 2025
+    rev: v6.0.0
     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: mixed-line-ending # OBS: normalize line endings before linters run
+        # WHY: yamllint enforces LF; Windows working copies may be CRLF.
+        args: [--fix=lf]
+
       - id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts
+
       - id: check-yaml # OBS: validate YAML syntax
-        files: \.(yml|yaml|md)$
+        files: \.(yml|yaml)$
 
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.37.1
+    hooks:
+      - id: yamllint # OBS: validate YAML structure and policy (no line-length enforcement)
+        args: [-c, .yamllint.yml]
+        files: \.(yml|yaml)$
 
   - repo: https://github.com/rhysd/actionlint
-    rev: v1.7.10 # OBS: v1.7.10 current as of Dec 30 2025
+    rev: v1.7.10
     hooks:
       - id: actionlint # OBS: validate GitHub Actions workflow syntax
         files: ^\.github/workflows/.*\.(yml|yaml)$

.yamllint.yml

@@ -0,0 +1,11 @@
+# WHY: Enforce YAML correctness 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

CITATION.cff

@@ -22,4 +22,4 @@ keywords:
   - identity-regimes
   - formal-ontology
 
-message: "If you use this software, please cite it as described in this file."
+message: "If using this software, please cite it as described in this file."

SPEC.md

@@ -158,4 +158,3 @@ This does not define:
 - exchange or interaction mechanisms
 
 These concerns are explicitly out of scope.
-

lychee.toml

@@ -3,10 +3,10 @@
 # WHY: Configures Lychee link checker behavior for CI/CD.
 # OBS: Flat structure required by lychee v0.22+; no nested sections.
 # OBS: No path exclusions; all documentation files are expected to be link-clean.
-# OBS: Link integrity supports Structural Explainability (SE) 
+# OBS: Link integrity supports Structural Explainability (SE)
 #      by preserving stable, reconstructible references over time.
-# OBS: Link integrity also benefits Contextual Evidence & Explanations (CEE) 
-#      by maintaining the availability of cited evidence and provenance, 
+# OBS: Link integrity also benefits Contextual Evidence & Explanations (CEE)
+#      by maintaining the availability of cited evidence and provenance,
 #      without enforcing interpretation.