Skip to content

Commit 53a9d54

Browse files
denisecasedenisecase
committed
add contract kit
1 parent b7305ee commit 53a9d54

7 files changed

Lines changed: 110 additions & 155 deletions

File tree

.yamllint.yml renamed to .github/.yamllint.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
# ============================================================
2-
# .yamllint.yml (YAML linting configuration)
2+
# .github/.yamllint.yml (Keep YAML files clean and consistent)
33
# ============================================================
4+
# Updated: 2026-04-13
45

5-
# WHY: Enforce YAML correctness without arbitrary style constraints.
6+
# WHY: Enforce YAML correctness (.github/.yamllint.yml) without arbitrary style constraints.
67
# OBS: Default yamllint rules conflict with GitHub Actions YAML.
78
# Line length, document start, truthy, and comment spacing are intentionally disabled.
89

lychee.toml renamed to .github/lychee.toml

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# ============================================================
2-
# lychee.toml (Lychee link checker configuration)
2+
# .github/lychee.toml (Lychee link checker configuration)
33
# ============================================================
4+
# Updated: 2026-04-13
45

56
# REQ.PROJECT: Automatic link checking using GitHub Actions and Lychee.
67
# WHY-FILE: Shared Lychee configuration (lychee.toml) for documentation-heavy repositories.
@@ -32,11 +33,14 @@ accept = [
3233
308, # Permanent redirect
3334
403, # Forbidden (often false positive)
3435
429, # Too many requests (rate limiting)
35-
503, # Service unavailable (temporary)
3636
]
3737

3838
# WHY: Exclude patterns that shouldn't be checked
3939
exclude = [
40+
"^https://shields\\.io", # WHY: Shields.io badges often have anti-bot measures that cause false positives
41+
"^https://img\\.shields\\.io", # WHY: Shields.io image badges often have anti-bot measures that cause false positives
42+
"^https://badges\\.github\\.com", # WHY: GitHub badges often have anti-bot measures that cause false positives
43+
"^https://www\\.linkedin\\.com", # WHY: LinkedIn often blocks automated requests, causing false positives
4044
"example\\.com", # WHY: Exclude example domains in documentation
4145
"localhost", # WHY: Exclude local development URLs
4246
"127\\.0\\.0\\.1", # WHY: Exclude local loopback

‎.github/workflows/ci-hygiene.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
# ============================================================
22
# .github/workflows/ci-hygiene.yml (Continuous Integration)
33
# ============================================================
4-
# VARIANT: hygiene-ci
5-
# SOURCE: https://github.com/denisecase/templates
4+
# Updated: 2026-05-23
65
#
76
# WHY-FILE: Minimal checks for repositories where hygiene is the primary gate.
87
# REQ: Any check that can be run locally MUST be available locally via pre-commit.
@@ -26,6 +25,7 @@ permissions: # WHY: Use least privileges required.
2625
env:
2726
PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
2827
PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
28+
PYTHON_VERSION: "3.14"
2929

3030
jobs:
3131
ci:

‎.github/workflows/links.yml‎

Lines changed: 10 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,33 @@
11
# ============================================================
22
# .github/workflows/links.yml (Lychee Link Checker)
33
# ============================================================
4-
# SOURCE: https://github.com/denisecase/templates
5-
#
4+
# Updated: 2026-04-13
5+
66
# WHY-FILE: Automated link checking.
77
# OBS: Behavior is configured in lychee.toml in this repository.
88
# OBS: Runs on pull requests and monthly on schedule; manual trigger always available.
99

1010
name: Check Links
1111

1212
on:
13+
workflow_call: # WHY: Allow this workflow to be called by other workflows if needed
1314
workflow_dispatch: # WHY: Manual trigger - always available
1415
pull_request: # WHY: Validates PR links before merge
1516
schedule:
1617
- cron: "0 6 1 * *" # WHY: Runs monthly (1st of month)
1718

1819
concurrency:
1920
# WHY: Prevent multiple simultaneous link checks on same ref
20-
group: link-check-${{ github.ref }}
21+
group: link-check-${{ github.ref || github.run_id }}
2122
cancel-in-progress: true
2223

2324
permissions:
2425
contents: read # WHY: Needed to checkout code.
25-
issues: write # WHY: Needed to create issue on scheduled failures.
26-
pull-requests: write # WHY: Needed to comment on PR if links broken.
2726

2827
env:
2928
PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
3029
PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
31-
REPORT_FAILURES: "true" # WHY: Enable PR comments and scheduled issues for link failures.
30+
REPORT_PATH: "./lychee/out.md" # WHY: Predictable markdown report path for summary generation.
3231

3332
jobs:
3433
lychee:
@@ -39,69 +38,16 @@ jobs:
3938
steps:
4039
- name: 1) Checkout repository code
4140
uses: actions/checkout@v6
41+
# WHY: Required so Lychee can inspect repository files.
4242

