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,98 @@
-# 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__/|
     build/|
+    coverage\.xml|
     dist/|
+    htmlcov/|
+    lake-packages/|
     node_modules/|
     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 @@
 # Structural Explainability (SE)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/MIT)
-![Build Status](https://github.com/structural-explainability/spec-se/actions/workflows/ci.yml/badge.svg)
+![Build Status](https://github.com/structural-explainability/spec-se/actions/workflows/ci-hygiene.yml/badge.svg?branch=main)
 [![Check Links](https://github.com/structural-explainability/spec-se/actions/workflows/links.yml/badge.svg)](https://github.com/structural-explainability/spec-se/actions/workflows/links.yml)
 
 > Authoritative specification of Structural Explainability (SE).
@@ -65,8 +65,10 @@ No downstream specification may weaken or override SE constraints.
 ## Repository Contents
 
 - [SPEC.md](./SPEC.md) - Normative specification
+- [SPEC_LAYERS.md](./SPEC_LAYERS.md) - Canonical epistemic layer model and definitions
 - [IDENTIFIERS.md](./IDENTIFIERS.md) - Stable requirement identifiers
 - [CONFORMANCE.md](./CONFORMANCE.md) - Conformance checklist
+- [se-manifest-1.md](./manifests/se-manifest-1.md) - SE manifest schema and field definitions
 - [ANNOTATIONS.md](./ANNOTATIONS.md) - Annotation standards
 - [LICENSE](./LICENSE) - licensing terms
 - [CITATION.cff](./CITATION.cff) - Citation metadata
@@ -85,3 +87,24 @@ By separating structure from interpretation, SE ensures that:
 - accountability is preserved under persistent disagreement.
 
 SE enables explanation without becoming explanatory.
+
+## 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-se"
@@ -17,7 +30,18 @@ required = []
 optional = []
 
 [provides]
-artifacts = ["README.md", "SPEC.md", "IDENTIFIERS.md", "CONFORMANCE.md"]
+artifacts = [
+  "README.md",
+  "SPEC.md",
+  "SPEC_LAYERS.md",
+  "IDENTIFIERS.md",
+  "CONFORMANCE.md",
+  "manifests/se-manifest-1.md",
+  "ANNOTATIONS.md",
+  "CHANGELOG.md",
+  "CITATION.cff",
+  "LICENSE",
+]
 
 [scope]
 includes = [