Skip to content

Commit 2d2723e

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
README batch 4/4: 4 utility-dir READMEs (audit item 3 — CLOSED)
Final batch. Closes per-directory README coverage. Note: * The audit listed `benches/` as missing but the directory itself does not exist; treating that audit entry as resolved-by-absence. Total covered = 4 (not 5) for this batch. Files added (all .adoc, all SPDX-headed): * docs/README.adoc — substantive map of the ~49-file documentation tree; subdir orientation (governance/, reports/audit/); per-file purpose for ARCHITECTURE, LEAN4_RUST_CORRESPONDENCE, PROOF_HOLES_AUDIT, POSIX_COMPLIANCE, the 10 PHASE6_M*_DESIGN docs, USER_GUIDE, CITATIONS, etc. Acknowledges the audit's flat-layout finding but maps the actual content honestly. * scripts/README.adoc — 6 shell helpers; each cited with its CI consumer; flags audit items 6 (verify-proofs gate) and 10b (Echidna integration partial) where relevant. * examples/README.adoc — sparse honestly: only 2 ReScript files present, not vsh shell examples. Points readers at the docs/COMPREHENSIVE_EXAMPLES.md and docs/DEMO_EXTERNAL_COMMANDS.md where actual vsh examples live, plus the manual_*.sh test scripts that double as examples. * hooks/README.adoc — 4 validation hooks; each maps to one hyperpolymath-policy clause (SPDX, workflow permissions, SHA pins, CodeQL); cites quality.yml CI consumer. == Audit item 3 closure Per-directory README coverage moves from the 2026-04-18 audit's 5/22 (~23%) baseline to **24/24 (100%) of the 19 originally-missing subtrees** addressed across batches 1-4 plus the resolved-by-absence benches/. **Item 3 of CRG-AUDIT-2026-04-18 closure list is closed.** Remaining audit items: 6 (verify-proofs CI), 8 (contractile six-verb restructure), 10a (47 spoofed authors — needs human auth), 10b (Echidna CI wiring). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 03705b5 commit 2d2723e

4 files changed

Lines changed: 237 additions & 0 deletions

File tree

