Skip to content

Commit 3500e22

Browse files
denisecasedenisecase
committed
ss
1 parent 701099e commit 3500e22

10 files changed

Lines changed: 241 additions & 181 deletions

File tree

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

File renamed without changes.

lychee.toml renamed to .github/lychee.toml

File renamed without changes.

‎.github/workflows/links.yml‎

Lines changed: 25 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,53 @@
1+
# ============================================================
2+
# .github/workflows/links.yml (Lychee Link Checker)
3+
# ============================================================
4+
# Updated: 2026-04-13
5+
16
# WHY-FILE: Automated link checking.
27
# OBS: Behavior is configured in lychee.toml in this repository.
38
# OBS: Runs on pull requests and monthly on schedule; manual trigger always available.
49

510
name: Check Links
611

712
on:
13+
workflow_call: # WHY: Allow this workflow to be called by other workflows if needed
814
workflow_dispatch: # WHY: Manual trigger - always available
9-
1015
pull_request: # WHY: Validates PR links before merge
11-
1216
schedule:
1317
- cron: "0 6 1 * *" # WHY: Runs monthly (1st of month)
1418

1519
concurrency:
1620
# WHY: Prevent multiple simultaneous link checks on same ref
17-
group: link-check-${{ github.ref }}
21+
group: link-check-${{ github.ref || github.run_id }}
1822
cancel-in-progress: true
1923

24+
permissions:
25+
contents: read # WHY: Needed to checkout code.
26+
27+
env:
28+
PYTHONUNBUFFERED: "1" # WHY: Real-time logging.
29+
PYTHONIOENCODING: "utf-8" # WHY: Ensure UTF-8 encoding for international characters.
30+
REPORT_PATH: "./lychee/out.md" # WHY: Predictable markdown report path for summary generation.
31+
2032
jobs:
2133
lychee:
22-
runs-on: ubuntu-latest
23-
24-
permissions:
25-
contents: read
26-
issues: write
27-
pull-requests: write
34+
name: Link checks
35+
runs-on: ubuntu-latest # WHY: Linux environment matches most production deployments
36+
timeout-minutes: 20 # WHY: Prevent hanging jobs. If over time, likely stuck.
2837

2938
steps:
30-
- name: A1) Checkout repository code
39+
- name: 1) Checkout repository code
3140
uses: actions/checkout@v6
41+
# WHY: Required so Lychee can inspect repository files.
3242

33-
- name: 2) Check links with Lychee
34-
uses: lycheeverse/lychee-action@v2
43+
- name: 2) Run Lychee
44+
uses: lycheeverse/lychee-action@v2.8.0
3545
with:
3646
args: >
37-
--config lychee.toml
38-
--user-agent "${{ github.repository }}/lychee"
39-
'./**/*.bib'
47+
--config .github/lychee.toml
48+
--verbose
49+
--no-progress
4050
'./**/*.md'
4151
'./**/*.html'
42-
'./**/*.tex'
4352
'./**/*.yml'
4453
'./**/*.yaml'
45-
lycheeVersion: latest # OBS: Always use latest lychee release
46-
env:
47-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
48-
49-
- name: 3) Comment on PR if links broken
50-
if: failure() && github.event_name == 'pull_request'
51-
uses: actions/github-script@v9
52-
with:
53-
script: |
54-
const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
55-
const comment = [
56-
"## Link Check Results",
57-
"",
58-
`Some links appear broken. Check the workflow logs: ${runUrl}`,
59-
].join("\n");
60-
61-
await github.rest.issues.createComment({
62-
issue_number: context.issue.number,
63-
owner: context.repo.owner,
64-
repo: context.repo.repo,
65-
body: comment,
66-
});
67-
68-
- name: 4) Create issue for scheduled failures # WHY: Track broken links found during scheduled checks
69-
# OBS: Only creates issue if none already open with 'broken-links' label
70-
if: failure() && github.event_name == 'schedule'
71-
uses: actions/github-script@v9
72-
with:
73-
script: |
74-
const date = new Date().toISOString().split("T")[0];
75-
const title = `Link Check Failed - ${date}`;
76-
const runUrl = `${context.payload.repository.html_url}/actions/runs/${context.runId}`;
77-
const body = `Monthly link check found broken links.\n\nWorkflow logs: ${runUrl}`;
78-
79-
const existing = await github.rest.issues.listForRepo({
80-
owner: context.repo.owner,
81-
repo: context.repo.repo,
82-
labels: "broken-links",
83-
state: "open",
84-
});
85-
86-
if (existing.data.length === 0) {
87-
await github.rest.issues.create({
88-
owner: context.repo.owner,
89-
repo: context.repo.repo,
90-
title,
91-
body,
92-
labels: ["maintenance", "broken-links"],
93-
});
94-
}

