Skip to content

Commit 934b848

Browse files
hyperpolymathclaude
andcommitted
docs: replace template README and fix EXPLAINME {project-name} placeholder
README now describes nesy-solver: public proof playground at nesy-solver.dev, multi-formalism support (SMT-LIB, Lean 4, Coq/Rocq, Idris2, Agda), and the Hypatia+Echidna+VeriSim architecture. EXPLAINME title placeholder fixed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 07375d3 commit 934b848

2 files changed

Lines changed: 34 additions & 161 deletions

File tree

EXPLAINME.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
// SPDX-License-Identifier: PMPL-1.0-or-later
2-
= {project-name} — Show Me The Receipts
2+
= nesy-solver — Show Me The Receipts
33
:toc:
44
:icons: font
55

README.adoc

Lines changed: 33 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -1,175 +1,48 @@
1-
= RSR Template Repository
2-
:toc: preamble
3-
:icons: font
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= nesy-solver
3+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
4+
:toc:
5+
:toc-placement: preamble
46

5-
image:https://www.bestpractices.dev/projects/TBD/badge[OpenSSF Best Practices, link="https://www.bestpractices.dev/projects/TBD"]
6-
image:https://api.securityscorecards.dev/projects/github.com/hyperpolymath/nesy-solver/badge[OpenSSF Scorecard, link="https://securityscorecards.dev/viewer/?uri=github.com/hyperpolymath/nesy-solver"]
7-
8-
[TIP]
9-
====
10-
**AI-Assisted Install:** Just tell any AI assistant: +
11-
`Set up Nesy Solver from https://github.com/hyperpolymath/nesy-solver` +
12-
The AI reads the manifest, asks you a few questions, and handles everything.
13-
====
7+
Public proof playground at link:https://nesy-solver.dev[nesy-solver.dev] — submit
8+
proof obligations, get prover recommendations, stream verdicts back live.
149

1510
== Overview
1611

17-
**The canonical template for RSR (Rhodium Standard Repository) projects.**
18-
19-
This project follows a **Dual-Track** architecture:
20-
* **Root:** High-level orientation and rich documentation for humans.
21-
* **Sub-directories:** Machine-readable metadata and technical implementation.
22-
23-
== ABI/FFI Standard (Verified Interface Seams)
12+
`nesy-solver` is the interactive frontend for the hyperpolymath neurosymbolic
13+
learning loop. It connects users directly to the Hypatia + Echidna + VeriSim
14+
pipeline:
2415

25-
All projects with foreign function interfaces MUST follow this consolidated standard:
16+
1. Submit a proof obligation in SMT-LIB, Lean 4, Coq/Rocq, Idris2, or Agda
17+
2. The app recommends a prover strategy based on live `proof_attempts` data
18+
in VeriSim
19+
3. Dispatches to Echidna for execution
20+
4. Streams the verdict back in real time
21+
5. Records the attempt in `verisim-api` — the playground improves its
22+
recommendations over time from actual usage data
2623

27-
* **ABI (Idris2):** `src/interface/abi/*.idr` (The Specification)
28-
* **FFI (Zig):** `src/interface/ffi/src/*.zig` (The Implementation)
29-
* **Generated:** `src/interface/generated/*.h` (The Artifacts)
24+
== Supported Formalisms
3025

31-
This unification ensures that the "Truth," the "Bridge," and the "Result" are managed as a single architectural unit.
26+
* SMT-LIB (Z3, CVC5)
27+
* Lean 4
28+
* Coq / Rocq
29+
* Idris2
30+
* Agda
3231

33-
== AI Gatekeeper Protocol
34-
35-
All projects MUST include a root `0-AI-MANIFEST.a2ml`. This is the mandatory entry point for all AI agents. It prevents duplicate file errors and preserves architectural invariants across sessions.
36-
37-
== Repository Structure
32+
== Architecture
3833

3934
[cols="1,3"]
4035
|===
41-
|Directory |Purpose
42-
43-
|`.github/`
44-
|Forge-specific metadata (CODEOWNERS, SECURITY.md, workflows).
45-
46-
|`.machine_readable/`
47-
|Canonical project state (6 a2ml files), bot directives, and AI guides.
48-
49-
|`container/`
50-
|Stapeln container ecosystem (selur-compose, vordr, rokur).
51-
52-
|`docs/`
53-
|Technical documentation sorted by tracks (Theory, Practice, Architecture).
54-
55-
|`docs/legal/`
56-
|Consolidated legal exhibits and full license texts.
57-
58-
|`src/interface/`
59-
|Unified ABI/FFI/Generated interface unit.
36+
| Component | Role
37+
38+
| `web/` | Frontend (ReScript + Deno)
39+
| `src/core/` | Proof dispatch and strategy selection
40+
| `src/interface/abi/` | Idris2 ABI for prover interface contracts
41+
| `src/interface/ffi/` | Zig FFI bridge to Echidna + external provers
42+
| `deploy/` | Container deployment (Containerfile, Podman)
43+
| `verisim-api` | External: records proof attempts, drives strategy recommendations
6044
|===
6145

