Add canonical example sets and schema invariants

Closes #4
Closes #5

Author: denisecase

.gitignore

@@ -27,6 +27,8 @@ PRIVATE-NOTES.md
 
 # WHY: Commit recommended extensions (opt-in) for consistent development experience.
 # NOTE: Share recommendations, not personal editor styles or preferences.
+# Must reinclude directory first so Git will traverse
+!.vscode/
 !.vscode/extensions.json
 !.vscode/settings.json
 

.vscode/ABOUT.md

@@ -0,0 +1,21 @@
+# VS Code Configuration (`.vscode/`)
+
+Optional editor configuration for Visual Studio Code.
+
+## Scope
+
+- Improves consistency for contributors using VS Code
+- Not required to run, test, or build this repository
+- Does not affect CI or repository correctness
+
+## JSON Note
+
+VS Code allows comments in `.vscode` JSON files.
+
+- Valid in VS Code only
+- Not valid general-purpose JSON
+
+## Files
+
+- `extensions.json` recommended extensions (optional)
+- `settings.json` workspace editor defaults

.vscode/extensions.json

@@ -0,0 +1,44 @@
+// ============================================================
+// .vscode/extensions.json (Structural Explainability)
+// ============================================================
+// Updated 2026-04-22
+// NOTE: Comments are not allowed in standard JSON files,
+// but Microsoft allows them in their .vscode config files.
+{
+  "recommendations": [
+    // ============================================================
+    // === PYTHON DEVELOPMENT ===
+    // ============================================================
+    "ms-python.python", // Core Python support
+    "ms-python.vscode-pylance", // Fast IntelliSense and type checking
+    "charliermarsh.ruff", // Modern formatting and linting (replaces black + isort + flake8)
+    // ============================================================
+    // === FILE PATH ASSISTANCE ===
+    // ============================================================
+    "christian-kohler.path-intellisense", // Autocomplete for file paths in Python strings (e.g., "data/file.csv")
+    // ============================================================
+    // === MARKDOWN AND DOCUMENTATION ===
+    // ============================================================
+    "yzhang.markdown-all-in-one", // Shortcuts, TOC, formatting for .md files
+    "bierner.markdown-preview-github-styles", // GitHub-style markdown preview
+    "esbenp.prettier-vscode", // Used for Markdown formatting
+    // "bierner.markdown-mermaid", // Diagram rendering in markdown (flowcharts, etc.)
+    // ============================================================
+    // === DATA FILES AND CONFIGURATION ===
+    // ============================================================
+    "redhat.vscode-yaml", // YAML syntax, validation, formatting
+    "tamasfe.even-better-toml", // TOML syntax, validation (for pyproject.toml)
+    // ============================================================
+    // === PROJECT INFRASTRUCTURE ===
+    // ============================================================
+    "editorconfig.editorconfig", // Respects .editorconfig settings (indentation, line endings)
+    "github.vscode-github-actions" // GitHub Actions workflow editing, validation, and run support
+  ],
+  "unwantedRecommendations": [
+    // ============================================================
+    // === NOT RECOMMENDED: CONFLICTS WITH CURRENT SETUP ===
+    // ============================================================
+    "ms-python.black-formatter", // We use ruff format instead
+    "ms-python.isort" // We use ruff for import sorting
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,37 @@
+// ============================================================
+// .vscode/settings.json (Structural Explainability)
+// ============================================================
+// Updated 2026-04-22
+// NOTE: Comments are not allowed in standard JSON files,
+// but Microsoft allows them in their .vscode config files.
+{
+  "editor.formatOnSave": false,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "vscode.json-language-features"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "vscode.json-language-features"
+  },
+  "[markdown]": {
+    //prettier for markdown files (e.g., README.md)
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "redhat.vscode-yaml"
+  },
+  "[toml]": {
+    "editor.defaultFormatter": "tamasfe.even-better-toml"
+  },
+  "[github-actions-workflow]": {
+    "editor.defaultFormatter": "redhat.vscode-yaml"
+  },
+  "yaml.schemas": {
+    "https://json.schemastore.org/github-workflow.json": [
+      ".github/workflows/*.yml",
+      ".github/workflows/*.yaml"
+    ]
+  }
+}

README.md

@@ -9,9 +9,23 @@
 [![Docs](https://github.com/structural-explainability/se-constitution/actions/workflows/deploy-zensical.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-constitution/actions/workflows/deploy-zensical.yml)
 [![Links](https://github.com/structural-explainability/se-constitution/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/structural-explainability/se-constitution/actions/workflows/links.yml)
 
-> Structural Explainability constitution:
+> Structural Explainability Constitution:
 > rules, schemas, and validation for the SE ecosystem.
 
+## Context
+
+se-constitution
+
+- defines rules
+
+se-kernel
+
+- defines primitives those rules depend on
+
+se-admin
+
+- enforces rules across repositories
+
 ## Command Reference
 
 <details>

data/examples/invalid/class/class-registry.toml

@@ -0,0 +1,24 @@
+# ============================================================
+# Canonical Invalid Example: Class Registry
+# VIOLATION 1: [class.kernel] is missing required 'summary' field.
+# Expected error: "class-registry.toml: [class.kernel] must define summary or description."
+# ============================================================
+
+[meta]
+version = "0.1.0"
+status = "draft"
+title = "SE Constitution Class Registry (Invalid Example)"
+
+[class.constitution]
+summary = "Architectural law and governing definitions for the SE ecosystem."
+stable = true
+allowed_repo_name_patterns = ["se-constitution"]
+
+[class.kernel]
+# VIOLATION 1: 'summary' intentionally omitted.
+stable = true
+allowed_repo_name_patterns = ["se-kernel"]
+
+[validation]
+single_class_required = true
+known_class_required = true

data/examples/invalid/dependency/dependency-rules.toml

@@ -0,0 +1,26 @@
+# ============================================================
+# Canonical Invalid Example: Dependency Rules
+# VIOLATION 2: kernel's allowed list contains 'phantom', which is not a known class.
+# Expected error: "dependency-rules.toml: class 'kernel' allows unknown dependency class 'phantom'."
+# ============================================================
+
+[meta]
+version = "0.1.0"
+status = "draft"
+title = "SE Constitution Dependency Rules (Invalid Example)"
+
+[principle]
+no_cycles = true
+no_reverse_foundation_dependencies = true
+constitution_is_foundational = true
+
+[dependency.constitution]
+allowed = []
+
+[dependency.kernel]
+# VIOLATION 2: 'phantom' is not defined in class-registry.toml.
+allowed = ["constitution", "phantom"]
+
+[validation]
+dependency_classes_must_be_known = true
+forbid_unknown_dependency_classes = true

data/examples/invalid/manifest/manifest-schema.toml

@@ -0,0 +1,33 @@
+# ============================================================
+# Canonical Invalid Example: Manifest Schema
+# Defines required sections and fields for SE_MANIFEST.toml.
+# Class entries match classes in class-registry.
+# ============================================================
+
+[meta]
+version = "0.1.0"
+status = "draft"
+title = "SE Manifest Schema (Minimal Invalid Example)"
+
+[section.repo]
+required = true
+
+[section.layer]
+required = true
+
+[section.depends]
+required = true
+
+[field."repo.name"]
+type = "string"
+required = true
+
+[field."repo.class"]
+type = "string"
+required = true
+
+[class.constitution]
+required_repo_name_patterns = ["se-constitution"]
+
+[class.kernel]
+required_repo_name_patterns = ["se-kernel"]

data/examples/invalid/naming/naming-patterns.toml

@@ -0,0 +1,29 @@
+# ============================================================
+# Canonical Invalid Example: Naming Patterns
+# VIOLATION 3: [pattern.phantom] references class 'phantom' not in class-registry.
+# Expected error: cross-file - naming pattern class 'phantom' is not a known class.
+# ============================================================
+
+[meta]
+version = "0.1.0"
+status = "draft"
+title = "SE Constitution Naming Patterns (Invalid Example)"
+
+[global]
+required_prefix = "se"
+separator = "-"
+ascii_only = true
+lowercase_only = true
+
+[pattern.constitution]
+class = "constitution"
+format = "se-constitution"
+
+[pattern.kernel]
+class = "kernel"
+format = "se-kernel"
+
+[pattern.phantom]
+# VIOLATION 3: 'phantom' is not defined in class-registry.toml.
+class = "phantom"
+format = "se-phantom"

data/examples/invalid/repo/repo-requirements.toml

@@ -0,0 +1,27 @@
+# ============================================================
+# Canonical Invalid Example: Repo Requirements
+# Minimum obligations for constitution and kernel classes.
+# All repo keys match classes in class-registry.
+# ============================================================
+
+[meta]
+version = "0.1.0"
+status = "draft"
+title = "SE Repo Requirements Registry (Minimal Invalid Example)"
+
+[global]
+required_root_files = ["README.md", "SE_MANIFEST.toml"]
+
+[repo.constitution]
+summary = "Architectural law and governing definitions for the SE ecosystem."
+require_ci = true
+require_manifest_validation = true
+
+[repo.kernel]
+summary = "Foundational structural primitives, invariants, and enduring constraints."
+require_ci = true
+require_manifest_validation = true
+
+[validation]
+enforce_known_repo_classes = true
+enforce_required_root_files = true