43-
- name: 2) Check links with Lychee
44-
id: lychee
43+
- name: 2) Run Lychee
4544
uses: lycheeverse/lychee-action@v2.8.0
4645
with:
47-
fail: true # WHY: Fail the step if broken links found
4846
args: >
49-
--config lychee.toml
50-
--user-agent "${{ github.repository }}/lychee"
51-
'./**/*.bib'
47+
--config .github/lychee.toml
48+
--verbose
49+
--no-progress
5250
'./**/*.md'
5351
'./**/*.html'
54-
'./**/*.tex'
5552
'./**/*.yml'
5653
'./**/*.yaml'
57-
env:
58-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59-
60-
- name: 3) Comment on PR if links broken
61-
if: failure() && github.event_name == 'pull_request' && env.REPORT_FAILURES == 'true'
62-
uses: actions/github-script@v9
63-
with:
64-
script: |
65-
const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
66-
const comment = [
67-
"## Link Check Results",
68-
"",
69-
`Some links appear broken. Check the workflow logs: ${runUrl}`,
70-
].join("\n");
71-
72-
await github.rest.issues.createComment({
73-
issue_number: context.issue.number,
74-
owner: context.repo.owner,
75-
repo: context.repo.repo,
76-
body: comment,
77-
});
78-
79-
- name: 4) Create issue for scheduled failures
80-
# WHY: Track broken links found during scheduled checks
81-
# OBS: Only creates issue if no open issue from github-actions bot exists
82-
if: failure() && github.event_name == 'schedule' && env.REPORT_FAILURES == 'true'
83-
uses: actions/github-script@v9
84-
with:
85-
script: |
86-
const owner = context.repo.owner;
87-
const repo = context.repo.repo;
88-
const date = new Date().toISOString().split("T")[0];
89-
const title = `Link Check Failed - ${date}`;
90-
const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
91-
const body = `Monthly link check found broken links.\n\nWorkflow logs: ${runUrl}`;
92-
93-
const existing = await github.rest.issues.listForRepo({
94-
owner: owner,
95-
repo: repo,
96-
state: "open",
97-
creator: "github-actions[bot]",
98-
per_page: 1,
99-
});
100-
101-
const alreadyOpen = existing.data.some(
102-
(i) => typeof i.title === "string" && i.title.startsWith("Link Check Failed -")
103-
);
104-
105-
if (!alreadyOpen) {
106-
await github.rest.issues.create({ owner, repo, title, body });
107-
}

‎.pre-commit-config.yaml‎

Lines changed: 18 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,22 @@
11
# ============================================================
22
# .pre-commit-config.yaml (Markdown Hygiene)
33
# ============================================================
4-
# VARIANT: markdown-hygiene
5-
# SOURCE: https://github.com/denisecase/templates
6-
#
7-
# REQ: Documentation-only repos MAY include a .pre-commit-config.yaml for repo hygiene (optional).
8-
# WHY: Keep Markdown diffs clean across OSes and prevent common documentation commit errors.
4+
# Updated: 2026-05-23
5+
6+
# Fast, consistent repo hygiene before commit.
97
#
10-
# OBS: These hooks use and do NOT override:
11-
# - .editorconfig (whitespace / indentation)
12-
# - .gitattributes (EOL normalization)
8+
# These hooks complement and do not replace:
9+
# - .editorconfig
10+
# - .gitattributes
11+
# - pyproject.toml
1312
#
14-
# OPTIONAL LOCAL USAGE (no repo venv required):
15-
# Install uv (once, user-level).
13+
# Local usage:
1614
# uv self update
1715
# uvx pre-commit install
18-
# uvx pre-commit run --all-files (just once, to check all files)
19-
# Subsequent commits will AUTOMATICALLY run pre-commit hooks after git add
20-
# and before git commit.
16+
# uvx pre-commit run --all-files
2117
#
22-
# NOTE: pre-commit is optional.
23-
# Repositories do NOT require Python, uv, or pre-commit to clone or commit.
18+
# Ruff lint runs before Ruff format in pre-commit so autofixes
19+
# are formatted in the same pass.
2420

