Skip to content

Commit aa04193

Browse files
hyperpolymathhyperpolymath
committed
Apply estate standardization: governance docs, contractiles, CI/CD cleanup
1 parent 1ad65bf commit aa04193

11 files changed

Lines changed: 659 additions & 85 deletions

File tree

‎.github/CODEOWNERS‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# CODEOWNERS - Define code review assignments for GitHub
3+
# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
4+
5+
# Default: sole maintainer for all files
6+
* @hyperpolymath
7+
8+
# Security-sensitive files require explicit ownership
9+
SECURITY.md @hyperpolymath
10+
.github/workflows/ @hyperpolymath
11+
.machine_readable/ @hyperpolymath
12+
contractiles/ @hyperpolymath
13+
14+
# License files
15+
LICENSE @hyperpolymath
16+
LICENSES/ @hyperpolymath
17+
18+
# Configuration
19+
.gitignore @hyperpolymath
20+
.github/ @hyperpolymath
21+
22+
# Documentation
23+
README* @hyperpolymath
24+
CONTRIBUTING* @hyperpolymath
25+
CODE_OF_CONDUCT* @hyperpolymath
26+
GOVERNANCE* @hyperpolymath
27+
MAINTAINERS* @hyperpolymath
28+
CHANGELOG* @hyperpolymath
29+
ROADMAP* @hyperpolymath
30+
31+
# Build and CI
32+
Justfile @hyperpolymath
33+
Makefile @hyperpolymath
34+
*.sh @hyperpolymath

‎.machine_readable/contractiles/Adjustfile.a2ml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# Adjustfile — Drift-tolerance contract for rsr-template-repo
3+
# Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
#
5+
# Cumulative-drift catchment: tolerance bands + corrective actions.
6+
# Authority: advisory (Yard) — continue-with-warnings; auto_fix where deterministic.
7+
# Run with: adjust check
8+
# Fix with: adjust fix (applies deterministic patches; advisory otherwise)
9+
10+
@abstract:
11+
Drift tolerances and corrective actions for rsr-template-repo. Unlike
12+
MUST (hard gate), ADJUST tracks cumulative drift against tolerance bands
13+
and proposes corrective actions. Advisory — it warns and trends, it does
14+
not block.
15+
@end
16+
17+
## Template Drift
18+
19+
### placeholder-drift
20+
- description: Template placeholders should be replaced when copied
21+
- tolerance: 0 placeholder markers in copied repos
22+
- corrective: Search and replace all {{PLACEHOLDER}} markers
23+
- severity: advisory
24+
- notes: This check only applies to repos that copied from this template
25+
26+
### template-version-drift
27+
- description: Template version should match RSR spec version
28+
- tolerance: Template version matches current RSR spec
29+
- corrective: Update template to match latest RSR spec
30+
- severity: advisory
31+
32+
## Documentation Drift
33+
34+
### readme-completeness
35+
- description: README should document all template features
36+
- tolerance: README covers all contractiles and directory structure
37+
- corrective: Update README.adoc with missing sections
38+
- severity: advisory
39+
40+
### example-accuracy
41+
- description: Examples in documentation should match actual template content
42+
- tolerance: All code examples in docs are accurate
43+
- corrective: Audit and fix examples in documentation
44+
- severity: advisory
45+
46+
## Structural Drift
47+
48+
### contractile-sync
49+
- description: All contractiles should have matching a2ml and ncl implementations
50+
- tolerance: Every .a2ml has a corresponding .ncl
51+
- corrective: Generate missing .ncl files from .a2ml
52+
- severity: advisory
53+
54+
### no-broken-symlinks
55+
- description: No broken symbolic links in template structure
56+
- tolerance: 0 broken symlinks
57+
- corrective: Run symlink-check script
58+
- severity: advisory
59+
60+
## Accessibility Drift
61+
62+
### adoc-not-md
63+
- description: Template docs should prefer AsciiDoc
64+
- tolerance: New prose docs are *.adoc
65+
- corrective: Convert any new *.md to *.adoc
66+
- severity: advisory
67+
68+
### spdx-header-consistency
69+
- description: All template files have correct SPDX headers
70+
- tolerance: 0 files missing SPDX-License-Identifier
71+
- corrective: Add SPDX headers to files that need them
72+
- severity: advisory

