Skip to content

Commit c1f11cb

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
chore: add UX infrastructure (quickstart, doctor, setup)
Added by ux-rollout.jl batch script. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 4128b6b commit c1f11cb

9 files changed

Lines changed: 398 additions & 0 deletions

File tree

‎EXPLAINME.adoc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
= Git Reticulator — EXPLAINME
2+
:toc: preamble
3+
4+
This document backs up the claims made in README with evidence and rationale.
5+
6+
== What Is This?
7+
8+
Git Reticulator is a hyperpolymath project. See README.adoc for usage.
9+
10+
== Why These Choices?
11+
12+
=== Language
13+
14+
The language(s) used in this project were chosen per the hyperpolymath
15+
language policy (see CLAUDE.md for the full list of allowed/banned languages).
16+
17+
=== Architecture
18+
19+
Architecture decisions are documented in `.machine_readable/` checkpoint files.
20+
21+
== Alternatives Considered
22+
23+
(To be filled in as the project matures.)
24+
25+
== Proof of Claims
26+
27+
(Link formal verification results from the `proven` repo where applicable.)

‎Justfile‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,109 @@ fmt-check:
3939
# Run panic-attacker pre-commit scan
4040
assail:
4141
@command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker"
42+
43+
# ═══════════════════════════════════════════════════════════════════════════════
44+
# ONBOARDING & DIAGNOSTICS
45+
# ═══════════════════════════════════════════════════════════════════════════════
46+
47+
# Check all required toolchain dependencies and report health
48+
doctor:
49+
#!/usr/bin/env bash
50+
echo "═══════════════════════════════════════════════════"
51+
echo " Git Reticulator Doctor — Toolchain Health Check"
52+
echo "═══════════════════════════════════════════════════"
53+
echo ""
54+
PASS=0; FAIL=0; WARN=0
55+
check() {
56+
local name="$1" cmd="$2" min="$3"
57+
if command -v "$cmd" >/dev/null 2>&1; then
58+
VER=$("$cmd" --version 2>&1 | head -1)
59+
echo " [OK] $name — $VER"
60+
PASS=$((PASS + 1))
61+
else
62+
echo " [FAIL] $name — not found (need $min+)"
63+
FAIL=$((FAIL + 1))
64+
fi
65+
}
66+
check "just" just "1.25"
67+
check "git" git "2.40"
68+
check "Rust (cargo)" cargo "1.80"
69+
# Optional tools
70+
if command -v panic-attack >/dev/null 2>&1; then
71+
echo " [OK] panic-attack — available"
72+
PASS=$((PASS + 1))
73+
else
74+
echo " [WARN] panic-attack — not found (pre-commit scanner)"
75+
WARN=$((WARN + 1))
76+
fi
77+
echo ""
78+
echo " Result: $PASS passed, $FAIL failed, $WARN warnings"
79+
if [ "$FAIL" -gt 0 ]; then
80+
echo " Run 'just heal' to attempt automatic repair."
81+
exit 1
82+
fi
83+
echo " All required tools present."
84+
85+
# Attempt to automatically install missing tools
86+
heal:
87+
#!/usr/bin/env bash
88+
echo "═══════════════════════════════════════════════════"
89+
echo " Git Reticulator Heal — Automatic Tool Installation"
90+
echo "═══════════════════════════════════════════════════"
91+
echo ""
92+
if ! command -v cargo >/dev/null 2>&1; then
93+
echo "Installing Rust via rustup..."
94+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
95+
source "$HOME/.cargo/env"
96+
fi
97+
if ! command -v just >/dev/null 2>&1; then
98+
echo "Installing just..."
99+
cargo install just 2>/dev/null || echo "Install just from https://just.systems"
100+
fi
101+
echo ""
102+
echo "Heal complete. Run 'just doctor' to verify."
103+
104+
# Guided tour of the project structure and key concepts
105+
tour:
106+
#!/usr/bin/env bash
107+
echo "═══════════════════════════════════════════════════"
108+
echo " Git Reticulator — Guided Tour"
109+
echo "═══════════════════════════════════════════════════"
110+
echo ""
111+
echo 'A hyperpolymath project.'
112+
echo ""
113+
echo "Key directories:"
114+
echo " src/ Source code"
115+
echo " docs/ Documentation"
116+
echo " tests/ Test suite"
117+
echo " .github/workflows/ CI/CD workflows"
118+
echo ""
119+
echo "Quick commands:"
120+
echo " just doctor Check toolchain health"
121+
echo " just heal Fix missing tools"
122+
echo " just help-me Common workflows"
123+
echo " just default List all recipes"
124+
echo ""
125+
echo "Read more: README.adoc, EXPLAINME.adoc"
126+
127+
# Show help for common workflows
128+
help-me:
129+
#!/usr/bin/env bash
130+
echo "═══════════════════════════════════════════════════"
131+
echo " Git Reticulator — Common Workflows"
132+
echo "═══════════════════════════════════════════════════"
133+
echo ""
134+
echo "FIRST TIME SETUP:"
135+
echo " just doctor Check toolchain"
136+
echo " just heal Fix missing tools"
137+
echo ""
138+
echo "DEVELOPMENT:"
139+
echo " cargo build Build the project"
140+
echo " cargo test Run tests"
141+
echo ""
142+
echo "PRE-COMMIT:"
143+
echo " just assail Run panic-attacker scan"
144+
echo ""
145+
echo "LEARN:"
146+
echo " just tour Guided project tour"
147+
echo " just default List all recipes"