2521
exclude: |
2622
(?x)^(
@@ -34,7 +30,6 @@ exclude: |
3430
\.tox/|
3531
\.venv/|
3632
.*\.(egg-info)/|
37-
.*\.log|
3833
__pycache__/|
3934
_minted.*/|
4035
build/|
@@ -44,7 +39,8 @@ exclude: |
4439
lake-packages/|
4540
node_modules/|
4641
out/|
47-
site/
42+
site/ |
43+
LICENSE
4844
)
4945
5046
repos:
@@ -73,15 +69,18 @@ repos:
7369
# === PRE-COMMIT: CHECK DATA FILE FORMATS ===
7470

7571
- id: check-json
76-
name: B1) Validate JSON syntax
72+
name: B1) Validate JSON syntax (except .vscode/)
73+
# WHY: VSCode settings may include comments, which are non-standard JSON.
74+
exclude: ^\.vscode/.*\.json$
7775

7876
- id: check-toml
7977
name: B2) Validate TOML syntax
8078

8179
- id: check-yaml
8280
name: B3) Validate YAML syntax
8381
files: \.(yml|yaml)$
84-
exclude: ^mkdocs\.ya?ml$ # OBS: mkdocs.yaml may include non-standard tags.
82+
# WHY: VS Code config files are editor-specific
83+
exclude: ^(\.vscode/)
8584

8685
# === PRE-COMMIT:CHECK FOR COMMON PROBLEMS ===
8786

‎SE_MANIFEST.toml‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,66 @@
11
# ============================================================
2-
# .github/SE_MANIFEST.toml (Repository Intent, Scope, and Role)
2+
# .github/SE_MANIFEST.toml
33
# ============================================================
44

5-
schema = "se-manifest-1"
6-
schema_url = "https://github.com/structural-explainability/spec-se/blob/main/manifests/se-manifest-1.md"
5+
schema = "se-manifest-schema"
6+
schema_url = "https://github.com/structural-explainability/se-manifest-schema/blob/main/manifest-schema.toml"
7+
8+
# === Identity ===
79

810
[meta]
9-
# Non-normative contextual information
10-
framework = "Structural Explainability"
11-
framework_url = "https://github.com/structural-explainability"
12-
framework_note = "Provides definitions and conventions for SE_MANIFEST semantics."
13-
description = "Declarative claim of repository intent, scope, and role."
14-
purpose = "To make explicit the boundaries, responsibilities, and expectations of this repository relative to others."
11+
purpose = "Declares the organization-level GitHub health and governance repository for Structural Explainability."
1512

1613
[repo]
1714
name = ".github"
18-
org = "structural-explainability"
15+
org = "structural-explainability"
16+
class = "admin"
1917
kind = "governance"
20-
status = "public"
18+
status = "active"
2119
since = "2025"
22-
summary = "Organization-wide community health files, contribution workflows, and governance scaffolding for Structural Explainability."
20+
summary = "Organization-wide profile for Structural Explainability."
2321

2422
[layer]
2523
space = "SE"
26-
role = "governance"
24+
role = "administration"
25+
26+
# === Dependencies ===
2727

2828
[depends]
2929
required = []
3030
optional = []
3131

32+
# === Provided artifacts ===
33+
3234
[provides]
33-
artifacts = [
34-
"README.md",
35-
"CODE_OF_CONDUCT.md",
36-
"CONTRIBUTING.md",
37-
"SECURITY.md",
38-
".github/",
39-
".github/workflows/",
40-
"SE_MANIFEST.toml"
41-
]
35+
artifacts = ["README.md", "profile/README.md"]
36+
37+
# === Scope ===
4238

4339
[scope]
4440
includes = [
45-
"organization-level contribution guidance",
46-
"issue and pull request templates",
47-
"repository and community health defaults",
48-
"workflow templates and CI policy scaffolding",
49-
"non-normative operational guidance for contributors"
41+
"organization-level GitHub profile content",
42+
"repository health defaults when present",
5043
]
44+
5145
excludes = [
52-
"normative specification definitions",
53-
"formal constraints or invariants",
54-
"conformance requirements",
55-
"implementation logic",
56-
"domain semantics",
57-
"interpretive or evaluative claims"
46+
"normative specification definitions",
47+
"formal constraints or invariants",
48+
"conformance requirements",
49+
"implementation logic",
50+
"domain semantics",
51+
"interpretive or evaluative claims",
5852
]
5953

54+
# === Compatibility ===
55+
56+
[compatibility]
57+
constitution = "none"
58+
59+
# === External references ===
60+
6061
[citation]
6162
cff = "CITATION.cff"
6263
preferred = "repo"
63-
bib_hint = "case2025-se-github"
6464

6565
[traceability]
6666
identifier_map = "none"

0 commit comments

Comments
 (0)