‎docs/README.adoc‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= docs/ — Project Documentation
3+
4+
Project-level documentation tree. ~49 entries (subdirs + files);
5+
historically flat-organised — the 2026-04-18 audit flagged the lack of
6+
`docs/architecture/`, `docs/decisions/`, `docs/practice/`, `docs/wikis/`
7+
subtrees as a coverage gap, but the existing files are themselves
8+
well-maintained.
9+
10+
This README provides orientation; individual files are self-describing.
11+
12+
== Subdirectories
13+
14+
[cols="2,4"]
15+
|===
16+
| Path | Role
17+
18+
| `governance/`
19+
| Authoritative governance artefacts. Currently
20+
`CRG-AUDIT-2026-04-18.adoc` (the active audit driving the v0.9.x
21+
closure list); future audits land here.
22+
23+
| `reports/audit/`
24+
| Historical audit snapshots; currently `audit-2026-04-04.md` (M2
25+
estate audit, "REPAIR THEN PUBLISH" verdict).
26+
|===
27+
28+
== Top-level files (selection)
29+
30+
[cols="2,4"]
31+
|===
32+
| File | Purpose
33+
34+
| `ARCHITECTURE.md` + `ARCHITECTURE_DIAGRAMS.md`
35+
| System-level architecture overview.
36+
37+
| `LEAN4_RUST_CORRESPONDENCE.md`
38+
| Design of the Lean → Rust correspondence (currently
39+
property-tested, not mechanised; ~85% confidence per CLAUDE.md).
40+
41+
| `PROOF_HOLES_AUDIT.md`
42+
| Active proof-debt ledger across the 6-system stack
43+
(Coq/Lean4/Agda/Isabelle/Mizar/Z3 + Idris2 ABI). Source of truth for
44+
the `[coq-proof-status]` block in `../.machine_readable/6a2/STATE.a2ml`.
45+
46+
| `POSIX_COMPLIANCE.md`
47+
| Per-feature POSIX compliance tracker (M1-M11 milestones; M1-M9
48+
complete, M10-M11 partial).
49+
50+
| `PROOF_OVERVIEW.md` + `PROPERTY_TESTING.md` + `VERIFICATION_STRATEGY_ANALYSIS.md`
51+
| Verification approach + property-testing discipline.
52+
53+
| `SEAM_ANALYSIS_AND_IDRIS2_PLAN.md` + `ZIG_LEAN_EXTRACTION.md`
54+
| Future-direction designs (Idris2 extraction; Zig-Lean integration).
55+
56+
| `ECHIDNA_INTEGRATION.md`
57+
| Echidna validator integration spec (audit item 10b — wiring still
58+
TODO; spec is the design source).
59+
60+
| `PHASE2_REPORT.md` / `PHASE3_INITIAL_REPORT.md` / `PHASE6_M*_DESIGN.md` (10 docs)
61+
| Per-phase milestone designs and reports. The PHASE6_M*_DESIGN docs
62+
enumerate Phase 6 milestones M1-M13.
63+
64+
| `USER_GUIDE.md`
65+
| End-user documentation for the `vsh` shell.
66+
67+
| `CITATIONS.adoc`
68+
| Academic citations + references.
69+
70+
| `CONTRIBUTOR_GUIDE_TIER1.md`
71+
| Tier-1 contribution guide.
72+
73+
| `OCAML_EXTRACTION.md`
74+
| OCaml extraction design (companion to `../impl/ocaml/README.adoc`).
75+
76+
| `INTEGRATION.md`
77+
| Cross-system integration notes.
78+
79+
| `CONSOLIDATION_ANALYSIS.md` / `CONTINUATION_REPORT.md` /
80+
`SIMPLIFICATION_OPPORTUNITIES.md`
81+
| Audit-style review documents.
82+
83+
| `COMPREHENSIVE_EXAMPLES.md` / `DEMO_EXTERNAL_COMMANDS.md`
84+
| Worked examples + REPL demos.
85+
|===
86+
87+
== Conventions
88+
89+
* Mixed `.md` (legacy) and `.adoc` (current preferred per RSR
90+
conventions). New documents should use `.adoc`.
91+
* Each file is self-describing; no central index file beyond this README.
92+
* Per-domain subtrees (`governance/`, `reports/`) collect related artefacts.
93+
94+
== See also
95+
96+
* `../README.md` / `../EXPLAINME.adoc` — repo entry points
97+
* `../CLAUDE.md` — AI-assistant honest-status document
98+
* `../ROADMAP.adoc` — release track + audit closure list
99+
* `../.machine_readable/6a2/STATE.a2ml` — machine-readable state

‎examples/README.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= examples/ — Example Code (sparse)
3+
4+
Example artefacts. Currently only two files; mainly placeholder for a
5+
future shell-script example library.
6+
7+
== Files
8+
9+
[cols="2,4"]
10+
|===
11+
| File | Role
12+
13+
| `SafeDOMExample.res`
14+
| ReScript example demonstrating the safe-DOM pattern. Reference
15+
artefact, not a vsh example.
16+
17+
| `web-project-deno.json`
18+
| Deno project manifest companion to the ReScript example.
19+
|===
20+
21+
== Status
22+
23+
These two files are reference material from a related ReScript pattern
24+
demo, not shell-scripting examples for `vsh` itself. Real `vsh`
25+
examples (control-flow, transactions, redirection) currently live in
26+
the documentation under `../docs/COMPREHENSIVE_EXAMPLES.md` and
27+
`../docs/DEMO_EXTERNAL_COMMANDS.md`.
28+
29+
A proper `examples/shell/` subtree of vsh-runnable scripts is on the
30+
roadmap but not yet populated.
31+
32+
== See also
33+
34+
* `../docs/COMPREHENSIVE_EXAMPLES.md` — worked vsh examples
35+
* `../docs/DEMO_EXTERNAL_COMMANDS.md` — REPL demo scripts
36+
* `../impl/rust-cli/tests/manual_redirect_test.sh` /
37+
`../impl/rust-cli/tests/manual_sigint_test.sh` — interactive
38+
manual scripts that double as small examples

‎hooks/README.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= hooks/ — Repository Validation Hooks
3+
4+
POSIX-shell validation hooks invoked by Git pre-commit / pre-push
5+
flows and the `../.github/workflows/quality.yml` CI job. Each hook
6+
enforces one project-wide policy from the hyperpolymath standard
7+
(`../CLAUDE.md`).
8+
9+
== Files
10+
11+
[cols="2,4"]
12+
|===
13+
| Hook | Enforces
14+
15+
| `validate-spdx.sh`
16+
| Every source file carries an SPDX `License-Identifier` header
17+
(typically `PMPL-1.0-or-later`; third-party files preserve their
18+
original).
19+
20+
| `validate-permissions.sh`
21+
| GitHub Actions workflows declare a `permissions:` block (workflow-
22+
or job-level) — never default-write.
23+
24+
| `validate-sha-pins.sh`
25+
| Third-party Action references in workflows are SHA-pinned per the
26+
CLAUDE.md "Common GitHub Actions SHA Pins" table — not floating
27+
`@v6`-style refs.
28+
29+
| `validate-codeql.sh`
30+
| CodeQL workflow's language matrix matches the actual file extensions
31+
present in the repo.
32+
|===
33+
34+
== Run conventions
35+
36+
These run from CI by default. To execute locally:
37+
38+
```bash
39+
bash hooks/validate-spdx.sh # individual hook
40+
just lint # if Justfile wraps them
41+
```
42+
43+
== See also
44+
45+
* `../CLAUDE.md` — project-wide policy these hooks enforce
46+
* `../.github/workflows/quality.yml` — CI workflow that drives them
47+
* `../Mustfile` — mandatory-checks declaration (lints / tests / fmt)

‎scripts/README.adoc‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= scripts/ — Utility Scripts
3+
4+
POSIX-shell helper scripts driven by the project's CI workflows and
5+
local development recipes. All shell-only; no banned-language scripts
6+
per the `../CLAUDE.md` language policy.
7+
8+
== Files
9+
10+
[cols="2,4"]
11+
|===
12+
| Script | Purpose
13+
14+
| `validate-correspondence.sh`
15+
| Drives the Lean → Rust correspondence validation. Invoked by
16+
`../.github/workflows/validation.yml validate-correspondence` job.
17+
18+
| `validate-with-echidna.sh`
19+
| Echidna validator entry point. Invoked by
20+
`../.github/workflows/echidna-validation.yml`. Wiring is partial —
21+
audit item 10b tracks full Echidna CI integration.
22+
23+
| `verify-proofs.sh`
24+
| Proof-system verification helper (Coq / Lean / etc.).
25+
`verify-proofs` job in `validation.yml` is currently gated
26+
(`if: false`) per audit item 6.
27+
28+
| `generate-verification-report.sh`
29+
| Emits a `validation-report.md` artefact uploaded by the
30+
validate-correspondence job.
31+
32+
| `security-audit.sh`
33+
| Local security-audit helper; not currently CI-automated (audit
34+
finding under "Low Priority").
35+
36+
| `demo_verified_operations.sh`
37+
| End-to-end demo: runs through the verified filesystem operation
38+
suite as a smoke check.
39+
|===
40+
41+
== Run conventions
42+
43+
```bash
44+
bash scripts/<script>.sh # from repo root
45+
just <recipe> # if a Justfile recipe wraps it
46+
```
47+
48+
== See also
49+
50+
* `../.github/workflows/` — CI workflows that invoke these scripts
51+
* `../Justfile` — top-level recipe orchestration
52+
* `../docs/governance/CRG-AUDIT-2026-04-18.adoc` — audit list of
53+
CI / verification gaps (items 6 + 10b)

0 commit comments

Comments
 (0)