‎QUICKSTART-DEV.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
= Git Reticulator — Developer Quickstart
2+
:toc: preamble
3+
4+
Clone, build, test, contribute.
5+
6+
== Prerequisites
7+
8+
* Git 2.40+
9+
* just (command runner)
10+
* See `just doctor` output for language-specific requirements
11+
12+
== Setup
13+
14+
[source,bash]
15+
----
16+
git clone https://github.com/hyperpolymath/git-reticulator
17+
cd git-reticulator
18+
just doctor # verify toolchain
19+
just heal # auto-install missing tools
20+
----
21+
22+
== Development Workflow
23+
24+
[source,bash]
25+
----
26+
just tour # understand the codebase
27+
just help-me # see available commands
28+
----
29+
30+
== Before Committing
31+
32+
[source,bash]
33+
----
34+
just assail # run panic-attacker security scan
35+
----
36+
37+
== Contributing
38+
39+
See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines.

‎QUICKSTART-MAINTAINER.adoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
= Git Reticulator — Maintainer Quickstart
2+
:toc: preamble
3+
4+
Packaging, deployment, and release management.
5+
6+
== Prerequisites
7+
8+
* Git 2.40+
9+
* just (command runner)
10+
* Familiarity with the project (run `just tour` first)
11+
12+
== CI/CD
13+
14+
This project uses GitHub Actions. Workflows are in `.github/workflows/`.
15+
16+
Key workflows:
17+
18+
* `hypatia-scan.yml` — Neurosymbolic security scanning
19+
* `codeql.yml` — Code analysis
20+
* `scorecard.yml` — OpenSSF Scorecard
21+
* `mirror.yml` — GitLab/Bitbucket mirroring
22+
23+
== Releasing
24+
25+
1. Update version in project config
26+
2. Update CHANGELOG.md
27+
3. Tag: `git tag -s v<VERSION>`
28+
4. Push: `git push origin main --tags`
29+
30+
== Container Build (if applicable)
31+
32+
[source,bash]
33+
----
34+
podman build -f Containerfile -t git-reticulator:latest .
35+
----
36+
37+
== Mirrors
38+
39+
This repo is mirrored to GitLab and Bitbucket (hyperpolymath accounts)
40+
via the `mirror.yml` workflow.

‎QUICKSTART-USER.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
= Git Reticulator — User Quickstart
2+
:toc: preamble
3+
4+
Get up and running in 60 seconds.
5+
6+
== Prerequisites
7+
8+
* Git 2.40+
9+
* just (command runner) — https://just.systems
10+
11+
== Install
12+
13+
[source,bash]
14+
----
15+
git clone https://github.com/hyperpolymath/git-reticulator
16+
cd git-reticulator
17+
just doctor # check toolchain
18+
just heal # auto-install missing tools
19+
----
20+
21+
== First Run
22+
23+
[source,bash]
24+
----
25+
just tour # guided project tour
26+
just help-me # see common workflows
27+
----
28+
29+
== Get Help
30+
31+
* `just help-me` — common workflows
32+
* `just doctor` — diagnose toolchain issues
33+
* https://github.com/hyperpolymath/git-reticulator/issues — report bugs

‎contractiles/intend/Intentfile.a2ml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Intentfile (A2ML Canonical)
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
5+
@abstract:
6+
Declared intent and purpose for Git Reticulator.
7+
@end
8+
9+
## Purpose
10+
11+
Git Reticulator — A hyperpolymath project.
12+
13+
## Anti-Purpose
14+
15+
This project is NOT:
16+
- A fork or wrapper around another tool
17+
- A monorepo (unless explicitly structured as one)
18+
19+
## If In Doubt
20+
21+
If you are unsure whether a change is in scope, ask.
22+
Sensitive areas: ABI definitions, license headers, CI workflows.

‎contractiles/must/Mustfile.a2ml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Mustfile (A2ML Canonical)
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
5+
@abstract:
6+
Physical State contract for Git Reticulator. Baseline UX Manifesto invariants
7+
that MUST hold at all times.
8+
@end
9+
10+
@requires:
11+
- section: Core-Files
12+
- section: Banned
13+
@end
14+
15+
## Core-Files
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 must exist
24+
- run: test -f README.adoc || test -f README.md
25+
- severity: critical
26+
27+
## Banned
28+
29+
### no-hardcoded-paths
30+
- description: No hardcoded developer paths
31+
- run: "! grep -rn '/home/hyper\|/mnt/eclipse' --include='*.rs' --include='*.res' --include='*.ex' --include='*.gleam' --include='*.zig' --include='*.sh' . 2>/dev/null | grep -v '.git/' | grep -v 'ux-rollout.jl' | head -1"
32+
- severity: critical
33+
34+
### no-dockerfiles
35+
- description: No Dockerfiles (use Containerfile)
36+
- run: test ! -f Dockerfile
37+
- severity: warning
38+
39+
### no-makefiles
40+
- description: No Makefiles (use Justfile)
41+
- run: test ! -f Makefile
42+
- severity: warning

‎contractiles/trust/Trustfile.a2ml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Trustfile (A2ML Canonical)
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
5+
@abstract:
6+
Trust and provenance verification for Git Reticulator.
7+
Maximal trust by default — LLM may read, build, test, lint, format.
8+
@end
9+
10+
@trust-level: maximal
11+
@trust-boundary: repo
12+
@trust-actions: [read, build, test, lint, format]
13+
@trust-deny: [delete-branch, force-push, modify-ci-secrets, publish]
14+
15+
## Integrity
16+
17+
### license-content
18+
- description: LICENSE contains expected SPDX identifier
19+
- run: grep -q 'SPDX\|License\|MIT\|Apache\|PMPL\|MPL' LICENSE
20+
- severity: critical
21+
22+
### no-secrets-committed
23+
- description: No .env or credential files in repo
24+
- run: test ! -f .env && test ! -f credentials.json && test ! -f .env.local
25+
- severity: critical

0 commit comments

Comments
 (0)