update

Author: denisecase

.editorconfig

@@ -5,7 +5,6 @@
 # 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) ===

.github/workflows/ci-hygiene.yml

@@ -0,0 +1,57 @@
+# ============================================================
+# .github/workflows/ci-hygiene.yml (Continuous Integration)
+# ============================================================
+# VARIANT: hygiene-ci
+# SOURCE: https://github.com/denisecase/templates
+#
+# WHY-FILE: Minimal checks for repositories where hygiene is the primary gate.
+# 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 Hygiene
+
+# WHY: Validate repo contents on pushes to main branch and pull requests.
+
+on:
+  push:
+    branches: [main] # WHY: Run when pushing to main branch.
+  pull_request:
+    branches: [main] # WHY: Run on pull requests targeting main branch.
+  workflow_dispatch: # WHY: Allow manual triggering from Actions tab.
+
+permissions: # WHY: Use least privileges required.
+  contents: read
+
+env:
+  PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
+  PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
+
+jobs:
+  ci:
+    name: Repository checks (pre-commit)
+    runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
+    timeout-minutes: 10 # WHY: Prevent hanging jobs. If over, it is likely stuck.
+
+    steps:
+      # ============================================================
+      # ASSEMBLE: Get code and set up environment
+      # ============================================================
+
+      - 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.
+        id: precommit # WHY: Identify step for conditional follow-up.
+        uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files
+
+      - name: 2f) If pre-commit failed, run it locally
+        if: failure()
+        run: |
+          echo "## Pre-commit failed" >> "$GITHUB_STEP_SUMMARY"
+          echo "Please run pre-commit locally and commit the resulting changes." >> "$GITHUB_STEP_SUMMARY"

.github/workflows/ci.yml

@@ -1,67 +1,100 @@
-# 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
-#      .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.
+# ============================================================
+# .pre-commit-config.yaml (Markdown Hygiene)
+# ============================================================
+# VARIANT: markdown-hygiene
+# SOURCE: https://github.com/denisecase/templates
+#
+# REQ: Documentation-only repos MAY include a .pre-commit-config.yaml for repo hygiene (optional).
+# WHY: Keep Markdown diffs clean across OSes and prevent common documentation commit errors.
+#
+# OBS: These hooks use and do NOT override:
+#   - .editorconfig (whitespace / indentation)
+#   - .gitattributes (EOL normalization)
 #
 # 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.
+#   uvx pre-commit run --all-files (just once, to check all files)
+# Subsequent commits will AUTOMATICALLY run pre-commit hooks after git add
+# and before git commit.
 #
 # NOTE: pre-commit is optional.
-#       Repositories do not require Python, uv, or pre-commit to clone or commit.
+#   Repositories do NOT require Python, uv, or pre-commit to clone or commit.
 
 exclude: |
   (?x)^(
     \.DS_Store|
+    \.coverage|
     \.ipynb_checkpoints/|
     \.mypy_cache/|
+    \.nox/|
     \.pytest_cache/|
     \.ruff_cache/|
     \.tox/|
     \.venv/|
+    .*\.(egg-info)/|
+    .*\.log|
+    __pycache__/|
+    _minted.*/|
     build/|
+    coverage\.xml|
     dist/|
+    htmlcov/|
+    lake-packages/|
     node_modules/|
+    out/|
     site/
   )
 
 repos:
+  # === REPO: PRE-COMMIT HOOKS (cross-platform, zero config) ===
+  #
+  # These hooks prevent problems that show up later as:
+  #   - mysterious diffs
+  #   - broken builds on another OS
+
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     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
+      # === PRE-COMMIT: NORMALIZE FILE FORMATTING ===
 
-      - 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: trailing-whitespace
+        name: A1) Clean trailing whitespace (per .editorconfig)
+        args: [--markdown-linebreak-ext=md] # Preserves markdown double-space line breaks
 
-      - id: check-merge-conflict # OBS: prevent committing unresolved merge conflicts
+      - id: end-of-file-fixer
+        name: A2) End files with a newline (per .gitattributes)
 
-      - id: check-yaml # OBS: validate YAML syntax
-        files: \.(yml|yaml)$
+      - id: mixed-line-ending
+        name: A3) Normalize line endings to LF before linters
+        args: [--fix=lf] # OBS: Windows working copies may be CRLF.
 
-  - 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]
+      #  === PRE-COMMIT: CHECK DATA FILE FORMATS ===
+
+      - id: check-json
+        name: B1) Validate JSON syntax
+
+      - id: check-toml
+        name: B2) Validate TOML syntax
+
+      - id: check-yaml
+        name: B3) Validate YAML syntax
         files: \.(yml|yaml)$
+        exclude: ^mkdocs\.ya?ml$ # OBS: mkdocs.yaml may include non-standard tags.
 
-  - repo: https://github.com/rhysd/actionlint
-    rev: v1.7.10
-    hooks:
-      - id: actionlint # OBS: validate GitHub Actions workflow syntax
-        files: ^\.github/workflows/.*\.(yml|yaml)$
+      # === PRE-COMMIT:CHECK FOR COMMON PROBLEMS ===
+
+      - id: check-added-large-files
+        name: C1) Prevent accidental commits of large binaries
+        args: [--maxkb=500]
+
+      - id: check-merge-conflict
+        name: C2) Prevent committing merge conflicts
+
+      - id: check-case-conflict
+        name: C3) Check for filename case conflicts
+
+# === GLOBAL SETTINGS ===
+# ALT: Set fail_fast to true to stop at first failure.
+fail_fast: false # Run all hooks even if one fails

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # Accountable Entities Specification (AE)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/MIT)
-![Build Status](https://github.com/structural-explainability/spec-ae/actions/workflows/ci.yml/badge.svg)
+![Build Status](https://github.com/structural-explainability/spec-ae/actions/workflows/ci-hygiene.yml/badge.svg?branch=main)
 [![Check Links](https://github.com/structural-explainability/spec-ae/actions/workflows/links.yml/badge.svg)](https://github.com/structural-explainability/spec-ae/actions/workflows/links.yml)
 
 > Authoritative specification of Accountable Entities (AE).
@@ -97,3 +97,24 @@ It does not assert what an entity is, what it does, or how it should be interpre
 
 AE makes identity explicit so that structure can remain stable
 across reinterpretation, disagreement, and changing explanatory frameworks.
+
+## Developer (running pre-commit)
+
+Steps to run pre-commit locally. Install `uv`.
+
+Initialize once:
+
+```shell
+uv self update
+uvx pre-commit install
+uvx pre-commit run --all-files
+```
+
+Save progress as needed:
+
+```shell
+git add -A
+# If pre-commit makes changes, re-run `git add -A` before committing.
+git commit -m "update"
+git push -u origin main
+```

README.md

@@ -1,4 +1,17 @@
+# ============================================================
+# SE_MANIFEST.toml (Repository Intent, Scope, and Role)
+# ============================================================
+
 schema = "se-manifest-1"
+schema_url = "https://github.com/structural-explainability/spec-se/blob/main/manifests/se-manifest-1.md"
+
+[meta]
+# Non-normative contextual information
+framework = "Structural Explainability"
+framework_url = "https://github.com/structural-explainability"
+framework_note = "Provides definitions and conventions for SE_MANIFEST semantics."
+description = "Declarative claim of repository intent, scope, and role."
+purpose = "To make explicit the boundaries, responsibilities, and expectations of this repository relative to others."
 
 [repo]
 name = "spec-ae"