‎.markdownlint-cli2.yaml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# ============================================================
2+
# .markdownlint-cli2.yaml (Markdownlint CLI2 configuration)
3+
# ============================================================
4+
# Updated: 2026-05-31
5+
# WHY: Generated and dependency directories are not source content.
6+
# REQ: Markdown lint should check authored Markdown, not virtual
7+
# environments, dependency trees, build output, or generated docs.
8+
9+
globs:
10+
- "**/*.md"
11+
12+
ignores:
13+
- ".lake/**"
14+
- "**/.lake/**"
15+
- ".venv/**"
16+
- "**/.venv/**"
17+
- "node_modules/**"
18+
- "**/node_modules/**"
19+
- "site/**"
20+
- "**/site/**"
21+
- "dist/**"
22+
- "**/dist/**"
23+
- "build/**"
24+
- "**/build/**"
25+
- ".ruff_cache/**"
26+
- "**/.ruff_cache/**"
27+
- ".pytest_cache/**"
28+
- "**/.pytest_cache/**"
29+
- ".mypy_cache/**"
30+
- "**/.mypy_cache/**"
31+
- ".pyright/**"
32+
- "**/.pyright/**"
33+
- ".tox/**"
34+
- "**/.tox/**"
35+
- ".nox/**"
36+
- "**/.nox/**"
37+
- ".uv-cache/**"
38+
- "**/.uv-cache/**"
39+
- "htmlcov/**"
40+
- "**/htmlcov/**"
41+
- "LICENSE"
42+
43+
config:
44+
default: true # WHY: This enables all default rules, which is a good starting point for linting Markdown files.
45+
46+
MD013:
47+
line_length: 100
48+
headings: false # WHY: This allows long headings, which can be necessary for clarity and SEO in Markdown files.
49+
tables: false # WHY: This allows long table cells, which can be necessary for readability and completeness in Markdown files.
50+
code_blocks: false # WHY: This allows long lines in code blocks, which can be necessary for readability and completeness in Markdown files.
51+
52+
MD025: false # WHY: This allows multiple top-level headings, which can be necessary in Markdown files that are not strictly linear documents (e.g., README files, documentation index files).
53+
54+
MD033:
55+
allowed_elements:
56+
- mark # WHY: Mark elements are often used in Markdown files for highlighting, and this allows them without triggering a lint error.
57+
- meta # WHY: Metadata is often needed in Markdown files, and this allows it without triggering a lint error.
58+
- link # WHY: Links are common in Markdown files, and this allows them without triggering a lint error.
59+
- details # WHY: Details elements are often used in Markdown files, and this allows them without triggering a lint error.
60+
- summary # WHY: Summary elements are often used in Markdown files, and this allows them without triggering a lint error.

‎README.md‎

Lines changed: 36 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,56 @@
44
![Build Status](https://github.com/structural-explainability/NeutralSubstrate/actions/workflows/ci-lean.yml/badge.svg?branch=main)
55
[![Check Links](https://github.com/structural-explainability/NeutralSubstrate/actions/workflows/links.yml/badge.svg?branch=main)](https://github.com/structural-explainability/NeutralSubstrate/actions/workflows/links.yml)
66

7-
> Lean 4 formalization of foundational constraints required for ontological substrates
8-
> intended to support accountability under persistent interpretive disagreement.
7+
> Superseded Lean 4 formalization of neutral-substrate constraints for
8+
> accountability-oriented systems under persistent interpretive disagreement.
99
10-
## Context
10+
## Status
1111

12-
Part of the Structural Explainability framework.
12+
This repository is superseded by the active `se-theory-*` and formal-contract repositories.
13+
14+
Active development has moved to:
15+
16+
- [`se-theory-neutral-substrate`](https://github.com/structural-explainability/se-theory-neutral-substrate)
17+
- [`se-formal-contract`](https://github.com/structural-explainability/se-formal-contract)
18+
19+
This repository is retained for provenance, earlier implementation history,
20+
and compatibility with prior references. It may receive maintenance updates for
21+
tooling, build hygiene, metadata, or release alignment, but it is no longer the
22+
active theory source.
1323

1424
## Scope
1525

16-
This repository formalizes structural constraints on ontological substrates that are intended to remain stable across incompatible interpretations, legal regimes, and analytic frameworks.
26+
This repository provides an earlier Lean 4 formalization of structural
27+
constraints on ontological substrates intended to remain stable across
28+
incompatible interpretations, legal regimes, and analytic frameworks.
29+
30+
It does not define a concrete ontology or protocol. It establishes substrate-level
31+
conditions that such systems must satisfy to avoid embedding interpretation,
32+
authority, causality, or judgment into the structural core.
33+
34+
## Current Replacement Path
1735

18-
It does not define a concrete ontology or protocol.
19-
It establishes conditions that any such system must satisfy at the substrate level.
36+
Use the active repositories for current work:
37+
38+
| Need | Use |
39+
| ---- | --- |
40+
| Active neutral-substrate theory | [`se-theory-neutral-substrate`](https://github.com/structural-explainability/se-theory-neutral-substrate) |
41+
| Machine-readable formal contract exports | [`se-formal-contract`](https://github.com/structural-explainability/se-formal-contract) |
2042

2143
## Build and Run
2244

23-
```bash
45+
```shell
2446
lake update
2547
lake build
2648
lake exe verify
2749
```
2850

51+
## Optional Markdown Lint
52+
53+
```shell
54+
npx markdownlint-cli2 --fix
55+
```
56+
2957
## Documentation
3058

3159
- [Paper to Lean Mapping](./docs/MAPPING.md)

0 commit comments

Comments
 (0)