‎.machine_readable/contractiles/Intentfile.a2ml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# Intentfile (A2ML Canonical) — north-star contractile for rsr-template-repo
3+
# Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
#
5+
# Paired runner: intend.ncl
6+
# Verb: intend
7+
#
8+
# Semantics: North-star contractile. Declares BOTH concrete committed
9+
# next-actions AND horizon aspirations the project wishes to
10+
# become. Two sections share one file because they answer
11+
# the same question at different ranges:
12+
# [[intents]] — "we WILL do this; track progress"
13+
# status: declared → in_progress → done |
14+
# deferred | retired
15+
# [[wishes]] — "we WISH this were true; revisit later"
16+
# status: declared → in_progress → achieved |
17+
# abandoned
18+
# grouped by horizon: near / mid / far.
19+
# Non-gating — this is a report, not a gate. See the `must`
20+
# contractile for hard gates.
21+
22+
@abstract:
23+
North-star contractile for rsr-template-repo. This repository is the
24+
canonical template for Rhodium Standard Repository compliance. It provides
25+
the scaffold that all hyperpolymath repos should copy and customize.
26+
@end
27+
28+
## Purpose
29+
30+
The rsr-template-repo serves as the master template for all hyperpolymath
31+
repositories. It contains the complete set of contractile files, machine-readable
32+
specifications, and governance documentation that define the Rhodium Standard.
33+
34+
Every new repository in the hyperpolymath estate should be initialized by
35+
copying this template and substituting the placeholder values with
36+
repo-specific content.
37+
38+
## Anti-Purpose
39+
40+
This repository is NOT:
41+
- A general-purpose project scaffold for external use (hyperpolymath-only)
42+
- A replacement for per-repo customization (all files must be bespoke)
43+
- A static template that never changes (evolves with RSR spec)
44+
- A runtime library or framework (build-time only)
45+
46+
## If In Doubt
47+
48+
If you are unsure whether a change is in scope, ask. Sensitive areas:
49+
- .machine_readable/ contractile definitions
50+
- RSR specification files
51+
- Governance templates
52+
- License policy documents
53+
54+
## Committed Next-Actions
55+
56+
### repo-initialization
57+
- description: Provide just copy-and-substitute template for new repos
58+
- probe: test -f scripts/init-repo.sh
59+
- status: done
60+
- notes: Run with source scripts/init-repo.sh <new-repo-name>
61+
62+
### contractile-completeness
63+
- description: Every RSR contractile has an a2ml and ncl implementation
64+
- probe: ls .machine_readable/contractiles/*.a2ml | wc -l | grep -q "^6$"
65+
- status: in_progress
66+
- notes: Currently 6 contractile verbs: intend, must, trust, adjust, bust, dust
67+
68+
### automation-scripts
69+
- description: All repetitive tasks have just recipes
70+
- probe: grep -c "^# " Justfile | grep -q "^[6-9][0-9]*$"
71+
- status: in_progress
72+
73+
## Wishes
74+
75+
### Near Horizon
76+
77+
#### cross-repo-validation
78+
- description: Tooling to validate all repos against RSR spec
79+
- horizon: near
80+
- status: declared
81+
82+
#### automated-substitution
83+
- description: Script to automate repo-specific substitution in template
84+
- horizon: near
85+
- status: declared
86+
87+
### Mid Horizon
88+
89+
#### formal-verification
90+
- description: Idris2 proofs for all critical contractile invariants
91+
- horizon: mid
92+
- status: declared
93+
94+
### Far Horizon
95+
96+
#### ecosystem-visualization
97+
- description: Interactive graph of all hyperpolymath repos and dependencies
98+
- horizon: far
99+
- status: declared

‎.machine_readable/contractiles/Justfile‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# justfile - Error-Lang build commands
3+
4+
set shell := ["bash", "-uc"]
5+
6+
# Default recipe
7+
default: help
8+
9+
# Show help
10+
help:
11+
@echo "Error-Lang Build Commands"
12+
@echo "========================="
13+
@echo ""
14+
@echo "Usage: just <recipe>"
15+
@echo ""
16+
@echo "Recipes:"
17+
@echo " run <file> Run an Error-Lang program"
18+
@echo " doctor Check environment"
19+
@echo " explain Explain an error code"
20+
@echo " test Run tests"
21+
@echo " lint Lint code"
22+
@echo " fmt Format code"
23+
@echo " build Build ReScript compiler"
24+
@echo " clean Clean build artifacts"
25+
26+
# Run an Error-Lang program
27+
run file:
28+
deno run --allow-read --allow-write cli/runtime.js {{file}}
29+
30+
# Check environment
31+
doctor:
32+
deno run cli/main.js doctor
33+
34+
# Explain an error code
35+
explain code="--all":
36+
deno run cli/main.js explain {{code}}
37+
38+
# Run tests
39+
test:
40+
deno test --allow-read --allow-write
41+
42+
# Lint code
43+
lint:
44+
deno lint
45+
@if command -v rescript &> /dev/null; then \
46+
cd compiler && npx rescript build; \
47+
fi
48+
49+
# Format code
50+
fmt:
51+
deno fmt
52+
53+
# Build ReScript compiler
54+
build:
55+
@if [ -d "compiler" ] && [ -f "compiler/rescript.json" ]; then \
56+
cd compiler && npx rescript build; \
57+
else \
58+
echo "ReScript compiler not yet configured"; \
59+
fi
60+
61+
# Clean build artifacts
62+
clean:
63+
rm -rf compiler/lib
64+
rm -f compiler/src/*.res.js
65+
rm -rf .error-lang
66+
67+
# Run all examples
68+
examples:
69+
@for f in examples/*.err; do \
70+
echo "=== Running $$f ==="; \
71+
just run "$$f"; \
72+
echo ""; \
73+
done
74+
75+
# Initialize state for a fresh start
76+
init:
77+
rm -rf .error-lang
78+
@echo "State cleared. Next run will be Run #1."

‎.machine_readable/contractiles/Mustfile.a2ml‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# Mustfile — Physical state contract for rsr-template-repo
3+
# Author: Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
#
5+
# What MUST be true about this repository. Hard requirements.
6+
# Run with: must check
7+
# Fix with: must fix (where a deterministic fix exists)
8+
9+
@abstract:
10+
Physical-state invariants for rsr-template-repo. This is the canonical
11+
RSR template repository. These are hard requirements — CI and pre-commit
12+
hooks fail if any check fails.
13+
@end
14+
15+
## File Presence
16+
17+
### license-present
18+
- description: LICENSE file must exist
19+
- run: test -f LICENSE
20+
- severity: critical
21+
22+
### readme-present
23+
- description: README.adoc must exist
24+
- run: test -f README.adoc
25+
- severity: critical
26+
27+
### security-policy
28+
- description: SECURITY.md must exist
29+
- run: test -f SECURITY.md
30+
- severity: critical
31+
32+
### ai-manifest
33+
- description: 0-AI-MANIFEST.a2ml must exist
34+
- run: test -f 0-AI-MANIFEST.a2ml
35+
- severity: critical
36+
37+
### governance-docs
38+
- description: GOVERNANCE.adoc, MAINTAINERS.adoc, CODEOWNERS must exist
39+
- run: test -f GOVERNANCE.adoc && test -f MAINTAINERS.adoc && test -f .github/CODEOWNERS
40+
- severity: critical
41+
42+
### machine-readable-dir
43+
- description: .machine_readable/ directory must exist
44+
- run: test -d .machine_readable
45+
- severity: critical
46+
47+
## Directory Structure
48+
49+
### contractiles-complete
50+
- description: All required contractile directories exist
51+
- run: test -d .machine_readable/contractiles && test -d .machine_readable/contractiles/bust && test -d .machine_readable/contractiles/dust
52+
- severity: critical
53+
54+
### contractiles-files-present
55+
- description: All four primary contractile files exist
56+
- run: test -f .machine_readable/contractiles/Intentfile.a2ml && test -f .machine_readable/contractiles/Mustfile.a2ml && test -f .machine_readable/contractiles/Trustfile.a2ml && test -f .machine_readable/contractiles/Adjustfile.a2ml
57+
- severity: critical
58+
59+
### bust-dust-files-present
60+
- description: Bustfile and Dustfile exist in their directories
61+
- run: test -f .machine_readable/contractiles/bust/Bustfile.a2ml && test -f .machine_readable/contractiles/dust/Dustfile.a2ml
62+
- severity: critical
63+
64+
### six-directory-present
65+
- description: 6a2 directory exists with required files
66+
- run: test -d .machine_readable/6a2 && test -f .machine_readable/6a2/META.a2ml && test -f .machine_readable/6a2/ECOSYSTEM.a2ml && test -f .machine_readable/6a2/STATE.a2ml && test -f .machine_readable/6a2/PLAYBOOK.a2ml && test -f .machine_readable/6a2/AGENTIC.a2ml && test -f .machine_readable/6a2/NEUROSYM.a2ml
67+
- severity: critical
68+
69+
### anchors-directory
70+
- description: anchors directory exists in 6a2
71+
- run: test -d .machine_readable/6a2/anchors
72+
- severity: warning
73+
74+
### self-validating-structure
75+
- description: self-validating directory has k9-svc and examples
76+
- run: test -d .machine_readable/self-validating && test -d .machine_readable/self-validating/k9-svc && test -d .machine_readable/self-validating/examples
77+
- severity: warning
78+
79+
## Template Integrity
80+
81+
### no-placeholder-values
82+
- description: No placeholder values remain in template files
83+
- run: test -z "$(grep -r '{{' .machine_readable/contractiles/ 2>/dev/null)"
84+
- severity: critical
85+
- notes: All placeholders must be substituted when copying this template
86+
87+
### template-readonly
88+
- description: Template marker files are not modified
89+
- run: grep -q 'RSR_TEMPLATE_DO_NOT_EDIT' .machine_readable/0.1-AI-MANIFEST.a2ml
90+
- severity: warning
91+
92+
## Git State
93+
94+
### no-untracked-contractiles
95+
- description: All contractile files are tracked in git
96+
- run: test -z "$(git ls-files -o --exclude-standard .machine_readable/contractiles/ 2>/dev/null)"
97+
- severity: critical
98+
99+
### signed-commits
100+
- description: All commits must be signed
101+
- run: git verify-commit HEAD
102+
- severity: critical

0 commit comments

Comments
 (0)