Skip to content

Commit ef09180

Browse files
Jonathan D.A. Jewellclaude
andcommitted
Update standards with enforcement workflows and complete structure
- Add language-policy.yml workflow (blocks TS, Go, Python, Java, Kotlin, Swift, Makefiles) - Add makefile-blocker.yml workflow (blocks all Makefile changes) - Add doc-format.yml workflow (enforces AsciiDoc documentation) - Add pre-commit hook for local enforcement - Update README.adoc with complete standards structure: - 6 SCM files and their canonical repos - ANCHOR.scm for calibration - RSR/Rhodium repos - Palimpsest licensing - Mustfile build system - Update CLAUDE.md: - Remove Python/SaltStack exception (Python fully banned) - Add Makefiles to banned list - Add .machine_readable/ requirement - Add documentation format policy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent c953e51 commit ef09180

6 files changed

Lines changed: 574 additions & 84 deletions

File tree

.claude/CLAUDE.md

Lines changed: 38 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,20 @@
11
# CLAUDE.md - AI Assistant Instructions
22

3+
## Machine-Readable Artefacts
4+
5+
Every Hyperpolymath repo must have `.machine_readable/` with these 6 SCM files:
6+
7+
- `STATE.scm` - Current project state and progress
8+
- `META.scm` - Architecture decisions and development practices
9+
- `ECOSYSTEM.scm` - Position in the ecosystem and related projects
10+
- `AGENTIC.scm` - AI agent interaction patterns
11+
- `NEUROSYM.scm` - Neurosymbolic integration config
12+
- `PLAYBOOK.scm` - Operational runbook
13+
14+
See: https://github.com/hyperpolymath/standards
15+
16+
---
17+
318
## Language Policy (Hyperpolymath Standard)
419

