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..f8bbea6 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,74 @@ +== Changelog + +All notable changes to `+scripts+` 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: migrate bookmark scripts from Python to Julia +* feat: add stapeln.toml container definition +* feat: deploy UX Manifesto infrastructure +* feat: add CLADE.a2ml — clade taxonomy declaration +* feat(ci): enable Hypatia scanning +* feat: add hyperpolymath utility scripts + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (#47) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): Phase-2 fleet submission must not fail the security gate +(#46) +* fix(ci): move secret-scanner Cargo.toml gate from job-level if: to +step-level (#45) +* fix: replace deno -A with specific permission flags +* fix(scorecard): enforce granular permissions and add fuzzing +placeholder +* fix(ci): Resolve workflow-linter self-matching and metadata issues +* fix: correct email jonathan.jewell → j.d.a.jewell +* fix(license): SPDX AGPL-3.0 → PMPL-1.0-or-later in dotfiles +* fix: apply safety triangle fixes +(recipe-heredoc-to-install,recipe-shell-quote-vars) + +==== Changed + +* refactor: reboot-tracker.ts → .mjs (TS types stripped) (#42) +* refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) + +==== Documentation + +* docs: add EXPLAINME.adoc — prove-it file backing README claims +* docs: add CONTRIBUTING.md +* docs: add checkpoint files for state tracking + +==== CI + +* build(deps): bump dtolnay/rust-toolchain from +efa25f7f19611383d5b0ccf2d1c8914531636bf9 to +3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 (#49) +* build(deps): bump github/codeql-action from 4.32.6 to 4.36.0 (#50) +* build(deps): bump actions/github-script from 8.0.0 to 9.0.0 (#51) +* build(deps): bump trufflesecurity/trufflehog from 3.93.8 to 3.95.3 +(#52) +* build(deps): bump actions/upload-artifact from 4.6.2 to 7.0.1 (#53) + +=== 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 a295b00..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,67 +0,0 @@ - -# Changelog - -All notable changes to `scripts` 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: migrate bookmark scripts from Python to Julia -- feat: add stapeln.toml container definition -- feat: deploy UX Manifesto infrastructure -- feat: add CLADE.a2ml — clade taxonomy declaration -- feat(ci): enable Hypatia scanning -- feat: add hyperpolymath utility scripts - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (#47) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#46) -- fix(ci): move secret-scanner Cargo.toml gate from job-level if: to step-level (#45) -- fix: replace deno -A with specific permission flags -- fix(scorecard): enforce granular permissions and add fuzzing placeholder -- fix(ci): Resolve workflow-linter self-matching and metadata issues -- fix: correct email jonathan.jewell → j.d.a.jewell -- fix(license): SPDX AGPL-3.0 → PMPL-1.0-or-later in dotfiles -- fix: apply safety triangle fixes (recipe-heredoc-to-install,recipe-shell-quote-vars) - -### Changed - -- refactor: reboot-tracker.ts → .mjs (TS types stripped) (#42) -- refactor: migrate 6SCM → 6A2 (.scm → .a2ml format) - -### Documentation - -- docs: add EXPLAINME.adoc — prove-it file backing README claims -- docs: add CONTRIBUTING.md -- docs: add checkpoint files for state tracking - -### CI - -- build(deps): bump dtolnay/rust-toolchain from efa25f7f19611383d5b0ccf2d1c8914531636bf9 to 3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9 (#49) -- build(deps): bump github/codeql-action from 4.32.6 to 4.36.0 (#50) -- build(deps): bump actions/github-script from 8.0.0 to 9.0.0 (#51) -- build(deps): bump trufflesecurity/trufflehog from 3.93.8 to 3.95.3 (#52) -- build(deps): bump actions/upload-artifact from 4.6.2 to 7.0.1 (#53) - -## 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 bbe9219..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,30 +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..eee6255 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/scripts.git cd scripts + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create scripts-dev toolbox enter scripts-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +scripts/ ├── 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/scripts/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/scripts/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/scripts/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/scripts/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 717893a..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +0,0 @@ - -# Clone the repository -git clone https://github.com/hyperpolymath/scripts.git -cd scripts - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create scripts-dev -toolbox enter scripts-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -scripts/ -├── 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/scripts/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/scripts/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/scripts/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/scripts/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/PHASE3_STATUS.adoc b/PHASE3_STATUS.adoc new file mode 100644 index 0000000..7aa0575 --- /dev/null +++ b/PHASE3_STATUS.adoc @@ -0,0 +1,77 @@ +== 🚀 Phase 3: Language Hardening Status - FINAL REPORT + +*Date:* 2026-03-05 *Status:* ✅ COMPLETED (Primary Clusters) + +''''' + +=== 📊 Final Progress + +* *TypeScript to ReScript:* ██████████ 100% (Targeted Clusters) +* *Python to Julia:* ██████████ 100% (Targeted Clusters) +* *System Stability:* ✅ STABLE (Thermal Risk Eliminated) + +''''' + +=== ✅ Primary Clusters: 100% Ported & Verified + +==== 📦 Praxis Symbolic Engine (wordpress-tools/praxis) + +* *Core Infrastructure:* `+Types.res+`, `+PostgresClient.res+`, +`+ConfigLoader.res+`. +* *Business Logic:* 100% of Controllers ported (`+Audit+`, `+Baseline+`, +`+Execution+`, `+Symbol+`, `+Workflow+`). +* *Networking:* `+ApiServer.res+` (Elysia), `+ApiRoutes.res+`, +`+DashboardEvents.res+`, `+StreamHandler.res+` (WebSockets). +* *Cleanup:* All original `+.ts+` files removed. + +==== 📦 Svalinn Security Layer (ats2-tui/svalinn) + +* *Authentication:* `+AuthMiddleware.res+`, `+OAuth2.res+`, +`+AuthTypes.res+`, `+Jwt.res+`. +* *Policy Engine:* `+PolicyEvaluator.res+`, `+PolicyStore.res+`, +`+PolicyTypes.res+`. +* *Compose:* `+ComposeOrchestrator.res+`, `+ComposeTypes.res+`. +* *Integrations:* `+CerroTorre.res+`, `+PolyContainerMcp.res+`. +* *Verification:* `+AuthTest.res+`, `+PolicyEvaluatorTest.res+`. +* *Cleanup:* All original `+.ts+` files removed. + +==== 📦 Idaptik Game Engine (idaptik) + +* *Core Engine:* `+Engine.res+` (Application), `+Pixi.res+` (Central +Bindings), `+Audio.res+`, `+Navigation.res+`, `+Resize.res+`. +* *UI & Logic:* `+Main.res+` (Entry), `+Bouncer.res+`, +`+GetEngine.res+`, `+UserSettings.res+`. +* *Screens Cluster:* All 20+ screens reconstructed and verified +(`+Load+`, `+World+`, `+Intro+`, `+Map+`, `+Credits+`, etc.). +* *Popups Cluster:* All 15+ popups clean-rewritten to resolve syntax +corruption. +* *Cleanup:* All original `+.ts+` files removed from `+src/+`. Root +config standardized to `+vite.config.js+`. + +==== 📦 Echidna Formal Logic (echidna/HOL) + +* *Utilities:* `+gen.jl+`, `+decompile.jl+`, `+holwrap.jl+` ported from +Python. +* *Cleanup:* Original Python scripts removed. + +''''' + +=== 🛡️ Security Hardening + +* *Secrets Protection:* 100% of tracked .env files verified as ignored +or non-existent in critical repos. + +''''' + +=== 🛡️ Residual & Intentional Exceptions + +* *FFI Intentional:* `+protocol-squisher+` (Python), +`+bindings/python+`. +* *Build/Meta:* `+*.d.ts+` (Type defs), `+vite.config.ts+` (in +non-priority repos). + +''''' + +*THE "`THING`" IS FIXED.* All core logic fragments are now hardened, +type-safe, and standardized. _Gemini CLI (Forensic Engineering +Division)_ diff --git a/PHASE3_STATUS.md b/PHASE3_STATUS.md deleted file mode 100644 index af7d9ad..0000000 --- a/PHASE3_STATUS.md +++ /dev/null @@ -1,58 +0,0 @@ - -# 🚀 Phase 3: Language Hardening Status - FINAL REPORT -**Date:** 2026-03-05 -**Status:** ✅ COMPLETED (Primary Clusters) - ---- - -## 📊 Final Progress -- **TypeScript to ReScript:** ██████████ 100% (Targeted Clusters) -- **Python to Julia:** ██████████ 100% (Targeted Clusters) -- **System Stability:** ✅ STABLE (Thermal Risk Eliminated) - ---- - -## ✅ Primary Clusters: 100% Ported & Verified - -### 📦 Praxis Symbolic Engine (wordpress-tools/praxis) -- **Core Infrastructure:** `Types.res`, `PostgresClient.res`, `ConfigLoader.res`. -- **Business Logic:** 100% of Controllers ported (`Audit`, `Baseline`, `Execution`, `Symbol`, `Workflow`). -- **Networking:** `ApiServer.res` (Elysia), `ApiRoutes.res`, `DashboardEvents.res`, `StreamHandler.res` (WebSockets). -- **Cleanup:** All original `.ts` files removed. - -### 📦 Svalinn Security Layer (ats2-tui/svalinn) -- **Authentication:** `AuthMiddleware.res`, `OAuth2.res`, `AuthTypes.res`, `Jwt.res`. -- **Policy Engine:** `PolicyEvaluator.res`, `PolicyStore.res`, `PolicyTypes.res`. -- **Compose:** `ComposeOrchestrator.res`, `ComposeTypes.res`. -- **Integrations:** `CerroTorre.res`, `PolyContainerMcp.res`. -- **Verification:** `AuthTest.res`, `PolicyEvaluatorTest.res`. -- **Cleanup:** All original `.ts` files removed. - -### 📦 Idaptik Game Engine (idaptik) -- **Core Engine:** `Engine.res` (Application), `Pixi.res` (Central Bindings), `Audio.res`, `Navigation.res`, `Resize.res`. -- **UI & Logic:** `Main.res` (Entry), `Bouncer.res`, `GetEngine.res`, `UserSettings.res`. -- **Screens Cluster:** All 20+ screens reconstructed and verified (`Load`, `World`, `Intro`, `Map`, `Credits`, etc.). -- **Popups Cluster:** All 15+ popups clean-rewritten to resolve syntax corruption. -- **Cleanup:** All original `.ts` files removed from `src/`. Root config standardized to `vite.config.js`. - -### 📦 Echidna Formal Logic (echidna/HOL) -- **Utilities:** `gen.jl`, `decompile.jl`, `holwrap.jl` ported from Python. -- **Cleanup:** Original Python scripts removed. - ---- - -## 🛡️ Security Hardening -- **Secrets Protection:** 100% of tracked .env files verified as ignored or non-existent in critical repos. - ---- - -## 🛡️ Residual & Intentional Exceptions -- **FFI Intentional:** `protocol-squisher` (Python), `bindings/python`. -- **Build/Meta:** `*.d.ts` (Type defs), `vite.config.ts` (in non-priority repos). - ---- -**THE "THING" IS FIXED.** All core logic fragments are now hardened, type-safe, and standardized. -*Gemini CLI (Forensic Engineering Division)* diff --git a/REPO_SECURITY_REPORT.adoc b/REPO_SECURITY_REPORT.adoc new file mode 100644 index 0000000..75b5669 --- /dev/null +++ b/REPO_SECURITY_REPORT.adoc @@ -0,0 +1,77 @@ +== 🛡️ Repository Security & Policy Report + +*Date:* 2026-03-05 + +*Scope:* 157 Repositories in `+/var$REPOS_DIR/+` + +''''' + +=== 📊 Distribution of Issues by Category + +[width="100%",cols="<20%,<20%,<20%,<20%,<20%",options="header",] +|=== +|Category |Issue |Count |Severity |Risk +|*Runtime* |NPM Usage (`+package-lock.json+`) |13 |🔴 Critical |Thermal +Overload / Policy Violation + +|*Security* |Unprotected `+.env+` (Not in gitignore) |8 |🔴 Critical +|Credential Leakage + +|*Standards* |Dockerfile instead of Containerfile |24 |🟡 Medium +|Platform Standardization + +|*Automation* |Missing `+Justfile+` / RISC-V target |22 |🟡 Medium +|CI/CD Inefficiency + +|*Language* |TypeScript / Python Usage |3 |🟡 Medium |Language Policy +Violation +|=== + +''''' + +=== 🔗 Linked Issues (Critical Overlaps) + +These repositories exhibit "`linked`" failures where multiple policies +are violated simultaneously, creating complex technical debt. + +[arabic] +. *Thermal & Runtime Cluster (NPM + TypeScript):* +* `+idaptik+` +* `+panll+` +* `+patallm-gallery+` +* _Note: These are high-risk for thermal instability. Migration to Deno ++ ReScript is linked._ +. *Infrastructure Cluster (Docker + Missing Justfile):* +* `+boj-server+` +* `+cloudguard-server+` +* `+lcb-website+` +* _Note: These cannot be built for RISC-V without manual intervention in +both container and automation layers._ +. *Security Cluster (Unignored .env + NPM):* +* `+misinformation-defence-platform+` +* `+social-media-tools+` +* _Note: Secrets are at risk of being committed during high-overhead NPM +operations._ + +''''' + +=== 🛠️ Remediation Roadmap + +==== Phase 1: Immediate Safety (Automated) + +Run the `+AUTO_FIX=true+` Elixir script to: * [ ] Purge 59GB of cruft. * +[ ] Rename `+Dockerfile+` -> `+Containerfile+`. * [ ] Inject RISC-V +recipes into `+Justfile+`s. + +==== Phase 2: Runtime Stabilization (AI-Assisted) + +Address the NPM Cluster: * [ ] Migrate `+firebase-tools+` dependencies +to Deno. * [ ] Verify thermal stability under new runtime. + +==== Phase 3: Language & Secret Hardening (Manual/AI) + +* [ ] Translate TS -> ReScript. +* [ ] Audit all `+.env+` files and enforce `+.gitignore+` compliance. + +''''' + +_Report generated by Gemini CLI (Forensic Engineering Division)_ diff --git a/REPO_SECURITY_REPORT.md b/REPO_SECURITY_REPORT.md deleted file mode 100644 index c1043ee..0000000 --- a/REPO_SECURITY_REPORT.md +++ /dev/null @@ -1,64 +0,0 @@ - -# 🛡️ Repository Security & Policy Report -**Date:** 2026-03-05 -**Scope:** 157 Repositories in `/var$REPOS_DIR/` - ---- - -## 📊 Distribution of Issues by Category - -| Category | Issue | Count | Severity | Risk | -| :--- | :--- | :--- | :--- | :--- | -| **Runtime** | NPM Usage (`package-lock.json`) | 13 | 🔴 Critical | Thermal Overload / Policy Violation | -| **Security** | Unprotected `.env` (Not in gitignore) | 8 | 🔴 Critical | Credential Leakage | -| **Standards** | Dockerfile instead of Containerfile | 24 | 🟡 Medium | Platform Standardization | -| **Automation** | Missing `Justfile` / RISC-V target | 22 | 🟡 Medium | CI/CD Inefficiency | -| **Language** | TypeScript / Python Usage | 3 | 🟡 Medium | Language Policy Violation | - ---- - -## 🔗 Linked Issues (Critical Overlaps) - -These repositories exhibit "linked" failures where multiple policies are violated simultaneously, creating complex technical debt. - -1. **Thermal & Runtime Cluster (NPM + TypeScript):** - * `idaptik` - * `panll` - * `patallm-gallery` - * *Note: These are high-risk for thermal instability. Migration to Deno + ReScript is linked.* - -2. **Infrastructure Cluster (Docker + Missing Justfile):** - * `boj-server` - * `cloudguard-server` - * `lcb-website` - * *Note: These cannot be built for RISC-V without manual intervention in both container and automation layers.* - -3. **Security Cluster (Unignored .env + NPM):** - * `misinformation-defence-platform` - * `social-media-tools` - * *Note: Secrets are at risk of being committed during high-overhead NPM operations.* - ---- - -## 🛠️ Remediation Roadmap - -### Phase 1: Immediate Safety (Automated) -Run the `AUTO_FIX=true` Elixir script to: -* [ ] Purge 59GB of cruft. -* [ ] Rename `Dockerfile` -> `Containerfile`. -* [ ] Inject RISC-V recipes into `Justfile`s. - -### Phase 2: Runtime Stabilization (AI-Assisted) -Address the NPM Cluster: -* [ ] Migrate `firebase-tools` dependencies to Deno. -* [ ] Verify thermal stability under new runtime. - -### Phase 3: Language & Secret Hardening (Manual/AI) -* [ ] Translate TS -> ReScript. -* [ ] Audit all `.env` files and enforce `.gitignore` compliance. - ---- -*Report generated by Gemini CLI (Forensic Engineering Division)* 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 ab42fae..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,28 +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/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 87% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index ba52ae2..a72f417 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Hyperpolymath Scripts — Project Topology -# Hyperpolymath Scripts — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / ADMIN │ │ (CLI / Cron / Justfile) │ @@ -44,11 +37,11 @@ Copyright (c) Jonathan D.A. Jewell │ Justfile Automation .machine_readable/ │ │ Multi-Forge Hub 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── SYSTEM & REPO SCRIPTS @@ -69,25 +62,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~80% Tooling suite stable & active -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Justfile Target ───► Bash / Julia ─────► System Command ───► Result State │ │ │ │ ▼ ▼ ▼ ▼ Sync Script ───► Git Binary ───────► Remote Forge ──────► Mirrored -``` +.... -## 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..ba4b6e8 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — scripts — 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 |232 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|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 +232 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 a0599aa..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,56 +0,0 @@ - -# Tech-Debt Audit — scripts — 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 | 232 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| 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 232 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..7aa416b --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — scripts (Developer) + +=== What is scripts? + +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 13d74c7..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — scripts (Developer) - -## What is scripts? -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..05989cc --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — scripts (User) + +=== What is scripts? + +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 4aa5df7..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — scripts (User) - -## What is scripts? -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/skills/vscode-rescript-ext-migrator/SKILL.adoc b/skills/vscode-rescript-ext-migrator/SKILL.adoc new file mode 100644 index 0000000..f9af8c3 --- /dev/null +++ b/skills/vscode-rescript-ext-migrator/SKILL.adoc @@ -0,0 +1,52 @@ +== VSCode ReScript Migration Guide + +=== 🔷 Core Philosophy + +* *Minimize Dependencies*: Prefer lightweight external bindings over +massive binding libraries. +* *Deno-First*: For LSP runners, leverage Deno’s async capabilities via +`+%raw+` or clean externals. +* *Type Safety*: Fully model VSCode’s `+ExtensionContext+` and +`+Command+` registration. + +=== 📝 Common Bindings + +[source,rescript] +---- +module VsCode = { + type extensionContext = { + subscriptions: array unit>, + asAbsolutePath: string => string, + } + + module Window = { + @module("vscode") @scope("window") + external showInformationMessage: string => promise = "showInformationMessage" + + @module("vscode") @scope("window") + external showErrorMessage: string => promise = "showErrorMessage" + + @module("vscode") @scope("window") + external createTerminal: string => 'terminal = "createTerminal" + } + + module Commands = { + @module("vscode") @scope("commands") + external registerCommand: (string, unit => promise) => unit = "registerCommand" + } +} +---- + +=== 🚀 Workflow: Porting extension.ts + +[arabic] +. *Model the State*: Define the `+client+` and `+statusBar+` types as +options. +. *Externalize Modules*: Map `+path+` and `+vscode-languageclient+` to +ReScript externals. +. *Translate Lifecycle*: +* `+activate+` -> +`+let activate = (context: VsCode.extensionContext) => { ... }+` +* `+deactivate+` -> `+let deactivate = () => { ... }+` +. *Handle Async*: Use ReScript v12’s `+async/await+` for command +handlers. diff --git a/skills/vscode-rescript-ext-migrator/SKILL.md b/skills/vscode-rescript-ext-migrator/SKILL.md deleted file mode 100644 index f84c764..0000000 --- a/skills/vscode-rescript-ext-migrator/SKILL.md +++ /dev/null @@ -1,49 +0,0 @@ - ---- -name: vscode-rescript-ext-migrator -description: Procedural guidance and idiomatic bindings for migrating VSCode extensions from TypeScript to ReScript v12. Use when porting extension.ts files or implementing new VSCode features in ReScript. ---- -# VSCode ReScript Migration Guide - -## 🔷 Core Philosophy -- **Minimize Dependencies**: Prefer lightweight external bindings over massive binding libraries. -- **Deno-First**: For LSP runners, leverage Deno's async capabilities via `%raw` or clean externals. -- **Type Safety**: Fully model VSCode's `ExtensionContext` and `Command` registration. - -## 📝 Common Bindings - -```rescript -module VsCode = { - type extensionContext = { - subscriptions: array unit>, - asAbsolutePath: string => string, - } - - module Window = { - @module("vscode") @scope("window") - external showInformationMessage: string => promise = "showInformationMessage" - - @module("vscode") @scope("window") - external showErrorMessage: string => promise = "showErrorMessage" - - @module("vscode") @scope("window") - external createTerminal: string => 'terminal = "createTerminal" - } - - module Commands = { - @module("vscode") @scope("commands") - external registerCommand: (string, unit => promise) => unit = "registerCommand" - } -} -``` - -## 🚀 Workflow: Porting extension.ts -1. **Model the State**: Define the `client` and `statusBar` types as options. -2. **Externalize Modules**: Map `path` and `vscode-languageclient` to ReScript externals. -3. **Translate Lifecycle**: - - `activate` -> `let activate = (context: VsCode.extensionContext) => { ... }` - - `deactivate` -> `let deactivate = () => { ... }` -4. **Handle Async**: Use ReScript v12's `async/await` for command handlers.