62-
== Container Ecosystem (Stapeln)
63-
64-
This template includes a complete `container/` directory for the **Stapeln Six** tools:
65-
1. **selur** (Orchestration)
66-
2. **cerro-torre** (Verified Packaging)
67-
3. **svalinn** (Edge Gateway)
68-
4. **vordr** (Monitoring)
69-
5. **rokur** (Secrets)
70-
6. **k9-svc** (Deployment Contracts)
71-
72-
== Quick Start
73-
74-
[source,bash]
75-
----
76-
just init # Interactive bootstrap
77-
just build # Unified build
78-
just test # Unified test
79-
just container-build # Build verified OCI image
80-
----
81-
82-
== Contractile System
83-
84-
This template includes five **contractile files** in `.machine_readable/contractiles/` that make your repository's rules executable:
85-
86-
[cols="1,2,3"]
87-
|===
88-
| Tool | File | Purpose
89-
90-
| `must check`
91-
| `Mustfile.a2ml`
92-
| Physical state invariants (files exist, code compiles, no secrets)
93-
94-
| `trust verify`
95-
| `Trustfile.a2ml`
96-
| Integrity verification (hashes valid, signatures correct, provenance traceable)
97-
98-
| `dust status`
99-
| `Dustfile.a2ml`
100-
| Cleanup tasks (stale files, build artifacts, expired tokens)
101-
102-
| `intend list`
103-
| `Intentfile.a2ml`
104-
| Design intent and roadmap tracking
105-
106-
| `k9 eval`
107-
| `*.k9.ncl`
108-
| Nickel-based deployment validation
109-
|===
110-
111-
=== Installation
112-
113-
[source,bash]
114-
----
115-
cargo install contractile
116-
117-
# Create symlinks for individual commands
118-
for cmd in must trust dust intend k9; do
119-
ln -sf $(which contractile) ~/.local/bin/$cmd
120-
done
121-
----
122-
123-
=== Usage
124-
125-
[source,bash]
126-
----
127-
# Symlink contractiles to project root (CLI searches ./contractiles/)
128-
ln -sf .machine_readable/contractiles contractiles
129-
130-
# Run checks
131-
must check # Verify physical state (23 checks in typical RSR project)
132-
trust verify # Verify integrity and provenance
133-
dust status # Show cleanup items
134-
intend list # Show design intents and roadmap
135-
136-
# Generate Just recipes from contractile files
137-
contractile gen-just # Creates contractile.just (already imported by Justfile)
138-
139-
# Then use via Just:
140-
just must-check
141-
just trust-verify
142-
----
143-
144-
=== Writing Checks
145-
146-
Contractile files use A2ML format — simple, line-oriented:
147-
148-
[source]
149-
----
150-
### check-name
151-
- description: Human-readable description
152-
- run: shell command (exit 0 = pass, non-zero = fail)
153-
- severity: critical | warning | info
154-
----
155-
156-
See link:https://github.com/hyperpolymath/contractiles[contractiles documentation] for the full specification.
157-
158-
== Wondering How This Works?
159-
160-
If you're curious about the tech behind the claims in this README, see
161-
link:EXPLAINME.adoc[EXPLAINME.adoc] — feature highlights with code paths
162-
and honest caveats. Questions welcome via issues or direct contact.
163-
164-
== Documentation
165-
166-
* link:EXPLAINME.adoc[Show Me The Receipts] — how headline features work
167-
* link:CONTRIBUTING.adoc[Contributing Guide]
168-
* link:GOVERNANCE.adoc[Governance Model]
169-
* link:docs/attribution/MAINTAINERS.adoc[Maintainers & Citations]
170-
* link:SECURITY.adoc[Security Policy]
171-
17246
== License
17347

174-
SPDX-License-Identifier: PMPL-1.0-or-later
175-
See link:LICENSE[LICENSE] and link:docs/legal/[docs/legal/] for details.
48+
PMPL-1.0-or-later. See link:LICENSE[LICENSE].

0 commit comments

Comments
 (0)