520
### ALLOWED Languages & Tools
@@ -14,9 +29,8 @@
1429
| **Gleam** | Backend services | Runs on BEAM or compiles to JS |
1530
| **Bash/POSIX Shell** | Scripts, automation | Keep minimal |
1631
| **JavaScript** | Only where ReScript cannot | MCP protocol glue, Deno APIs |
17-
| **Python** | SaltStack only | No other Python permitted |
1832
| **Nickel** | Configuration language | For complex configs |
19-
| **Guile Scheme** | State/meta files | STATE.scm, META.scm, ECOSYSTEM.scm |
33+
| **Guile Scheme** | State/meta files | STATE.scm, META.scm, etc. |
2034
| **Julia** | Batch scripts, data processing | Per RSR |
2135
| **OCaml** | AffineScript compiler | Language-specific |
2236
| **Ada** | Safety-critical systems | Where required |
@@ -31,11 +45,24 @@
3145
| Bun | Deno |
3246
| pnpm/yarn | Deno |
3347
| Go | Rust |
34-
| Python (general) | ReScript/Rust |
48+
| **Python** | ReScript/Rust |
3549
| Java/Kotlin | Rust/Tauri/Dioxus |
3650
| Swift | Tauri/Dioxus |
3751
| React Native | Tauri/Dioxus |
3852
| Flutter/Dart | Tauri/Dioxus |
53+
| **Makefiles** | Mustfile/justfile |
54+
55+
**NOTE:** Python is fully banned. There are no exceptions (SaltStack exception removed 2026-01-03).
56+
57+
### Build System
58+
59+
All repositories use Mustfile/justfile instead of Makefiles:
60+
61+
- `Mustfile` - Mandatory checks definition
62+
- `justfile` - Build recipes (https://just.systems)
63+
- `mustfile.toml` - Configuration (optional)
64+
65+
See: https://github.com/hyperpolymath/mustfile
3966

4067
### Mobile Development
4168

@@ -52,15 +79,22 @@ Both are FOSS with independent governance (no Big Tech).
5279
2. **No package.json for runtime deps** - Use deno.json imports
5380
3. **No node_modules in production** - Deno caches deps automatically
5481
4. **No Go code** - Use Rust instead
55-
5. **Python only for SaltStack** - All other Python must be rewritten
82+
5. **No Python** - All Python must be rewritten
5683
6. **No Kotlin/Swift for mobile** - Use Tauri 2.0+ or Dioxus
84+
7. **No Makefiles** - Use Mustfile/justfile instead
5785

5886
### Package Management
5987

6088
- **Primary**: Guix (guix.scm)
6189
- **Fallback**: Nix (flake.nix)
6290
- **JS deps**: Deno (deno.json imports)
6391

92+
### Documentation Format
93+
94+
- All docs must be `.adoc` (AsciiDoc) except GitHub-required files
95+
- GitHub-required `.md`: SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, CHANGELOG.md
96+
- No duplicate formats (if `.adoc` exists, don't also have `.md`)
97+
6498
### Security Requirements
6599

66100
- No MD5/SHA1 for security (use SHA256+)

.github/workflows/doc-format.yml

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# SPDX-License-Identifier: AGPL-3.0-or-later
2+
name: Documentation Format Enforcement
3+
4+
on:
5+
push:
6+
branches: [main, master]
7+
pull_request:
8+
branches: [main, master]
9+
10+
permissions: read-all
11+
12+
jobs:
13+
check-doc-format:
14+
name: Check Documentation Format
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
19+
20+
- name: Check for duplicate documentation formats
21+
run: |
22+
DUPLICATES=0
23+
24+
# Check for docs that exist in both .md and .adoc (except GitHub-required)
25+
for doc in README ARCHITECTURE ROADMAP PHILOSOPHY INSTALL CHANGELOG; do
26+
if [ -f "${doc}.md" ] && [ -f "${doc}.adoc" ]; then
27+
echo "::error::Duplicate documentation: ${doc}.md and ${doc}.adoc both exist. Keep only .adoc"
28+
DUPLICATES=$((DUPLICATES + 1))
29+
fi
30+
done
31+
32+
# CONTRIBUTING can have both but .md should just be a redirect
33+
if [ -f "CONTRIBUTING.md" ] && [ -f "CONTRIBUTING.adoc" ]; then
34+
if ! grep -q "See.*CONTRIBUTING.adoc" CONTRIBUTING.md 2>/dev/null; then
35+
echo "::warning::CONTRIBUTING.md exists alongside CONTRIBUTING.adoc but is not a redirect"
36+
fi
37+
fi
38+
39+
if [ $DUPLICATES -gt 0 ]; then
40+
echo "::error::Found $DUPLICATES duplicate documentation files"
41+
exit 1
42+
fi
43+
44+
echo "✓ No duplicate documentation formats found"
45+
46+
- name: Check documentation uses .adoc
47+
run: |
48+
# List of files that MUST be .md for GitHub community health
49+
# SECURITY.md, CONTRIBUTING.md (can redirect), CODE_OF_CONDUCT.md, CHANGELOG.md
50+
51+
# Check README is .adoc (not .md)
52+
if [ -f "README.md" ] && [ ! -f "README.adoc" ]; then
53+
echo "::warning::README.md found without README.adoc. Consider converting to AsciiDoc."
54+
fi
55+
56+
# Check other docs are .adoc
57+
for doc in ARCHITECTURE ROADMAP PHILOSOPHY INSTALL; do
58+
if [ -f "${doc}.md" ]; then
59+
echo "::warning::${doc}.md should be ${doc}.adoc"
60+
fi
61+
done
62+
63+
echo "✓ Documentation format check complete"
64+
65+
- name: Verify GitHub-required files exist
66+
run: |
67+
# These files are required/preferred by GitHub in .md format
68+
MISSING=0
69+
70+
if [ ! -f "SECURITY.md" ]; then
71+
echo "::warning::SECURITY.md not found (required for GitHub security tab)"
72+
fi
73+
74+
if [ ! -f "LICENSE.txt" ] && [ ! -f "LICENSE" ]; then
75+
echo "::warning::LICENSE file not found"
76+
fi
77+
78+
echo "✓ GitHub-required files check complete"
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# SPDX-License-Identifier: AGPL-3.0-or-later
2+
name: Language Policy Enforcement
3+
4+
on:
5+
push:
6+
branches: [main, master]
7+
pull_request:
8+
branches: [main, master]
9+
10+
permissions: read-all
11+
12+
jobs:
13+
check-banned-languages:
14+
name: Check for Banned Languages
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
19+
20+
- name: Check for TypeScript files
21+
run: |
22+
if find . -name "*.ts" -o -name "*.tsx" | grep -v node_modules | grep -v ".d.ts" | head -1 | grep -q .; then
23+
echo "::error::TypeScript files found. Use ReScript instead."
24+
find . -name "*.ts" -o -name "*.tsx" | grep -v node_modules | grep -v ".d.ts"
25+
exit 1
26+
fi
27+
echo "✓ No TypeScript files found"
28+
29+
- name: Check for Go files
30+
run: |
31+
if find . -name "*.go" | head -1 | grep -q .; then
32+
echo "::error::Go files found. Use Rust instead."
33+
find . -name "*.go"
34+
exit 1
35+
fi
36+
echo "✓ No Go files found"
37+
38+
- name: Check for Python files (except Ansible)
39+
run: |
40+
# Allow Python only in ansible/ directories or for Ansible-specific files
41+
PYTHON_FILES=$(find . -name "*.py" | grep -v __pycache__ | grep -v ".venv" | grep -v "ansible" | grep -v "molecule" || true)
42+
if [ -n "$PYTHON_FILES" ]; then
43+
echo "::error::Python files found outside Ansible context. Rewrite in Rust/ReScript."
44+
echo "$PYTHON_FILES"
45+
exit 1
46+
fi
47+
echo "✓ No unauthorized Python files found"
48+
49+
- name: Check for Makefiles
50+
run: |
51+
MAKEFILES=$(find . -name "Makefile" -o -name "Makefile.*" -o -name "*.mk" | grep -v ".github" || true)
52+
if [ -n "$MAKEFILES" ]; then
53+
echo "::error::Makefiles found. Use Mustfile/justfile instead."
54+
echo "$MAKEFILES"
55+
exit 1
56+
fi
57+
echo "✓ No Makefiles found"
58+
59+
- name: Check for package.json (npm/node)
60+
run: |
61+
if [ -f "package.json" ]; then
62+
# Allow if it only contains devDependencies for tooling
63+
if grep -q '"dependencies"' package.json; then
64+
echo "::error::package.json with runtime dependencies found. Use deno.json instead."
65+
exit 1
66+
fi
67+
fi
68+
echo "✓ No npm runtime dependencies found"
69+
70+
- name: Check for Java/Kotlin files
71+
run: |
72+
if find . -name "*.java" -o -name "*.kt" -o -name "*.kts" | head -1 | grep -q .; then
73+
echo "::error::Java/Kotlin files found. Use Rust/Tauri/Dioxus instead."
74+
find . -name "*.java" -o -name "*.kt" -o -name "*.kts"
75+
exit 1
76+
fi
77+
echo "✓ No Java/Kotlin files found"
78+
79+
- name: Check for Swift files
80+
run: |
81+
if find . -name "*.swift" | head -1 | grep -q .; then
82+
echo "::error::Swift files found. Use Tauri/Dioxus instead."
83+
find . -name "*.swift"
84+
exit 1
85+
fi
86+
echo "✓ No Swift files found"
87+
88+
check-required-files:
89+
name: Check Required Files
90+
runs-on: ubuntu-latest
91+
steps:
92+
- name: Checkout
93+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
94+
95+
- name: Check for .machine_readable directory
96+
run: |
97+
if [ ! -d ".machine_readable" ]; then
98+
echo "::warning::.machine_readable/ directory not found"
99+
else
100+
echo "✓ .machine_readable/ directory exists"
101+
for scm in STATE META ECOSYSTEM AGENTIC NEUROSYM PLAYBOOK; do
102+
if [ ! -f ".machine_readable/${scm}.scm" ]; then
103+
echo "::warning::Missing .machine_readable/${scm}.scm"
104+
else
105+
echo "✓ .machine_readable/${scm}.scm exists"
106+
fi
107+
done
108+
fi
109+
110+
- name: Check for Mustfile/justfile
111+
run: |
112+
if [ ! -f "Mustfile" ] && [ ! -f "justfile" ]; then
113+
echo "::warning::Neither Mustfile nor justfile found"
114+
else
115+
echo "✓ Build system files present"
116+
fi
117+
118+
- name: Check SPDX headers
119+
run: |
120+
MISSING_SPDX=0
121+
for ext in rs res js jsx mjs ts tsx py go java kt swift sh bash; do
122+
while IFS= read -r file; do
123+
if [ -n "$file" ] && ! head -5 "$file" | grep -q "SPDX-License-Identifier"; then
124+
echo "::warning::Missing SPDX header: $file"
125+
MISSING_SPDX=$((MISSING_SPDX + 1))
126+
fi
127+
done < <(find . -name "*.$ext" -type f 2>/dev/null | grep -v node_modules | grep -v .git | head -50)
128+
done
129+
if [ $MISSING_SPDX -gt 0 ]; then
130+
echo "::warning::$MISSING_SPDX files missing SPDX headers"
131+
fi
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# SPDX-License-Identifier: AGPL-3.0-or-later
2+
name: Makefile Blocker
3+
4+
on:
5+
push:
6+
paths:
7+
- '**/Makefile'
8+
- '**/Makefile.*'
9+
- '**/*.mk'
10+
pull_request:
11+
paths:
12+
- '**/Makefile'
13+
- '**/Makefile.*'
14+
- '**/*.mk'
15+
16+
permissions: read-all
17+
18+
jobs:
19+
block-makefiles:
20+
name: Block Makefile Changes
21+
runs-on: ubuntu-latest
22+
steps:
23+
- name: Checkout
24+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
25+
26+
- name: Fail on Makefile presence
27+
run: |
28+
echo "::error::Makefiles are not permitted in Hyperpolymath repositories."
29+
echo ""
30+
echo "Use the Mustfile/justfile system instead:"
31+
echo " - Mustfile: Mandatory checks (see hyperpolymath/mustfile)"
32+
echo " - justfile: Build recipes (https://just.systems)"
33+
echo " - mustfile.toml: Configuration"
34+
echo ""
35+
echo "Found Makefiles:"
36+
find . -name "Makefile" -o -name "Makefile.*" -o -name "*.mk" | grep -v ".github"
37+
echo ""
38+
echo "To migrate, see: https://github.com/hyperpolymath/mustfile"
39+
exit 1

0 commit comments

Comments
 (0)