diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..ca1c652 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 8109476..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] 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..5949bf0 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,9 @@ +== Contributing + +[arabic] +. Fork the repository +. Create a feature branch +. Ensure SPDX headers on all files +. Submit a pull request + +*Author:* Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 8725e71..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,9 +0,0 @@ - -# Contributing - -1. Fork the repository -2. Create a feature branch -3. Ensure SPDX headers on all files -4. Submit a pull request - -**Author:** Jonathan D.A. Jewell 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/READINESS.adoc b/READINESS.adoc new file mode 100644 index 0000000..7874193 --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,55 @@ +== nesy-solver Component Readiness Assessment + +*Standard:* +https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades[Component +Readiness Grades (CRG) v2.2] *Current Grade:* C *Assessed:* 2026-04-05 +*Assessor:* Jonathan D.A. Jewell + +''''' + +=== Summary + +[width="100%",cols="25%,8%,17%,50%",options="header",] +|=== +|Component |Grade |Release Stage |Evidence Summary +|Primary component |C |Alpha-stable |Dogfooded on own project; CI +passing +|=== + +*Overall:* Grade C — dogfooding confirmed, CI passing, deep annotation +in place. + +''''' + +=== Grade C Evidence + +* Deployed and dogfooded on the nesy-solver project itself +* CI passing (dogfood-gate, hypatia-scan, static-analysis-gate) +* TEST-NEEDS.md documents test matrix +* No home failures +* Deep code and folder annotation in place per CRG v2 requirements + +''''' + +=== Promotion Path to Grade B + +Grade B requires: *6+ diverse external targets tested, issues fed back*. + +Diversity means: different languages, different architectures, different +use cases. + +To reach B: 1. Deploy on at least 6 external projects that differ +meaningfully from each other 2. Confirm it works in each (or document +failures) 3. Feed back any issues found (GitHub issues or PRs) 4. Update +this file with the evidence + +''''' + +=== Concerns and Maintenance Notes + +_Document any known limitations, demotion risks, or maintenance concerns +here._ + +''''' + +=== Run `+just crg-badge+` to generate the shields.io badge for your README. diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index 2e2936e..0000000 --- a/READINESS.md +++ /dev/null @@ -1,53 +0,0 @@ - - - -# nesy-solver Component Readiness Assessment - -**Standard:** [Component Readiness Grades (CRG) v2.2](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) -**Current Grade:** C -**Assessed:** 2026-04-05 -**Assessor:** Jonathan D.A. Jewell - ---- - -## Summary - -| Component | Grade | Release Stage | Evidence Summary | -|---------------------|-------|---------------|-------------------------------------------| -| Primary component | C | Alpha-stable | Dogfooded on own project; CI passing | - -**Overall:** Grade C — dogfooding confirmed, CI passing, deep annotation in place. - ---- - -## Grade C Evidence - -- Deployed and dogfooded on the nesy-solver project itself -- CI passing (dogfood-gate, hypatia-scan, static-analysis-gate) -- TEST-NEEDS.md documents test matrix -- No home failures -- Deep code and folder annotation in place per CRG v2 requirements - ---- - -## Promotion Path to Grade B - -Grade B requires: **6+ diverse external targets tested, issues fed back**. - -Diversity means: different languages, different architectures, different use cases. - -To reach B: -1. Deploy on at least 6 external projects that differ meaningfully from each other -2. Confirm it works in each (or document failures) -3. Feed back any issues found (GitHub issues or PRs) -4. Update this file with the evidence - ---- - -## Concerns and Maintenance Notes - -*Document any known limitations, demotion risks, or maintenance concerns here.* - ---- - -## Run `just crg-badge` to generate the shields.io badge for your README. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..3e6a7a2 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,138 @@ +== TEST-NEEDS: nesy-solver + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State (Updated 2026-04-04) + +[width="100%",cols="40%,26%,34%",options="header",] +|=== +|Category |Count |Details +|*Source modules* |6 |3 Idris2 ABI (Foreign, Layout, Types), 2 Zig FFI +(build, main), 1 Zig integration test template + +|*Unit tests* |0 |None in main source (inline tests in main.zig) + +|*Integration tests* |1 |test/integration_test.zig (documented template, +1 placeholder test) + +|*E2E tests* |1 |tests/e2e/template_instantiation_test.sh (full +instantiation + validation) + +|*Workflow tests* |1 |tests/workflows/validate_workflows_test.sh (21 +workflows validated) + +|*Validation tests* |1 |scripts/validate-template.sh (8-phase +comprehensive validation) + +|*Benchmarks* |5 |benches/template_bench.sh (validation, Zig build, +tests, workflows, instantiation) + +|*Fuzz tests* |0 |README.adoc scaffold with harness instructions +|=== + +=== Completed Work (CRG C - Testing & Benchmarking) + +==== Template Validation Script ✅ + +* [x] `+scripts/validate-template.sh+` — 8-phase validation +** Phase 1: Core repository structure (root files, directories) +** Phase 2: Machine-readable metadata (.machine_readable/) +** Phase 3: GitHub Actions workflows (17 required + all present) +** Phase 4: Idris2 ABI and Zig FFI source files +** Phase 5: Placeholder token replacement (skipped in template) +** Phase 6: SPDX license headers (100% coverage, 6/6 files) +** Phase 7: Build system verification (zig build + idris2 syntax check) +** Phase 8: Documentation requirements (TOPOLOGY, ABI-FFI-README, etc) +* Status: *PASSING* (0 errors, 3 warnings about template placeholders) + +==== E2E Template Instantiation Test ✅ + +* [x] `+tests/e2e/template_instantiation_test.sh+` — full workflow +** Clones template to temp directory +** Replaces all \{\{PLACEHOLDER}} tokens with test values +** Validates resulting structure with scripts/validate-template.sh +** Verifies Zig build works after instantiation +** Checks no remaining placeholders +** Cleans up temp directory +* Status: *READY TO TEST* (can be verified by CI) + +==== Workflow Validation Test ✅ + +* [x] `+tests/workflows/validate_workflows_test.sh+` +** Validates all 21 workflows exist and have proper structure +** Checks SPDX headers, '`name`' field +** Verifies all 15 required workflows present +* Status: *PASSING* (0 errors, 15/15 required workflows found) + +==== Zig FFI Tests ✅ + +* [x] `+src/interface/ffi/test/integration_test.zig+` — template with +examples +** Converted from nesy_solver placeholders to "`template`" namespace +** Added comprehensive comments for how to instantiate +** Tests grouped by category (lifecycle, operations, strings, errors, +version, memory safety, threading) +** Compiles and passes placeholder test +* Status: *PASSING* (1 test: placeholder_test_implementation_required +passes) + +==== Benchmarks ✅ + +* [x] `+benches/template_bench.sh+` — 5 benchmark suites +** Validation script: ~5.8s average (3 runs) +** Zig build: ~19ms (clean build) +** Zig tests: ~20ms +** Workflow validation: ~117ms +** Template instantiation: ~427ms +* Formats: human, json, csv +* Status: *PASSING* (all benchmarks execute) + +==== Build System ✅ + +* [x] `+src/interface/ffi/build.zig+` — updated for Zig 0.15.2 +** Simplified to test-only configuration +** Supports both unit tests and integration tests +** Works with `+zig build+` without errors +* Status: *PASSING* (builds successfully) + +=== Test Results Summary + +.... +Validation Script: PASS (0 errors, 3 warnings) +Workflow Validation: PASS (21/21 workflows valid) +Integration Tests: PASS (1/1 placeholder test) +E2E Instantiation: READY (needs CI confirmation) +Benchmarks: PASS (5/5 benchmark suites) +Build System: PASS (zig build succeeds) +.... + +=== CRG C Compliance + +* *Coverage*: 6/6 test categories (unit, integration, E2E, workflow, +validation, benchmarks) +* *Documentation*: All test files have SPDX headers + inline +documentation +* *Author Attribution*: Jonathan D.A. Jewell +6759885+hyperpolymath@users.noreply.github.com +* *License*: MPL-2.0 on all new files +* *Automation*: All scripts executable + working + +=== FLAGGED ISSUES - ALL RESOLVED + +* [line-through]#*Template repo used by ALL new repos has 0 validation +tests*# → FIXED: 4 test suites + validation script +* [line-through]#*fuzz/placeholder.txt*# → FIXED: replaced with +README.adoc containing real harness instructions +* [line-through]#*No E2E tests for template instantiation*# → FIXED: +full E2E test suite +* [line-through]#*Zig FFI integration tests are placeholders*# → FIXED: +converted to documented template format + +=== Next Steps (Future Sessions) + +* [ ] Integrate test scripts into CI/CD workflows +* [ ] Generate test coverage reports +* [ ] Add more specialized benchmarks (memory, threading stress) +* [ ] Document test instantiation patterns for new repos + +=== Priority: P0 (COMPLETE) ✅ diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 533e89b..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,107 +0,0 @@ -# TEST-NEEDS: nesy-solver - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State (Updated 2026-04-04) - -| Category | Count | Details | -|----------|-------|---------| -| **Source modules** | 6 | 3 Idris2 ABI (Foreign, Layout, Types), 2 Zig FFI (build, main), 1 Zig integration test template | -| **Unit tests** | 0 | None in main source (inline tests in main.zig) | -| **Integration tests** | 1 | test/integration_test.zig (documented template, 1 placeholder test) | -| **E2E tests** | 1 | tests/e2e/template_instantiation_test.sh (full instantiation + validation) | -| **Workflow tests** | 1 | tests/workflows/validate_workflows_test.sh (21 workflows validated) | -| **Validation tests** | 1 | scripts/validate-template.sh (8-phase comprehensive validation) | -| **Benchmarks** | 5 | benches/template_bench.sh (validation, Zig build, tests, workflows, instantiation) | -| **Fuzz tests** | 0 | README.adoc scaffold with harness instructions | - -## Completed Work (CRG C - Testing & Benchmarking) - -### Template Validation Script ✅ -- [x] `scripts/validate-template.sh` — 8-phase validation - - Phase 1: Core repository structure (root files, directories) - - Phase 2: Machine-readable metadata (.machine_readable/) - - Phase 3: GitHub Actions workflows (17 required + all present) - - Phase 4: Idris2 ABI and Zig FFI source files - - Phase 5: Placeholder token replacement (skipped in template) - - Phase 6: SPDX license headers (100% coverage, 6/6 files) - - Phase 7: Build system verification (zig build + idris2 syntax check) - - Phase 8: Documentation requirements (TOPOLOGY, ABI-FFI-README, etc) -- Status: **PASSING** (0 errors, 3 warnings about template placeholders) - -### E2E Template Instantiation Test ✅ -- [x] `tests/e2e/template_instantiation_test.sh` — full workflow - - Clones template to temp directory - - Replaces all {{PLACEHOLDER}} tokens with test values - - Validates resulting structure with scripts/validate-template.sh - - Verifies Zig build works after instantiation - - Checks no remaining placeholders - - Cleans up temp directory -- Status: **READY TO TEST** (can be verified by CI) - -### Workflow Validation Test ✅ -- [x] `tests/workflows/validate_workflows_test.sh` - - Validates all 21 workflows exist and have proper structure - - Checks SPDX headers, 'name' field - - Verifies all 15 required workflows present -- Status: **PASSING** (0 errors, 15/15 required workflows found) - -### Zig FFI Tests ✅ -- [x] `src/interface/ffi/test/integration_test.zig` — template with examples - - Converted from nesy_solver placeholders to "template" namespace - - Added comprehensive comments for how to instantiate - - Tests grouped by category (lifecycle, operations, strings, errors, version, memory safety, threading) - - Compiles and passes placeholder test -- Status: **PASSING** (1 test: placeholder_test_implementation_required passes) - -### Benchmarks ✅ -- [x] `benches/template_bench.sh` — 5 benchmark suites - - Validation script: ~5.8s average (3 runs) - - Zig build: ~19ms (clean build) - - Zig tests: ~20ms - - Workflow validation: ~117ms - - Template instantiation: ~427ms -- Formats: human, json, csv -- Status: **PASSING** (all benchmarks execute) - -### Build System ✅ -- [x] `src/interface/ffi/build.zig` — updated for Zig 0.15.2 - - Simplified to test-only configuration - - Supports both unit tests and integration tests - - Works with `zig build` without errors -- Status: **PASSING** (builds successfully) - -## Test Results Summary - -``` -Validation Script: PASS (0 errors, 3 warnings) -Workflow Validation: PASS (21/21 workflows valid) -Integration Tests: PASS (1/1 placeholder test) -E2E Instantiation: READY (needs CI confirmation) -Benchmarks: PASS (5/5 benchmark suites) -Build System: PASS (zig build succeeds) -``` - -## CRG C Compliance - -- **Coverage**: 6/6 test categories (unit, integration, E2E, workflow, validation, benchmarks) -- **Documentation**: All test files have SPDX headers + inline documentation -- **Author Attribution**: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> -- **License**: MPL-2.0 on all new files -- **Automation**: All scripts executable + working - -## FLAGGED ISSUES - ALL RESOLVED - -- ~~**Template repo used by ALL new repos has 0 validation tests**~~ → FIXED: 4 test suites + validation script -- ~~**fuzz/placeholder.txt**~~ → FIXED: replaced with README.adoc containing real harness instructions -- ~~**No E2E tests for template instantiation**~~ → FIXED: full E2E test suite -- ~~**Zig FFI integration tests are placeholders**~~ → FIXED: converted to documented template format - -## Next Steps (Future Sessions) - -- [ ] Integrate test scripts into CI/CD workflows -- [ ] Generate test coverage reports -- [ ] Add more specialized benchmarks (memory, threading stress) -- [ ] Document test instantiation patterns for new repos - -## Priority: P0 (COMPLETE) ✅ diff --git a/TOPOLOGY.adoc b/TOPOLOGY.adoc new file mode 100644 index 0000000..a975f58 --- /dev/null +++ b/TOPOLOGY.adoc @@ -0,0 +1,36 @@ +== Architecture Topology + +=== System Overview + +RSR (Rhodium Standard Repository) template provides the canonical +scaffold for all hyperpolymath projects, with integrated CI/CD, +documentation, and service discovery patterns. + +=== Component Overview + +[width="100%",cols="37%,33%,30%",options="header",] +|=== +|Component |Language |Purpose +|dogfood-gate workflow |YAML |Quality checks (CRG, security, linting) +|eclexiaiser-validate job |YAML |Resource cost awareness scoring +|Groove discovery |JSON |Service endpoint registration +|=== + +=== Data Flow + +.... +[Code Push] → [GitHub Actions] → [hypatia scan] → [eclexiaiser validate] → [Results] +.... + +=== Integration Points + +* *Upstream*: Hypatia (neurosymbolic CI/CD), eclexiaiser (resource +scoring) +* *Downstream*: All RSR-based repositories (500+ instances) + +=== Deployment + +* Container: Stapeln Six ecosystem +* CI/CD: GitHub Actions → Hypatia scan → eclexiaiser-validate (6 +scorecard dimensions) → Mirror +* Service Discovery: Groove protocol (.well-known/groove/manifest.json) diff --git a/TOPOLOGY.md b/TOPOLOGY.md deleted file mode 100644 index 61cdc22..0000000 --- a/TOPOLOGY.md +++ /dev/null @@ -1,33 +0,0 @@ - - - -# Architecture Topology - -## System Overview - -RSR (Rhodium Standard Repository) template provides the canonical scaffold for all hyperpolymath projects, with integrated CI/CD, documentation, and service discovery patterns. - -## Component Overview - -| Component | Language | Purpose | -|-----------|----------|---------| -| dogfood-gate workflow | YAML | Quality checks (CRG, security, linting) | -| eclexiaiser-validate job | YAML | Resource cost awareness scoring | -| Groove discovery | JSON | Service endpoint registration | - -## Data Flow - -``` -[Code Push] → [GitHub Actions] → [hypatia scan] → [eclexiaiser validate] → [Results] -``` - -## Integration Points - -- **Upstream**: Hypatia (neurosymbolic CI/CD), eclexiaiser (resource scoring) -- **Downstream**: All RSR-based repositories (500+ instances) - -## Deployment - -- Container: Stapeln Six ecosystem -- CI/CD: GitHub Actions → Hypatia scan → eclexiaiser-validate (6 scorecard dimensions) → Mirror -- Service Discovery: Groove protocol (.well-known/groove/manifest.json) diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..0823fcd --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — nesy-solver (Developer) + +=== What is nesy-solver? + +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 a67c992..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — nesy-solver (Developer) - -## What is nesy-solver? -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..9ac14c4 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — nesy-solver (User) + +=== What is nesy-solver? + +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 e728fb6..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — nesy-solver (User) - -## What is nesy-solver? -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