From 36b3306f6ad1c8f581a48d1968b345d6e41be563 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:29:39 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- CHANGELOG.adoc | 73 +++++++++++++++ CHANGELOG.md | 67 -------------- CODE_OF_CONDUCT.adoc | 24 +++++ CODE_OF_CONDUCT.md | 27 ------ CONTRIBUTING.adoc | 109 ++++++++++++++++++++++ CONTRIBUTING.md | 116 ------------------------ GOVERNANCE.adoc | 60 ++++++++++++ GOVERNANCE.md | 60 ------------ PROOF-NEEDS.adoc | 50 ++++++++++ PROOF-NEEDS.md | 27 ------ REQUIRES_INITIALISATION.adoc | 161 +++++++++++++++++++++++++++++++++ REQUIRES_INITIALISATION.md | 158 -------------------------------- SECURITY.adoc | 24 +++++ SECURITY.md | 25 ----- TEST-NEEDS.adoc | 128 ++++++++++++++++++++++++++ TEST-NEEDS.md | 80 ---------------- TOPOLOGY.md => TOPOLOGY.adoc | 39 ++++---- docs/tech-debt-2026-05-26.adoc | 71 +++++++++++++++ docs/tech-debt-2026-05-26.md | 57 ------------ llm-warmup-dev.adoc | 19 ++++ llm-warmup-dev.md | 16 ---- llm-warmup-user.adoc | 19 ++++ llm-warmup-user.md | 16 ---- 23 files changed, 756 insertions(+), 670 deletions(-) create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 REQUIRES_INITIALISATION.adoc delete mode 100644 REQUIRES_INITIALISATION.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md rename TOPOLOGY.md => TOPOLOGY.adoc (90%) create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..18ef4dc --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,73 @@ +== Changelog + +All notable changes to `+neural-foundations+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(crg): add crg-grade and crg-badge justfile recipes +* feat: add stapeln.toml container definition +* feat: add UX Justfile with doctor, tour, help-me, assail recipes +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration + +==== Fixed + +* fix(ci): bump a2ml/k9-validate-action pins to canonical (#57) +* fix(ci): sync hypatia-scan.yml to canonical (#56) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): hypatia-scan.yml – –exit-zero + GITHUB_TOKEN +(hyperpolymath/hypatia#213) (#52) +* fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#53) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#54) +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: SPDX headers (AGPL→PMPL), email, author name +* fix(license): SPDX AGPL-3.0 → PMPL-1.0-or-later in dotfiles + +==== Changed + +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: substantive CRG C annotation (EXPLAINME.adoc) +* docs: add CRG Grade C header to TEST-NEEDS.md +* docs: add TEST-NEEDS.md and PROOF-NEEDS.md from audit +* docs: add EXPLAINME.adoc — prove-it file backing README claims + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#59) +* ci(secret-scanner): drop duplicate –fail from trufflehog extra_args +(#51) +* ci: bump actions/upload-artifact SHA to current v4 (#50) +* ci: SHA-pin hyperpolymath validate-actions in dogfood-gate +* ci(antipattern): fix top-level dir + benchmark/lsp filename matching +(#49) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 2becdc2..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,67 +0,0 @@ - - -# Changelog - -All notable changes to `neural-foundations` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat(crg): add crg-grade and crg-badge justfile recipes -- feat: add stapeln.toml container definition -- feat: add UX Justfile with doctor, tour, help-me, assail recipes -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration - -### Fixed - -- fix(ci): bump a2ml/k9-validate-action pins to canonical (#57) -- fix(ci): sync hypatia-scan.yml to canonical (#56) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): hypatia-scan.yml -- --exit-zero + GITHUB_TOKEN (hyperpolymath/hypatia#213) (#52) -- fix(ci): rsr-antipattern duplicate heredoc + setup-beam ubuntu24 (#53) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#54) -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: SPDX headers (AGPL→PMPL), email, author name -- fix(license): SPDX AGPL-3.0 → PMPL-1.0-or-later in dotfiles - -### Changed - -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: substantive CRG C annotation (EXPLAINME.adoc) -- docs: add CRG Grade C header to TEST-NEEDS.md -- docs: add TEST-NEEDS.md and PROOF-NEEDS.md from audit -- docs: add EXPLAINME.adoc — prove-it file backing README claims - -### CI - -- ci: redistribute concurrency-cancel guard to read-only check workflows (#59) -- ci(secret-scanner): drop duplicate --fail from trufflehog extra_args (#51) -- ci: bump actions/upload-artifact SHA to current v4 (#50) -- ci: SHA-pin hyperpolymath validate-actions in dogfood-gate -- ci(antipattern): fix top-level dir + benchmark/lsp filename matching (#49) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..2554c90 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/neural-foundations.git cd +neural-foundations + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create neural-foundations-dev toolbox enter +neural-foundations-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +neural-foundations/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/neural-foundations/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/neural-foundations/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/neural-foundations/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/neural-foundations/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 6d2bb60..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/neural-foundations.git -cd neural-foundations - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create neural-foundations-dev -toolbox enter neural-foundations-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -neural-foundations/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/neural-foundations/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/neural-foundations/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/neural-foundations/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/neural-foundations/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..70f9f16 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,50 @@ +== PROOF-NEEDS.md — neural-foundations + +=== Current State + +* **src/abi/*.idr**: YES (in satellites) — echidna has +`+BojForeign.idr+`, `+Foreign.idr+`, `+Layout.idr+`, `+Overlay.idr+` +* *Dangerous patterns*: 0 in own code (27 references are all in +rule/detection code that identifies dangerous patterns in other repos) +* *LOC*: ~153,000 (Rust + Agda + Julia + Idris2) +* *ABI layer*: ECHIDNA has comprehensive Idris2 ABI with explicit "`NO +believe_me`" invariant +* *Existing proofs*: Agda proofs in `+echidna/proofs/agda/+` and +`+echidna/meta-checker/+` + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|ECHIDNA axiom safety checker |Meta-checker correctly classifies all +axiom types |The tool that checks OTHER proofs must itself be proven +correct + +|ECHIDNA prover integrations |Each prover bridge (Dafny, dReal, Frama-C, +F*, Imandra, Kissat, MetaMath, MiniZinc, Mizar, NuSMV, PRISM) faithfully +translates |Incorrect translation makes proof results meaningless + +|LLM-unify parser correctness |Claude/Copilot/Gemini parsers extract +correct structured data |Wrong parsing produces incorrect model +comparisons + +|Elegant-state consensus |Voting/proposal mechanism produces correct +outcomes |Distributed consensus bugs lose data + +|Conative-gating SLM |Small language model gating decisions are sound +|Incorrect gating passes unsafe content +|=== + +=== Recommended Prover + +*Agda* for ECHIDNA meta-checker (already in Agda). *Idris2* for ABI +layer extensions. The prover bridge translations are ideal for *Lean4* +relational proofs. + +=== Priority + +*HIGH* — ECHIDNA is the proof verification meta-tool. If the +meta-checker itself has bugs, it undermines all downstream formal +verification. The existing Agda proofs need extension to cover all +prover bridges. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 6fc6713..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,27 +0,0 @@ -# PROOF-NEEDS.md — neural-foundations - -## Current State - -- **src/abi/*.idr**: YES (in satellites) — echidna has `BojForeign.idr`, `Foreign.idr`, `Layout.idr`, `Overlay.idr` -- **Dangerous patterns**: 0 in own code (27 references are all in rule/detection code that identifies dangerous patterns in other repos) -- **LOC**: ~153,000 (Rust + Agda + Julia + Idris2) -- **ABI layer**: ECHIDNA has comprehensive Idris2 ABI with explicit "NO believe_me" invariant -- **Existing proofs**: Agda proofs in `echidna/proofs/agda/` and `echidna/meta-checker/` - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| ECHIDNA axiom safety checker | Meta-checker correctly classifies all axiom types | The tool that checks OTHER proofs must itself be proven correct | -| ECHIDNA prover integrations | Each prover bridge (Dafny, dReal, Frama-C, F*, Imandra, Kissat, MetaMath, MiniZinc, Mizar, NuSMV, PRISM) faithfully translates | Incorrect translation makes proof results meaningless | -| LLM-unify parser correctness | Claude/Copilot/Gemini parsers extract correct structured data | Wrong parsing produces incorrect model comparisons | -| Elegant-state consensus | Voting/proposal mechanism produces correct outcomes | Distributed consensus bugs lose data | -| Conative-gating SLM | Small language model gating decisions are sound | Incorrect gating passes unsafe content | - -## Recommended Prover - -**Agda** for ECHIDNA meta-checker (already in Agda). **Idris2** for ABI layer extensions. The prover bridge translations are ideal for **Lean4** relational proofs. - -## Priority - -**HIGH** — ECHIDNA is the proof verification meta-tool. If the meta-checker itself has bugs, it undermines all downstream formal verification. The existing Agda proofs need extension to cover all prover bridges. diff --git a/REQUIRES_INITIALISATION.adoc b/REQUIRES_INITIALISATION.adoc new file mode 100644 index 0000000..3b21408 --- /dev/null +++ b/REQUIRES_INITIALISATION.adoc @@ -0,0 +1,161 @@ +== REQUIRES INITIALISATION + +*This repository is not finished being set up.* 14 substitution token(s) +across 4 file(s) still have no value. + +=== Why this is not already done + +This repo was created from `+hyperpolymath/rsr-template-repo+`. The mint +(`+just repo-init+`) fills every token that has a single mechanical +answer — owner, repo, author, dates, licence, branch — and it has done +so here. + +The tokens below are the ones it _deliberately cannot_ answer. They need +a decision or a fact that exists only in your head: what this project is +for, what command builds it, which port the service listens on, whether +a PGP key is held at all. The template’s own token vocabulary says as +much — you cannot sensibly answer "`required invariants`" in a +thirty-second bootstrap. + +They were left *visibly unfilled on purpose*. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +=== Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it +early does not finish the setup, it just conceals it — and the next +person or agent to arrive will reasonably assume the repo is complete. + +* *If you are a person:* delete this file yourself once the last item is +done. +* *If you are an agent:* resolve what you legitimately can, leave the +rest, and delete this file only when no token below remains anywhere in +the tree. Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically +once nothing is outstanding, so the safest way to finish is to fix the +tokens and let the check confirm it. + +=== What is needed, and where it goes + +==== `+{{BUILD_CMD}}+` + +The exact command that builds this project. + +Appears in: + +* `+QUICKSTART-DEV.adoc+` + +==== `+{{BUILD_OUTPUT_PATH}}+` + +Where the build artefact lands. + +Appears in: + +* `+QUICKSTART-MAINTAINER.adoc+` + +==== `+{{CONSUMER1}}+` + +A downstream repo that consumes this one. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{CONSUMER2}}+` + +A second downstream consumer. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEP1}}+` + +First named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEP2}}+` + +Second named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{DEPS}}+` + +Prose summary of runtime/build dependencies. + +Appears in: + +* `+QUICKSTART-MAINTAINER.adoc+` + +==== `+{{LANG_STACK}}+` + +The language stack, in prose. + +Appears in: + +* `+QUICKSTART-DEV.adoc+` + +==== `+{{MONOREPO_OR_STANDALONE}}+` + +Literally '`monorepo`' or '`standalone`'. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{MUST_INVARIANTS}}+` + +The invariants this project guarantees. Not answerable in a bootstrap; +it is the point of the repo. + +Appears in: + +* `+QUICKSTART-DEV.adoc+` + +==== `+{{ONE_PARAGRAPH_ANTI_PURPOSE}}+` + +A paragraph on what this deliberately is NOT for. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{ONE_PARAGRAPH_PURPOSE}}+` + +A paragraph on what this is for. + +Appears in: + +* `+.machine_readable/INTENT.contractile+` + +==== `+{{PROJECT_UNIQUE_STRENGTH}}+` + +What this does that its alternatives do not. + +Appears in: + +* `+.machine_readable/agent_instructions/methodology.a2ml+` + +==== `+{{TEST_CMD}}+` + +The exact command that runs its tests. + +Appears in: + +* `+QUICKSTART-DEV.adoc+` + +''''' + +Generated by the estate top-up pass. Rationale and the governing rulings +are in `+hyperpolymath/standards+`; the token vocabulary is +`+.machine_readable/ai/PLACEHOLDERS.adoc+` in `+rsr-template-repo+`. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md deleted file mode 100644 index 5d8e77d..0000000 --- a/REQUIRES_INITIALISATION.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# REQUIRES INITIALISATION - -**This repository is not finished being set up.** 14 substitution token(s) across 4 file(s) still have no value. - -## Why this is not already done - -This repo was created from `hyperpolymath/rsr-template-repo`. The mint -(`just repo-init`) fills every token that has a single mechanical answer — -owner, repo, author, dates, licence, branch — and it has done so here. - -The tokens below are the ones it *deliberately cannot* answer. They need a -decision or a fact that exists only in your head: what this project is for, -what command builds it, which port the service listens on, whether a PGP key -is held at all. The template's own token vocabulary says as much — you cannot -sensibly answer "required invariants" in a thirty-second bootstrap. - -They were left **visibly unfilled on purpose**. The alternatives were both -worse: inventing plausible values would put confident falsehoods into a -security policy and an architecture document, and silently deleting the -sections would hide the fact that a decision is owed. A visible gap is -honest; a fabricated answer is not. - -## Do not delete this file until every item below is resolved - -This file is the only marker that the work is outstanding. Deleting it early -does not finish the setup, it just conceals it — and the next person or agent -to arrive will reasonably assume the repo is complete. - -- **If you are a person:** delete this file yourself once the last item is done. -- **If you are an agent:** resolve what you legitimately can, leave the rest, - and delete this file only when no token below remains anywhere in the tree. - Do not delete it to make a gate go green. - -Re-running the estate top-up tool will remove this file automatically once -nothing is outstanding, so the safest way to finish is to fix the tokens and -let the check confirm it. - -## What is needed, and where it goes - -### `{{BUILD_CMD}}` - -The exact command that builds this project. - -Appears in: - -- `QUICKSTART-DEV.adoc` - -### `{{BUILD_OUTPUT_PATH}}` - -Where the build artefact lands. - -Appears in: - -- `QUICKSTART-MAINTAINER.adoc` - -### `{{CONSUMER1}}` - -A downstream repo that consumes this one. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{CONSUMER2}}` - -A second downstream consumer. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEP1}}` - -First named dependency, in .machine_readable/INTENT.contractile. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEP2}}` - -Second named dependency, in .machine_readable/INTENT.contractile. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{DEPS}}` - -Prose summary of runtime/build dependencies. - -Appears in: - -- `QUICKSTART-MAINTAINER.adoc` - -### `{{LANG_STACK}}` - -The language stack, in prose. - -Appears in: - -- `QUICKSTART-DEV.adoc` - -### `{{MONOREPO_OR_STANDALONE}}` - -Literally 'monorepo' or 'standalone'. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{MUST_INVARIANTS}}` - -The invariants this project guarantees. Not answerable in a bootstrap; it is the point of the repo. - -Appears in: - -- `QUICKSTART-DEV.adoc` - -### `{{ONE_PARAGRAPH_ANTI_PURPOSE}}` - -A paragraph on what this deliberately is NOT for. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{ONE_PARAGRAPH_PURPOSE}}` - -A paragraph on what this is for. - -Appears in: - -- `.machine_readable/INTENT.contractile` - -### `{{PROJECT_UNIQUE_STRENGTH}}` - -What this does that its alternatives do not. - -Appears in: - -- `.machine_readable/agent_instructions/methodology.a2ml` - -### `{{TEST_CMD}}` - -The exact command that runs its tests. - -Appears in: - -- `QUICKSTART-DEV.adoc` - ---- - -Generated by the estate top-up pass. Rationale and the governing rulings are -in `hyperpolymath/standards`; the token vocabulary is -`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..b0574df --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,24 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|< main |:x: +|=== + +=== Reporting a Vulnerability + +Please report security vulnerabilities through GitHub private +vulnerability reporting: 1. Go to the *Security* tab 2. Click *Report a +vulnerability* 3. Fill out the form + +We respond within 48 hours. + +=== Security Measures + +* Dependabot for dependency updates +* CodeQL for code scanning +* Secret scanning and push protection diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 159a0b7..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,25 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | -| < main | :x: | - -## Reporting a Vulnerability - -Please report security vulnerabilities through GitHub private vulnerability reporting: -1. Go to the **Security** tab -2. Click **Report a vulnerability** -3. Fill out the form - -We respond within 48 hours. - -## Security Measures - -- Dependabot for dependency updates -- CodeQL for code scanning -- Secret scanning and push protection - diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..f748340 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,128 @@ +== TEST-NEEDS.md — neural-foundations + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. +____ + +=== Current State — Updated 2026-04-04 + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |~8 |echidna: test_agda_backend.rs, +test_neural_integration.rs, ffi_integration_test.rs, prover tests +(unified_test.ts, prover_test.ts). llm-antidote: test_suite.py + +|Integration |~5 |echidna: integration_test.sh, Zig +core_native_test.zig, integration_test.zig. llm-unify: e2e_test.sh + +|E2E |3 |llm-unify e2e_test.sh, echidna tests/e2e_proof_pipeline.rs (29 +tests), llm-unify-core tests/e2e_routing_test.rs (10 tests) + +|P2P/Property |31 |echidna tests/neural_property_tests.rs — +embedding/dispatch/trust/hash/axiom/prover + +|Aspect |32 |echidna tests/security_aspect_tests.rs — +forgery/injection/escalation/axiom/integrity + +|Concurrency |27 |echidna tests/concurrency_test.rs — parallel +factory/routing/trust/hash/agent/axiom + +|Benchmarks |5 |echidna: proof_benchmarks.rs, routing_benchmarks.rs (7 +groups), benchmark.zig, overlay_benchmark.zig. llm-antidote: +benchmark.py +|=== + +*Source modules:* ~337 across 3 satellite groups. neurosymbolic/echidna: +~104 Rust src + Idris2 ABI + Zig FFI + Julia. foundation-models: +llm-antidote, llm-unify, llm-unify-core. agentic: elegant-state, +conative-gating, agentic-scm. + +=== What’s Missing (Remaining After 2026-04-04 Session) + +==== Completed in 2026-04-04 CRG C Blitz ✓ + +* [x] echidna E2E: full proof request → prover selection → proof +generation → verification (`+tests/e2e_proof_pipeline.rs+`) +* [x] llm-unify E2E: request → routing → normalisation → fallback +(`+crates/llm-unify-core/tests/e2e_routing_test.rs+`) +* [x] P2P property tests: embedding, dispatch, trust monotonicity, hash +stability, axiom ordering (`+tests/neural_property_tests.rs+`) +* [x] Security aspect tests: forgery, injection, escalation, axiom +sanitisation, integrity (`+tests/security_aspect_tests.rs+`) +* [x] Concurrency tests: parallel factory, routing, trust, hashing, +agent, axiom (`+tests/concurrency_test.rs+`) +* [x] Routing benchmarks: decision latency, axiom throughput, trust +computation, factory instantiation, agentic planning, BLAKE3 +(`+benches/routing_benchmarks.rs+`) + +==== Still Missing + +* [ ] Agentic E2E: agent lifecycle (create → plan → execute → evaluate) +for elegant-state, conative-gating +* [ ] LLM antidote adversarial property tests — NOTE: test_suite.py is +semi-manual and Python (banned). Needs rewrite in Julia or Rust. +* [ ] Cross-satellite: echidna proof + llm-unify inference in combined +workflow +* [ ] Fuzz harness: replace `+tests/fuzz/placeholder.txt+` with a real +cargo-fuzz harness + +==== P2P (Property-Based) Tests — Remaining + +* [ ] LLM antidote: adversarial input property tests (blocked: Python +banned, needs Julia rewrite) +* [ ] Prover backends: equivalence property tests across all 49 prover +implementations (coverage increase) + +==== Build & Execution + +* [ ] `+cargo test+` for echidna Rust +* [ ] `+zig build test+` for FFI +* [ ] Python test runner for llm-antidote +* [ ] Shell test execution for integration tests + +==== Benchmarks Needed + +* [ ] Proof generation latency by complexity +* [ ] LLM routing decision time +* [ ] Agent planning throughput +* [ ] Cross-prover comparison benchmarks +* [ ] Neural overlay inference time + +==== Self-Tests + +* [ ] Prover health checks (each backend reachable) +* [ ] Model availability verification +* [ ] Proof chain integrity validation + +==== CRITICAL GAPS + +[cols=",,,",options="header",] +|=== +|Subsystem |Source Files |Tests |Status +|echidna |~104 |~8 |*7.7% — insufficient* +|llm-antidote |unknown |1 suite |Minimal +|llm-unify |unknown |1 e2e |Minimal +|agentic (elegant-state) |unknown |1 archived |*Effectively 0* +|conative-gating |unknown |0 |*Untested* +|agentic-scm |unknown |0 |*Untested* +|=== + +=== Priority + +*CRITICAL.* 337 source files across a neurosymbolic AI framework with +~14 test files total. echidna at 104 Rust files with 8 tests is 7.7% +coverage. The agentic subsystem is completely untested. Benchmarks for +echidna are a bright spot, but the overall test story is woeful for a +framework that generates formal proofs — the proof engine itself needs +far more rigorous testing. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 686b9e7..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,80 +0,0 @@ -# TEST-NEEDS.md — neural-foundations - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. - -## Current State — Updated 2026-04-04 - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | ~8 | echidna: test_agda_backend.rs, test_neural_integration.rs, ffi_integration_test.rs, prover tests (unified_test.ts, prover_test.ts). llm-antidote: test_suite.py | -| Integration | ~5 | echidna: integration_test.sh, Zig core_native_test.zig, integration_test.zig. llm-unify: e2e_test.sh | -| E2E | 3 | llm-unify e2e_test.sh, echidna tests/e2e_proof_pipeline.rs (29 tests), llm-unify-core tests/e2e_routing_test.rs (10 tests) | -| P2P/Property | 31 | echidna tests/neural_property_tests.rs — embedding/dispatch/trust/hash/axiom/prover | -| Aspect | 32 | echidna tests/security_aspect_tests.rs — forgery/injection/escalation/axiom/integrity | -| Concurrency | 27 | echidna tests/concurrency_test.rs — parallel factory/routing/trust/hash/agent/axiom | -| Benchmarks | 5 | echidna: proof_benchmarks.rs, routing_benchmarks.rs (7 groups), benchmark.zig, overlay_benchmark.zig. llm-antidote: benchmark.py | - -**Source modules:** ~337 across 3 satellite groups. neurosymbolic/echidna: ~104 Rust src + Idris2 ABI + Zig FFI + Julia. foundation-models: llm-antidote, llm-unify, llm-unify-core. agentic: elegant-state, conative-gating, agentic-scm. - -## What's Missing (Remaining After 2026-04-04 Session) - -### Completed in 2026-04-04 CRG C Blitz ✓ - -- [x] echidna E2E: full proof request → prover selection → proof generation → verification (`tests/e2e_proof_pipeline.rs`) -- [x] llm-unify E2E: request → routing → normalisation → fallback (`crates/llm-unify-core/tests/e2e_routing_test.rs`) -- [x] P2P property tests: embedding, dispatch, trust monotonicity, hash stability, axiom ordering (`tests/neural_property_tests.rs`) -- [x] Security aspect tests: forgery, injection, escalation, axiom sanitisation, integrity (`tests/security_aspect_tests.rs`) -- [x] Concurrency tests: parallel factory, routing, trust, hashing, agent, axiom (`tests/concurrency_test.rs`) -- [x] Routing benchmarks: decision latency, axiom throughput, trust computation, factory instantiation, agentic planning, BLAKE3 (`benches/routing_benchmarks.rs`) - -### Still Missing - -- [ ] Agentic E2E: agent lifecycle (create → plan → execute → evaluate) for elegant-state, conative-gating -- [ ] LLM antidote adversarial property tests — NOTE: test_suite.py is semi-manual and Python (banned). Needs rewrite in Julia or Rust. -- [ ] Cross-satellite: echidna proof + llm-unify inference in combined workflow -- [ ] Fuzz harness: replace `tests/fuzz/placeholder.txt` with a real cargo-fuzz harness - -### P2P (Property-Based) Tests — Remaining -- [ ] LLM antidote: adversarial input property tests (blocked: Python banned, needs Julia rewrite) -- [ ] Prover backends: equivalence property tests across all 49 prover implementations (coverage increase) - -### Build & Execution -- [ ] `cargo test` for echidna Rust -- [ ] `zig build test` for FFI -- [ ] Python test runner for llm-antidote -- [ ] Shell test execution for integration tests - -### Benchmarks Needed -- [ ] Proof generation latency by complexity -- [ ] LLM routing decision time -- [ ] Agent planning throughput -- [ ] Cross-prover comparison benchmarks -- [ ] Neural overlay inference time - -### Self-Tests -- [ ] Prover health checks (each backend reachable) -- [ ] Model availability verification -- [ ] Proof chain integrity validation - -### CRITICAL GAPS - -| Subsystem | Source Files | Tests | Status | -|-----------|-------------|-------|--------| -| echidna | ~104 | ~8 | **7.7% — insufficient** | -| llm-antidote | unknown | 1 suite | Minimal | -| llm-unify | unknown | 1 e2e | Minimal | -| agentic (elegant-state) | unknown | 1 archived | **Effectively 0** | -| conative-gating | unknown | 0 | **Untested** | -| agentic-scm | unknown | 0 | **Untested** | - -## Priority - -**CRITICAL.** 337 source files across a neurosymbolic AI framework with ~14 test files total. echidna at 104 Rust files with 8 tests is 7.7% coverage. The agentic subsystem is completely untested. Benchmarks for echidna are a bright spot, but the overall test story is woeful for a framework that generates formal proofs — the proof engine itself needs far more rigorous testing. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 90% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 4e58ed8..67c6515 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Neural Foundations — Project Topology -# Neural Foundations — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ AI DEVELOPER │ │ (Research, Logic, Systems) │ @@ -51,11 +47,11 @@ │ Justfile / Rust .machine_readable/ │ │ Julia / ReScript 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE FOUNDATIONS @@ -77,25 +73,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% Foundational hub operational -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Philosophy ──────► Foundation Tech ───► Neural Hub ──────► Satellites │ │ │ │ ▼ ▼ ▼ ▼ CCCP Policy ──────► RSR Compliance ───► Scaffolding ───► Applications -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..b7421b4 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — neural-foundations — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |207 +|`+docs/+` files |2 +|`+docs/+` LoC |260 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +207 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index e49d549..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — neural-foundations — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 207 | -| `docs/` files | 2 | -| `docs/` LoC | 260 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 207 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..2b8d1c9 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — neural-foundations (Developer) + +=== What is neural-foundations? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index 248a384..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — neural-foundations (Developer) - -## What is neural-foundations? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..d71ad50 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — neural-foundations (User) + +=== What is neural-foundations? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 674a8dc..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — neural-foundations (User) - -## What is neural-foundations? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture