diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 000000000..1c0a7a697 --- /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 607e3d8cd..000000000 --- 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/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 000000000..b42aeb937 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,62 @@ +== Contributing to julia-ecosystem + +Thanks for your interest. This repository follows the Hyperpolymath +estate standards defined in +https://github.com/hyperpolymath/standards[hyperpolymath/standards]. + +=== Licence + +This project is licensed under *MPL-2.0*. By contributing you agree that +your contributions are licensed under the same terms. Every source file +carries an `+SPDX-License-Identifier+` header; keep it when editing, and +add one to any new file. + +=== Development environment + +Use the toolchain declared by this repository (just). + +=== Build and test + +This repo uses https://just.systems[`+just+`] (the estate uses +Justfiles, never Makefiles). Recipes available here: + +[source,sh] +---- +just # list recipes +just doctor # environment diagnostics +---- + +=== Machine-readable artefacts + +This repo carries `+.machine_readable/+` A2ML files (`+STATE.a2ml+`, +`+META.a2ml+`, `+ECOSYSTEM.a2ml+`, `+AGENTIC.a2ml+`, `+NEUROSYM.a2ml+`, +`+PLAYBOOK.a2ml+`). If your change alters project state, architecture, +or operational steps, update the corresponding file in the same PR — CI +validates them. + +=== Language policy + +The estate restricts which languages may be used. In particular Python, +Go, TypeScript, ReScript, V-lang, Java/Kotlin, Swift and Makefiles are +*not* accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, Gleam, +Elixir, Haskell, Idris2, Agda, Julia and OCaml are. CI enforces this, so +check the policy in `+hyperpolymath/standards+` before introducing a new +language. + +=== Documentation format + +Docs are AsciiDoc (`+.adoc+`) by default, including `+README.adoc+`. The +GitHub-required community-health files stay Markdown: `+SECURITY.md+`, +`+CONTRIBUTING.md+`, `+CODE_OF_CONDUCT.md+`, `+CHANGELOG.md+`. Do not +add a `+.md+` duplicate of a doc that already exists as `+.adoc+`. + +=== Pull requests + +[arabic] +. Branch from `+main+` — do not push to `+main+` directly; branch +protection requires review and passing checks. +. Keep the change focused, and explain _why_ in the PR body. +. Make sure governance CI is green. It checks documentation presence, +packaging policy, secrets, licence consistency and workflow security. +. Security issues: follow `+SECURITY.md+` — report privately, never in a +public issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index daed1e105..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,61 +0,0 @@ - - - -# Contributing to julia-ecosystem - -Thanks for your interest. This repository follows the Hyperpolymath estate -standards defined in [hyperpolymath/standards](https://github.com/hyperpolymath/standards). - -## Licence - -This project is licensed under **MPL-2.0**. By contributing you agree that -your contributions are licensed under the same terms. Every source file -carries an `SPDX-License-Identifier` header; keep it when editing, and add -one to any new file. - -## Development environment - -Use the toolchain declared by this repository (just). - -## Build and test - -This repo uses [`just`](https://just.systems) (the estate uses Justfiles, -never Makefiles). Recipes available here: - -```sh -just # list recipes -just doctor # environment diagnostics -``` - -## Machine-readable artefacts - -This repo carries `.machine_readable/` A2ML files (`STATE.a2ml`, -`META.a2ml`, `ECOSYSTEM.a2ml`, `AGENTIC.a2ml`, `NEUROSYM.a2ml`, -`PLAYBOOK.a2ml`). If your change alters project state, architecture, or -operational steps, update the corresponding file in the same PR — CI -validates them. - -## Language policy - -The estate restricts which languages may be used. In particular Python, Go, -TypeScript, ReScript, V-lang, Java/Kotlin, Swift and Makefiles are **not** -accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, Gleam, Elixir, -Haskell, Idris2, Agda, Julia and OCaml are. CI enforces this, so check the -policy in `hyperpolymath/standards` before introducing a new language. - -## Documentation format - -Docs are AsciiDoc (`.adoc`) by default, including `README.adoc`. The -GitHub-required community-health files stay Markdown: `SECURITY.md`, -`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `CHANGELOG.md`. Do not add a `.md` -duplicate of a doc that already exists as `.adoc`. - -## Pull requests - -1. Branch from `main` — do not push to `main` directly; branch protection - requires review and passing checks. -2. Keep the change focused, and explain *why* in the PR body. -3. Make sure governance CI is green. It checks documentation presence, - packaging policy, secrets, licence consistency and workflow security. -4. Security issues: follow `SECURITY.md` — report privately, never in a - public issue. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d3b..9b836fb28 100644 --- a/GOVERNANCE.adoc +++ b/GOVERNANCE.adoc @@ -1,162 +1,60 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell -= Governance Model -:toc: preamble +== Governance -This document describes the governance model for this repository. +=== Overview -== Overview +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. -This repository follows a **Sole Maintainer Governance Model**: +=== Roles and Responsibilities -* Single maintainer (@hyperpolymath) has full authority over the project -* All contributions are welcome and reviewed by the maintainer -* Decisions are made transparently through GitHub issues and discussions -* The project adheres to the hyperpolymath estate policies where applicable +==== Maintainers -== Core Principles +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 -[cols="1,2"] -|=== -| Principle | Description +==== Contributors -| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input +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 -| **Meritocracy** | Contributions are judged on technical merit, not contributor identity +=== Decision Making -| **Transparency** | All significant decisions are documented publicly +==== Minor Changes -| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates -| **Open Contribution** | Anyone can contribute via fork and pull request +==== Major Changes -|=== +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers -== Roles and Permissions +==== Breaking Changes -[cols="1,2,2"] -|=== -| Role | Permissions | Assignment +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide -| **Maintainer** | Write access, merge rights, admin | @hyperpolymath -| **Contributors** | Read access, fork, submit PRs | All GitHub users -| **Users** | Use the software, report issues | All GitHub users +=== Code of Conduct -|=== +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. -== Decision Making Framework +=== Communication -=== Routine Decisions +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions -* Bug fixes -* Documentation improvements -* Minor feature additions -* Dependency updates +=== Licensing -**Process**: Maintainer reviews and merges PRs that meet quality standards. +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. -=== Significant Changes +''''' -* New major features -* API changes -* Architecture modifications -* Breaking changes - -**Process**: -. Open issue describing the change -. Discuss with community (minimum 72 hours) -. Maintainer makes final decision -. Document rationale in issue/PR - -=== Structural Decisions - -* Repository purpose/renaming -* License changes -* Ownership transfer -* Deprecation/archival - -**Process**: -. Extended discussion (minimum 1 week) -. Maintainer makes final decision -. Document in CHANGELOG and governance docs - -== Contribution Lifecycle - -[cols="1,2"] -|=== -| Stage | Process - -| **Ideation** | Open issue, discuss feasibility - -| **Development** | Fork, implement, test thoroughly - -| **Review** | Submit PR, maintainer reviews within 7 days - -| **Merge** | Maintainer merges or requests changes - -| **Release** | Maintainer publishes according to project conventions - -|=== - -== Conflict Resolution - -In case of disagreements: - -. Discuss in the relevant GitHub issue or PR -. Provide technical justification for positions -. Maintainer mediates and makes final decision -. Decision is documented and can be revisited later - -== Project Policies - -This repository adheres to hyperpolymath estate-wide policies: - -* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) -* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md -* **Security**: Follows hyperpolymath SECURITY.md -* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions - -== Repository-Specific Conventions - -[cols="1,2"] -|=== -| Convention | Description - -| **Signing** | All commits must be signed (SSH or GPG) - -| **SPDX Headers** | All source files must have SPDX license identifiers - -| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root - -| **Machine Readable** | META.a2ml in .machine_readable/6a2/ - -| **CI/CD** | GitHub Actions workflows in .github/workflows/ - -|=== - -== Governance Evolution - -As the project grows, this governance model may evolve: - -* **Adding Co-Maintainers**: When contribution volume warrants it -* **Forming a Team**: For complex multi-maintainer projects -* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) - -Changes to this document require the same process as Significant Changes above. - -== See Also - -* link:MAINTAINERS.adoc[Maintainers] -* link:CODE_OF_CONDUCT.md[Code of Conduct] -* link:CONTRIBUTING.adoc[Contributing Guide] -* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] -* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] - -== Changelog - -[cols="1,1,1"] -|=== -| Date | Change | By - -| 2026-06-07 | Initial governance model established | @hyperpolymath -|=== +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c75..000000000 --- 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 000000000..7d5132fbb --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,12 @@ +== PROOF-NEEDS.md + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. + +When this project needs formal ABI verification, create domain-specific +Idris2 proofs following the pattern in repos like `+typed-wasm+`, +`+proven+`, `+echidna+`, or `+boj-server+`. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 895032028..000000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,10 +0,0 @@ -# PROOF-NEEDS.md - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. - -When this project needs formal ABI verification, create domain-specific Idris2 proofs -following the pattern in repos like `typed-wasm`, `proven`, `echidna`, or `boj-server`. diff --git a/README.adoc b/README.adoc new file mode 100644 index 000000000..05487929d --- /dev/null +++ b/README.adoc @@ -0,0 +1,106 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/julia-ecosystem[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] +https://www.mozilla.org/MPL/2.0/[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +MPL-2.0]] image:Julia + +*A unified framework for post-disciplinary research, organizing, and +verified computing.* + +[[toc]] + +== Overview + +This is the central monorepo for the *Hyperpolymath Julia Ecosystem*. It +consolidates 20+ specialized libraries into a single, cohesive research +and development environment. From formal logic and cryptography to +historical dynamics and labor organizing, this ecosystem provides the +"`Post-Disciplinary Glue`" to tackle complex global challenges. + +== Repository Map + +=== 🧠 Logic & Verification + +* Axiom: Provably correct machine learning and formal verification. +* SMTLib: Julia interface for SMT solvers (Z3, CVC5). +* PolyglotFormalisms: Formally verified cross-language common library. +* ZeroProb: Reasoning about measure-zero events and black swans. + +=== 🛡️ Security & Forensics + +* ProvenCrypto: Formally verified PQC and cryptographic protocols. +* InvestigativeJournalism: High-intelligence forensics and secure +evidence lockers. + +=== 🏛️ History & Social Science + +* Cliodynamics: Mathematical modeling of historical dynamics (DST). +* Cliometrics: Quantitative economic history and convergence analysis. +* Axiology: Formal value theory and ethical alignment for ML. +* ViableSystems: Organizational cybernetics (VSM) and Soft Systems +Methodology (SSM). + +=== ✊ Organizing & Action + +* TradeUnionism: Data-driven labor organizing and spatial power mapping. +* PRComms: High-integrity strategic communications and crisis +management. +* Exnovation: Systematic phase-out of legacy practices and structures. +* BowtieRisk: Structured hazard analysis and barrier modeling. + +=== 🎨 Mathematics & Play + +* JuliaForChildren: Joyful visual coding for children with Minecraft/KSP +interop. +* KnotTheory: Computational knot theory and invariants. +* Skein: Persistence layer for knot-theoretic data. +* HackenbushGames: Combinatorial game theory toolkit. +* Cladistics: Phylogenetic analysis and evolutionary relationships. + +=== ⚙️ Orchestration & Meta + +* PostDisciplinary: The universal graph linking all disciplinary +modules. +* JuliaPackageSpitter: Automated scaffolding for new ecosystem +libraries. +* MacroPower: Low-code automation and workflow engine. +* ShellIntegration: Unified shell interface (PowerShell & Valence). +* MinixSDK: Research foundation for Julia-to-MINIX 3 microkernel +development. +* SoftwareSovereign: Universal software policy engine and license-aware +discovery. + +=== 🔌 The Metal Layer (Subdivided LowLevel) + +* LowLevel: The meta-orchestrator for high-integrity hardware control. +* SiliconCore: Multi-arch Assembly, CPUID, and manual memory arenas. +* AcceleratorGate: GPU, NPU, and TPU driver dispatch. +* QuantumCircuit: QPU abstraction and reversible computing. +* HardwareResilience: Self-healing, diagnostics, and fault-recovery. +* FirmwareAudit: BIOS, UEFI, ACPI, and RAID telemetry. + +== Development in the Monorepo + +To work on a specific package within this repo: + +[source,bash] +---- +# Example: Testing PRComms.jl +cd packages/PRComms.jl +julia --project=. -e 'using Pkg; Pkg.test()' +---- + +=== Registration + +When registering these packages, use the `+subdir+` argument: +`+@JuliaRegistrator+` `+register+` +`+subdirectory=packages/PackageName.jl+` + +== License + +All packages in this ecosystem are licensed under the +*Palimpsest-MPL-1.0 License* (MPL-2.0). See the LICENSE file in the root +and in each package subdirectory for details. + +''''' + +_Synthesis is the ultimate discipline._ diff --git a/README.md b/README.md deleted file mode 100644 index 8da29f321..000000000 --- a/README.md +++ /dev/null @@ -1,165 +0,0 @@ - - -[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/julia-ecosystem) -[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://www.mozilla.org/MPL/2.0/) - -image:Julia - -**A unified framework for post-disciplinary research, organizing, and -verified computing.** - -
- -
- -# Overview - -This is the central monorepo for the **Hyperpolymath Julia Ecosystem**. -It consolidates 20+ specialized libraries into a single, cohesive -research and development environment. From formal logic and cryptography -to historical dynamics and labor organizing, this ecosystem provides the -"Post-Disciplinary Glue" to tackle complex global challenges. - -# Repository Map - -## 🧠 Logic & Verification - -- Axiom: Provably correct - machine learning and formal verification. - -- SMTLib: Julia interface - for SMT solvers (Z3, CVC5). - -- PolyglotFormalisms: Formally verified cross-language - common library. - -- ZeroProb: Reasoning - about measure-zero events and black swans. - -## 🛡️ Security & Forensics - -- ProvenCrypto: - Formally verified PQC and cryptographic protocols. - -- InvestigativeJournalism: High-intelligence forensics - and secure evidence lockers. - -## 🏛️ History & Social Science - -- Cliodynamics: - Mathematical modeling of historical dynamics (DST). - -- Cliometrics: - Quantitative economic history and convergence analysis. - -- Axiology: Formal value - theory and ethical alignment for ML. - -- ViableSystems: - Organizational cybernetics (VSM) and Soft Systems Methodology (SSM). - -## ✊ Organizing & Action - -- TradeUnionism: - Data-driven labor organizing and spatial power mapping. - -- PRComms: High-integrity - strategic communications and crisis management. - -- Exnovation: Systematic - phase-out of legacy practices and structures. - -- BowtieRisk: Structured - hazard analysis and barrier modeling. - -## 🎨 Mathematics & Play - -- JuliaForChildren: Joyful - visual coding for children with Minecraft/KSP interop. - -- KnotTheory: - Computational knot theory and invariants. - -- Skein: Persistence layer - for knot-theoretic data. - -- HackenbushGames: - Combinatorial game theory toolkit. - -- Cladistics: - Phylogenetic analysis and evolutionary relationships. - -## ⚙️ Orchestration & Meta - -- PostDisciplinary: - The universal graph linking all disciplinary modules. - -- JuliaPackageSpitter: Automated scaffolding for new - ecosystem libraries. - -- MacroPower: Low-code - automation and workflow engine. - -- ShellIntegration: - Unified shell interface (PowerShell & Valence). - -- MinixSDK: Research - foundation for Julia-to-MINIX 3 microkernel development. - -- SoftwareSovereign: - Universal software policy engine and license-aware discovery. - -## 🔌 The Metal Layer (Subdivided LowLevel) - -- LowLevel: The - meta-orchestrator for high-integrity hardware control. - -- SiliconCore: - Multi-arch Assembly, CPUID, and manual memory arenas. - -- AcceleratorGate: - GPU, NPU, and TPU driver dispatch. - -- QuantumCircuit: - QPU abstraction and reversible computing. - -- HardwareResilience: Self-healing, diagnostics, and - fault-recovery. - -- FirmwareAudit: - BIOS, UEFI, ACPI, and RAID telemetry. - -# Development in the Monorepo - -To work on a specific package within this repo: - -```bash -# Example: Testing PRComms.jl -cd packages/PRComms.jl -julia --project=. -e 'using Pkg; Pkg.test()' -``` - -## Registration - -When registering these packages, use the `subdir` argument: -`@JuliaRegistrator` `register` `subdirectory=packages/PackageName.jl` - -# License - -All packages in this ecosystem are licensed under the -**Palimpsest-MPL-1.0 License** (MPL-2.0). See the LICENSE file in the -root and in each package subdirectory for details. - ------------------------------------------------------------------------- - -*Synthesis is the ultimate discipline.* diff --git a/REGISTRY-SUBMISSIONS.adoc b/REGISTRY-SUBMISSIONS.adoc new file mode 100644 index 000000000..e23fedd92 --- /dev/null +++ b/REGISTRY-SUBMISSIONS.adoc @@ -0,0 +1,434 @@ +== Julia General Registry Submissions + +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== + +== For each package, you’ll need: + +== - repo: the Git URL (HTTPS for registry) + +== - subdir: path from repo root to the package directory + +== - name, uuid, version: from Project.toml + +== - description: for the registry listing + +== + +== Common fields for all packages: + +== repo = "`https://github.com/hyperpolymath/julia-ecosystem`" + +== subdir = "`packages/`" + +=== Registration command template (via LocalRegistry or Registrator): + +=== + +=== using LocalRegistry + +=== register( + +=== "`packages/`", + +=== registry = "`path/to/General`", + +=== repo = "`https://github.com/hyperpolymath/julia-ecosystem`", + +=== subdir = "`packages/`" + +=== ) + +=== + +=== Or via JuliaRegistrator bot comment on a GitHub commit: + +=== @JuliaRegistrator register subdir=packages/ + +''''' + +=== 1. AcceleratorGate.jl + +* *name*: AcceleratorGate +* *uuid*: 59f742c7-270d-4a76-95d4-a853ae16cc71 +* *version*: 0.1.0 +* *subdir*: packages/AcceleratorGate.jl +* *description*: Shared coprocessor dispatch infrastructure for Julia +packages. Provides a unified backend type hierarchy (GPU, TPU, NPU, +FPGA, QPU, DSP, VPU, PPU, Math, Crypto) with automatic detection, +platform-aware selection, resource-aware memory tracking, and +self-healing fallback hooks. + +=== 2. Axiology.jl + +* *name*: Axiology +* *uuid*: 868b87ec-ec5d-47a0-ab5f-c8a8ecbd97bd +* *version*: 0.1.0 +* *subdir*: packages/Axiology.jl +* *description*: Value theory integration for machine learning models. +Provides frameworks for embedding ethical constraints, preference +orderings, and axiological assessments into model training and +evaluation pipelines. + +=== 3. Axiom.jl + +* *name*: Axiom +* *uuid*: bbd403f8-dcc5-405a-84eb-8de9d358675c +* *version*: 0.2.0 +* *subdir*: packages/Axiom.jl +* *description*: Provably correct machine learning framework. Bridges +formal verification and ML with property-based testing, SMT-backed +invariant checking, and coprocessor-accelerated inference across GPU, +TPU, NPU, FPGA, QPU, and other backends via AcceleratorGate. + +=== 4. BowtieRisk.jl + +* *name*: BowtieRisk +* *uuid*: f4857c2c-646e-44f8-8901-46c9ace85fa6 +* *version*: 0.1.0 +* *subdir*: packages/BowtieRisk.jl +* *description*: Bow-tie risk analysis with barrier assessment and Monte +Carlo simulation. Models hazards, threats, top events, consequences, and +barriers (preventive/mitigative) with support for escalation factors, +barrier degradation, and dependency handling. + +=== 5. Causals.jl + +* *name*: Causals +* *uuid*: c4a8b6d2-f9e3-4c1a-b8d7-9f2e3c4d5e6f +* *version*: 0.1.0 +* *subdir*: packages/Causals.jl +* *description*: Causal inference and Applied Information Economics +(AIE). Implements do-calculus, Bayesian network inference, propensity +score estimation, and Hubbard’s Value of Information framework with +coprocessor-accelerated backends for large-scale causal discovery. + +=== 6. Cladistics.jl + +* *name*: Cladistics +* *uuid*: e3663be0-4771-44aa-b6d0-43b3a6d82e58 +* *version*: 0.1.0 +* *subdir*: packages/Cladistics.jl +* *description*: Phylogenetic analysis and cladistics. Implements +parsimony-based tree reconstruction, character matrix operations, +maximum parsimony scoring, tree rearrangement (SPR/TBR/NNI), consensus +methods, and GPU-accelerated likelihood computation for large datasets. + +=== 7. Cliodynamics.jl + +* *name*: Cliodynamics +* *uuid*: 8d2f3e70-4c6b-5e9c-a3d1-2f8e9c0b1d2e +* *version*: 1.0.0 +* *subdir*: packages/Cliodynamics.jl +* *description*: Mathematical modeling and statistical analysis of +historical dynamics. Implements Peter Turchin’s cliodynamics research +program: demographic-structural theory, secular cycles, elite +overproduction, Political Stress Indicator (PSI), and state breakdown +prediction using differential equation models. + +=== 8. Cliometrics.jl + +* *name*: Cliometrics +* *uuid*: 6c8e9c60-3b5a-4d8b-9f2a-1e7f8a9b0c1d +* *version*: 0.1.0 +* *subdir*: packages/Cliometrics.jl +* *description*: Quantitative economic history analysis. Applies +economic theory and econometric methods to historical data: GDP +reconstruction, price series deflation, demographic transition modeling, +trade flow analysis, and institutional quality metrics with +coprocessor-accelerated computation. + +=== 9. Exnovation.jl + +* *name*: Exnovation +* *uuid*: eb535ea2-a284-4d5f-a499-9e884733dc08 +* *version*: 0.1.0 +* *subdir*: packages/Exnovation.jl +* *description*: Systematic phase-out and discontinuation planning for +legacy practices, products, and technologies. Provides scoring matrices, +impact assessment, stakeholder analysis, transition pathway generation, +and monitoring dashboards for managed exnovation processes. + +=== 10. FirmwareAudit.jl + +* *name*: FirmwareAudit +* *uuid*: e6a7b8c9-d0e1-4f2a-ab3c-4d5e6f7a8b9c +* *version*: 0.1.0 +* *subdir*: packages/FirmwareAudit.jl +* *description*: Firmware image auditing and vulnerability scanning. +Performs entropy analysis, string extraction, header format +identification (ELF, PE, Mach-O, U-Boot, Intel HEX), hash verification, +and known-CVE matching against an embedded vendor vulnerability +database. + +=== 11. HackenbushGames.jl + +* *name*: HackenbushGames +* *uuid*: 01ec8bc2-77c0-4797-a5fe-db76a6b99454 +* *version*: 0.1.0 +* *subdir*: packages/HackenbushGames.jl +* *description*: Combinatorial game theory implementation for Hackenbush +games. Supports Red-Blue, Green, and multi-color Hackenbush with surreal +number evaluation, game addition, canonical form reduction, and +GPU/coprocessor-accelerated game tree search. + +=== 12. HardwareResilience.jl + +* *name*: HardwareResilience +* *uuid*: d5f6a7b8-c9d0-4e1f-9a2b-3c4d5e6f7a8b +* *version*: 0.1.0 +* *subdir*: packages/HardwareResilience.jl +* *description*: Hardware resilience detection and monitoring for Linux +systems. Detects ECC memory, RAID arrays, thermal zones, watchdog +timers, and redundant power supplies, producing a comprehensive +resilience assessment with a supervised execution guardian for +safety-critical workloads. + +=== 13. Hyperpolymath.jl + +* *name*: Hyperpolymath +* *uuid*: a0b1c2d3-e4f5-6a7b-8c9d-0e1f2a3b4c5d +* *version*: 0.1.0 +* *subdir*: packages/Hyperpolymath.jl +* *description*: Meta-package aggregating the hyperpolymath Julia +ecosystem. Imports and re-exports all domain packages spanning +logic/verification, security/forensics, history/social science, +organising/action, mathematics/play, orchestration/meta, and the metal +layer. + +=== 14. InvestigativeJournalism.jl + +* *name*: InvestigativeJournalism +* *uuid*: 379a7c0a-3675-4b32-b948-cb4760c6e442 +* *version*: 0.1.0 +* *subdir*: packages/InvestigativeJournalism.jl +* *description*: Digital forensics and investigative analysis toolkit. +Provides evidence chain management, claim tracking, source credibility +scoring, timeline reconstruction, network analysis of actors, and +structured output for investigative reporting workflows. + +=== 15. JuliaForChildren (JuliaForChildren.jl) + +* *name*: JuliaForChildren +* *uuid*: c1c96f90-3ae4-433d-aa60-06e66792fdf1 +* *version*: 0.1.0 +* *subdir*: packages/JuliaForChildren.jl +* *description*: Educational Julia programming toolkit for children aged +7-14. Provides simplified interfaces for turtle graphics, Minecraft +modding, KSP mission planning, game development, robotics, and +collaborative coding with accessibility-first design and screen reader +support. + +=== 16. JuliaPackageSpitter (JuliaPackage-Reuse-Audit.jl) + +* *name*: JuliaPackageSpitter +* *uuid*: 772df90b-d426-497b-8682-0a765d4f8c0b +* *version*: 0.1.0 +* *subdir*: packages/JuliaPackage-Reuse-Audit.jl +* *description*: Automated Julia package scaffolding and reuse auditing. +Generates compliant package structures from configurable PackageSpec +templates and audits existing packages for code reuse opportunities +across the ecosystem. + +=== 17. KnotTheory.jl + +* *name*: KnotTheory +* *uuid*: 215268c9-7579-426e-8b7c-a3dc27acd339 +* *version*: 0.1.0 +* *subdir*: packages/KnotTheory.jl +* *description*: Mathematical knot theory library implementing planar +diagram representations, polynomial invariants (Jones, Alexander, +HOMFLY-PT, Kauffman bracket), Reidemeister move simplification, braid +word conversion, and Seifert circle computation with a built-in knot +table. + +=== 18. Lithoglyph.jl + +* *name*: Lithoglyph +* *uuid*: f1e2d3c4-b5a6-4b7c-8d9e-0f1a2b3c4d5e +* *version*: 0.1.0 +* *subdir*: packages/Lithoglyph.jl +* *description*: Julia bindings for the LithoGlyph database engine. +Provides a client for registering and searching glyphs (symbolic data +with tags and provenance) in the federated LithoGlyph store, plus an FFI +bridge to the core Zig/Forth normaliser. + +=== 19. LowLevel.jl + +* *name*: LowLevel +* *uuid*: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d +* *version*: 0.1.0 +* *subdir*: packages/LowLevel.jl +* *description*: Low-level system introspection and hardware detection +for Julia. Provides CPU architecture detection (x86_64, ARM, RISC-V, +MIPS, PowerPC), SIMD capability probing, cache hierarchy analysis, and +platform-specific feature flags. + +=== 20. MacroPower.jl + +* *name*: MacroPower +* *uuid*: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e +* *version*: 0.1.0 +* *subdir*: packages/MacroPower.jl +* *description*: Macroeconomic power analysis and modelling through +trigger-action automation workflows. Define workflows with conditional +triggers and executable actions using the @workflow macro, then run them +with run_workflow for policy simulation and scenario analysis. + +=== 21. MinixSDK.jl + +* *name*: MinixSDK +* *uuid*: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a +* *version*: 0.1.0 +* *subdir*: packages/MinixSDK.jl +* *description*: Research SDK for targeting MINIX 3 from Julia. Provides +cross-compilation scaffolding, microkernel service generation, IPC +message passing primitives, and driver skeleton templates for exploring +MINIX’s message-based architecture from Julia. + +=== 22. PolyglotFormalisms.jl + +* *name*: PolyglotFormalisms +* *uuid*: 8fd979ee-625c-447d-87f1-33af4d789de5 +* *version*: 1.1.0 +* *subdir*: packages/PolyglotFormalisms.jl +* *description*: Cross-language formal methods library implementing the +aLib Common Library specification. Provides arithmetic, logic, set +theory, and algebraic operations with formal proofs and verification +certificates exportable to Idris, Lean, Coq, and Isabelle. + +=== 23. PostDisciplinary.jl + +* *name*: PostDisciplinary +* *uuid*: f1a9a0dc-9df1-4c08-8f01-4f9031796370 +* *version*: 0.1.0 +* *subdir*: packages/PostDisciplinary.jl +* *description*: Post-disciplinary research integration framework. +Connects insights across disciplines using knowledge graphs, memetic +evolution models, boundary objects, and VeriSimDB-backed provenance +tracking for transdisciplinary research projects. + +=== 24. PRComms.jl + +* *name*: PRComms +* *uuid*: 2dde2a48-bffb-456d-9be4-0a16c25066d3 +* *version*: 0.1.0 +* *subdir*: packages/PRComms.jl +* *description*: Public relations and communications management toolkit. +Provides release lifecycle management, stakeholder mapping, message +framing analysis, media outlet targeting, boundary objects for +cross-team alignment, and campaign effectiveness tracking. + +=== 25. ProvenCrypto.jl + +* *name*: ProvenCrypto +* *uuid*: 33678010-b125-405f-b046-d17447b3c4c1 +* *version*: 0.1.0 +* *subdir*: packages/ProvenCrypto.jl +* *description*: Formally verified cryptographic protocols and +post-quantum primitives. Implements Kyber KEM, Dilithium/SPHINCS+ +signatures, ZK-SNARKs, Shamir secret sharing, Noise protocol, Signal +ratchet, and TLS 1.3 with proof export to Idris 2, Lean 4, Coq, and +Isabelle/HOL. + +=== 26. QuantumCircuit.jl + +* *name*: QuantumCircuit +* *uuid*: b3d4e5f6-a7b8-4c9d-ae0f-1a2b3c4d5e6f +* *version*: 0.1.0 +* *subdir*: packages/QuantumCircuit.jl +* *description*: Quantum circuit simulation and gate-level computation. +Provides qubit registers, standard gates (Hadamard, Pauli, CNOT, +Toffoli, phase, T), measurement, Bell state preparation, circuit +composition, and coprocessor-accelerated state vector simulation via +AcceleratorGate. + +=== 27. ShellIntegration.jl + +* *name*: ShellIntegration +* *uuid*: c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f +* *version*: 0.1.0 +* *subdir*: packages/ShellIntegration.jl +* *description*: Capability-restricted shell execution from Julia. +Provides sandboxed command execution with configurable allow/deny lists, +timeout enforcement, output capture, and audit logging for safe system +interaction from Julia workflows. + +=== 28. SiliconCore.jl + +* *name*: SiliconCore +* *uuid*: c4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a +* *version*: 0.1.0 +* *subdir*: packages/SiliconCore.jl +* *description*: Cross-platform CPU feature detection and hardware +capability analysis. Probes Linux, macOS, Windows, and BSD systems for +SIMD instruction sets (SSE through AVX-512, NEON, SVE2, RVV), cache +hierarchy, core topology, and platform classification across x86_64, +aarch64, and RISC-V. + +=== 29. Skein.jl + +* *name*: Skein +* *uuid*: e8a1f3d0-7c42-4e9a-b5d1-3a7f8c2e1d0b +* *version*: 0.1.0 +* *subdir*: packages/Skein.jl +* *description*: Skein relation computation and knot polynomial +evaluation. Implements skein module algebra, Kauffman bracket via skein +relations, Jones polynomial computation, and bulk import/export for +KnotInfo-style datasets with GPU-accelerated polynomial arithmetic. + +=== 30. SMTLib.jl + +* *name*: SMTLib +* *uuid*: 7d3f9a2c-8b4e-5c1f-a6d0-9e8f7b2c3d4e +* *version*: 0.1.0 +* *subdir*: packages/SMTLib.jl +* *description*: Lightweight Julia interface to SMT solvers (Z3, CVC5) +via SMT-LIB2 format. Provides a complete pipeline from Julia expressions +to SMT-LIB2 scripts, solver invocation, model parsing, and unsatisfiable +core extraction with GPU-accelerated batch solving. + +=== 31. SoftwareSovereign.jl + +* *name*: SoftwareSovereign +* *uuid*: cc72cefe-1ea1-4255-93cd-1af1078aa475 +* *version*: 0.1.0 +* *subdir*: packages/SoftwareSovereign.jl +* *description*: Software sovereignty and supply chain analysis. +Provides dependency auditing, license compliance checking, SBOM +generation, provenance verification, and sovereignty scoring for +assessing digital autonomy and reducing vendor lock-in risk. + +=== 32. TradeUnionism.jl + +* *name*: TradeUnionism +* *uuid*: 28827ff7-c05d-49d1-8ea0-4ff47f2d6875 +* *version*: 0.1.0 +* *subdir*: packages/TradeUnionism.jl +* *description*: Trade union organising and collective bargaining +toolkit. Provides membership management, cost proposal modelling, +geospatial branch mapping (haversine distance), campaign branding, +ballot management, and collective agreement tracking. + +=== 33. ViableSystems.jl + +* *name*: ViableSystems +* *uuid*: a6c07668-559f-42e4-88f9-b00ef4c02498 +* *version*: 0.1.0 +* *subdir*: packages/ViableSystems.jl +* *description*: Viable System Model (VSM) implementation based on +Stafford Beer’s cybernetics framework. Models Systems 1-5 (operations, +coordination, control, intelligence, policy), recursive structure, +variety management, and boundary objects for organisational diagnosis. + +=== 34. ZeroProb.jl + +* *name*: ZeroProb +* *uuid*: f9e8c2e0-8b4a-4d5f-9a3c-1e2d3c4b5a6f +* *version*: 0.1.0 +* *subdir*: packages/ZeroProb.jl +* *description*: Zero-probability event handling and black swan +analysis. Provides frameworks for reasoning about measure-zero events in +finance, risk management, betting systems, and scientific edge cases +where standard probability models break down. diff --git a/REGISTRY-SUBMISSIONS.md b/REGISTRY-SUBMISSIONS.md deleted file mode 100644 index a8a77146b..000000000 --- a/REGISTRY-SUBMISSIONS.md +++ /dev/null @@ -1,265 +0,0 @@ -# Julia General Registry Submissions -# SPDX-License-Identifier: CC-BY-SA-4.0 -# -# For each package, you'll need: -# - repo: the Git URL (HTTPS for registry) -# - subdir: path from repo root to the package directory -# - name, uuid, version: from Project.toml -# - description: for the registry listing -# -# Common fields for all packages: -# repo = "https://github.com/hyperpolymath/julia-ecosystem" -# subdir = "packages/" - -## Registration command template (via LocalRegistry or Registrator): -## -## using LocalRegistry -## register( -## "packages/", -## registry = "path/to/General", -## repo = "https://github.com/hyperpolymath/julia-ecosystem", -## subdir = "packages/" -## ) -## -## Or via JuliaRegistrator bot comment on a GitHub commit: -## @JuliaRegistrator register subdir=packages/ - ---- - -## 1. AcceleratorGate.jl -- **name**: AcceleratorGate -- **uuid**: 59f742c7-270d-4a76-95d4-a853ae16cc71 -- **version**: 0.1.0 -- **subdir**: packages/AcceleratorGate.jl -- **description**: Shared coprocessor dispatch infrastructure for Julia packages. Provides a unified backend type hierarchy (GPU, TPU, NPU, FPGA, QPU, DSP, VPU, PPU, Math, Crypto) with automatic detection, platform-aware selection, resource-aware memory tracking, and self-healing fallback hooks. - -## 2. Axiology.jl -- **name**: Axiology -- **uuid**: 868b87ec-ec5d-47a0-ab5f-c8a8ecbd97bd -- **version**: 0.1.0 -- **subdir**: packages/Axiology.jl -- **description**: Value theory integration for machine learning models. Provides frameworks for embedding ethical constraints, preference orderings, and axiological assessments into model training and evaluation pipelines. - -## 3. Axiom.jl -- **name**: Axiom -- **uuid**: bbd403f8-dcc5-405a-84eb-8de9d358675c -- **version**: 0.2.0 -- **subdir**: packages/Axiom.jl -- **description**: Provably correct machine learning framework. Bridges formal verification and ML with property-based testing, SMT-backed invariant checking, and coprocessor-accelerated inference across GPU, TPU, NPU, FPGA, QPU, and other backends via AcceleratorGate. - -## 4. BowtieRisk.jl -- **name**: BowtieRisk -- **uuid**: f4857c2c-646e-44f8-8901-46c9ace85fa6 -- **version**: 0.1.0 -- **subdir**: packages/BowtieRisk.jl -- **description**: Bow-tie risk analysis with barrier assessment and Monte Carlo simulation. Models hazards, threats, top events, consequences, and barriers (preventive/mitigative) with support for escalation factors, barrier degradation, and dependency handling. - -## 5. Causals.jl -- **name**: Causals -- **uuid**: c4a8b6d2-f9e3-4c1a-b8d7-9f2e3c4d5e6f -- **version**: 0.1.0 -- **subdir**: packages/Causals.jl -- **description**: Causal inference and Applied Information Economics (AIE). Implements do-calculus, Bayesian network inference, propensity score estimation, and Hubbard's Value of Information framework with coprocessor-accelerated backends for large-scale causal discovery. - -## 6. Cladistics.jl -- **name**: Cladistics -- **uuid**: e3663be0-4771-44aa-b6d0-43b3a6d82e58 -- **version**: 0.1.0 -- **subdir**: packages/Cladistics.jl -- **description**: Phylogenetic analysis and cladistics. Implements parsimony-based tree reconstruction, character matrix operations, maximum parsimony scoring, tree rearrangement (SPR/TBR/NNI), consensus methods, and GPU-accelerated likelihood computation for large datasets. - -## 7. Cliodynamics.jl -- **name**: Cliodynamics -- **uuid**: 8d2f3e70-4c6b-5e9c-a3d1-2f8e9c0b1d2e -- **version**: 1.0.0 -- **subdir**: packages/Cliodynamics.jl -- **description**: Mathematical modeling and statistical analysis of historical dynamics. Implements Peter Turchin's cliodynamics research program: demographic-structural theory, secular cycles, elite overproduction, Political Stress Indicator (PSI), and state breakdown prediction using differential equation models. - -## 8. Cliometrics.jl -- **name**: Cliometrics -- **uuid**: 6c8e9c60-3b5a-4d8b-9f2a-1e7f8a9b0c1d -- **version**: 0.1.0 -- **subdir**: packages/Cliometrics.jl -- **description**: Quantitative economic history analysis. Applies economic theory and econometric methods to historical data: GDP reconstruction, price series deflation, demographic transition modeling, trade flow analysis, and institutional quality metrics with coprocessor-accelerated computation. - -## 9. Exnovation.jl -- **name**: Exnovation -- **uuid**: eb535ea2-a284-4d5f-a499-9e884733dc08 -- **version**: 0.1.0 -- **subdir**: packages/Exnovation.jl -- **description**: Systematic phase-out and discontinuation planning for legacy practices, products, and technologies. Provides scoring matrices, impact assessment, stakeholder analysis, transition pathway generation, and monitoring dashboards for managed exnovation processes. - -## 10. FirmwareAudit.jl -- **name**: FirmwareAudit -- **uuid**: e6a7b8c9-d0e1-4f2a-ab3c-4d5e6f7a8b9c -- **version**: 0.1.0 -- **subdir**: packages/FirmwareAudit.jl -- **description**: Firmware image auditing and vulnerability scanning. Performs entropy analysis, string extraction, header format identification (ELF, PE, Mach-O, U-Boot, Intel HEX), hash verification, and known-CVE matching against an embedded vendor vulnerability database. - -## 11. HackenbushGames.jl -- **name**: HackenbushGames -- **uuid**: 01ec8bc2-77c0-4797-a5fe-db76a6b99454 -- **version**: 0.1.0 -- **subdir**: packages/HackenbushGames.jl -- **description**: Combinatorial game theory implementation for Hackenbush games. Supports Red-Blue, Green, and multi-color Hackenbush with surreal number evaluation, game addition, canonical form reduction, and GPU/coprocessor-accelerated game tree search. - -## 12. HardwareResilience.jl -- **name**: HardwareResilience -- **uuid**: d5f6a7b8-c9d0-4e1f-9a2b-3c4d5e6f7a8b -- **version**: 0.1.0 -- **subdir**: packages/HardwareResilience.jl -- **description**: Hardware resilience detection and monitoring for Linux systems. Detects ECC memory, RAID arrays, thermal zones, watchdog timers, and redundant power supplies, producing a comprehensive resilience assessment with a supervised execution guardian for safety-critical workloads. - -## 13. Hyperpolymath.jl -- **name**: Hyperpolymath -- **uuid**: a0b1c2d3-e4f5-6a7b-8c9d-0e1f2a3b4c5d -- **version**: 0.1.0 -- **subdir**: packages/Hyperpolymath.jl -- **description**: Meta-package aggregating the hyperpolymath Julia ecosystem. Imports and re-exports all domain packages spanning logic/verification, security/forensics, history/social science, organising/action, mathematics/play, orchestration/meta, and the metal layer. - -## 14. InvestigativeJournalism.jl -- **name**: InvestigativeJournalism -- **uuid**: 379a7c0a-3675-4b32-b948-cb4760c6e442 -- **version**: 0.1.0 -- **subdir**: packages/InvestigativeJournalism.jl -- **description**: Digital forensics and investigative analysis toolkit. Provides evidence chain management, claim tracking, source credibility scoring, timeline reconstruction, network analysis of actors, and structured output for investigative reporting workflows. - -## 15. JuliaForChildren (JuliaForChildren.jl) -- **name**: JuliaForChildren -- **uuid**: c1c96f90-3ae4-433d-aa60-06e66792fdf1 -- **version**: 0.1.0 -- **subdir**: packages/JuliaForChildren.jl -- **description**: Educational Julia programming toolkit for children aged 7-14. Provides simplified interfaces for turtle graphics, Minecraft modding, KSP mission planning, game development, robotics, and collaborative coding with accessibility-first design and screen reader support. - -## 16. JuliaPackageSpitter (JuliaPackage-Reuse-Audit.jl) -- **name**: JuliaPackageSpitter -- **uuid**: 772df90b-d426-497b-8682-0a765d4f8c0b -- **version**: 0.1.0 -- **subdir**: packages/JuliaPackage-Reuse-Audit.jl -- **description**: Automated Julia package scaffolding and reuse auditing. Generates compliant package structures from configurable PackageSpec templates and audits existing packages for code reuse opportunities across the ecosystem. - -## 17. KnotTheory.jl -- **name**: KnotTheory -- **uuid**: 215268c9-7579-426e-8b7c-a3dc27acd339 -- **version**: 0.1.0 -- **subdir**: packages/KnotTheory.jl -- **description**: Mathematical knot theory library implementing planar diagram representations, polynomial invariants (Jones, Alexander, HOMFLY-PT, Kauffman bracket), Reidemeister move simplification, braid word conversion, and Seifert circle computation with a built-in knot table. - -## 18. Lithoglyph.jl -- **name**: Lithoglyph -- **uuid**: f1e2d3c4-b5a6-4b7c-8d9e-0f1a2b3c4d5e -- **version**: 0.1.0 -- **subdir**: packages/Lithoglyph.jl -- **description**: Julia bindings for the LithoGlyph database engine. Provides a client for registering and searching glyphs (symbolic data with tags and provenance) in the federated LithoGlyph store, plus an FFI bridge to the core Zig/Forth normaliser. - -## 19. LowLevel.jl -- **name**: LowLevel -- **uuid**: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d -- **version**: 0.1.0 -- **subdir**: packages/LowLevel.jl -- **description**: Low-level system introspection and hardware detection for Julia. Provides CPU architecture detection (x86_64, ARM, RISC-V, MIPS, PowerPC), SIMD capability probing, cache hierarchy analysis, and platform-specific feature flags. - -## 20. MacroPower.jl -- **name**: MacroPower -- **uuid**: b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e -- **version**: 0.1.0 -- **subdir**: packages/MacroPower.jl -- **description**: Macroeconomic power analysis and modelling through trigger-action automation workflows. Define workflows with conditional triggers and executable actions using the @workflow macro, then run them with run_workflow for policy simulation and scenario analysis. - -## 21. MinixSDK.jl -- **name**: MinixSDK -- **uuid**: d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a -- **version**: 0.1.0 -- **subdir**: packages/MinixSDK.jl -- **description**: Research SDK for targeting MINIX 3 from Julia. Provides cross-compilation scaffolding, microkernel service generation, IPC message passing primitives, and driver skeleton templates for exploring MINIX's message-based architecture from Julia. - -## 22. PolyglotFormalisms.jl -- **name**: PolyglotFormalisms -- **uuid**: 8fd979ee-625c-447d-87f1-33af4d789de5 -- **version**: 1.1.0 -- **subdir**: packages/PolyglotFormalisms.jl -- **description**: Cross-language formal methods library implementing the aLib Common Library specification. Provides arithmetic, logic, set theory, and algebraic operations with formal proofs and verification certificates exportable to Idris, Lean, Coq, and Isabelle. - -## 23. PostDisciplinary.jl -- **name**: PostDisciplinary -- **uuid**: f1a9a0dc-9df1-4c08-8f01-4f9031796370 -- **version**: 0.1.0 -- **subdir**: packages/PostDisciplinary.jl -- **description**: Post-disciplinary research integration framework. Connects insights across disciplines using knowledge graphs, memetic evolution models, boundary objects, and VeriSimDB-backed provenance tracking for transdisciplinary research projects. - -## 24. PRComms.jl -- **name**: PRComms -- **uuid**: 2dde2a48-bffb-456d-9be4-0a16c25066d3 -- **version**: 0.1.0 -- **subdir**: packages/PRComms.jl -- **description**: Public relations and communications management toolkit. Provides release lifecycle management, stakeholder mapping, message framing analysis, media outlet targeting, boundary objects for cross-team alignment, and campaign effectiveness tracking. - -## 25. ProvenCrypto.jl -- **name**: ProvenCrypto -- **uuid**: 33678010-b125-405f-b046-d17447b3c4c1 -- **version**: 0.1.0 -- **subdir**: packages/ProvenCrypto.jl -- **description**: Formally verified cryptographic protocols and post-quantum primitives. Implements Kyber KEM, Dilithium/SPHINCS+ signatures, ZK-SNARKs, Shamir secret sharing, Noise protocol, Signal ratchet, and TLS 1.3 with proof export to Idris 2, Lean 4, Coq, and Isabelle/HOL. - -## 26. QuantumCircuit.jl -- **name**: QuantumCircuit -- **uuid**: b3d4e5f6-a7b8-4c9d-ae0f-1a2b3c4d5e6f -- **version**: 0.1.0 -- **subdir**: packages/QuantumCircuit.jl -- **description**: Quantum circuit simulation and gate-level computation. Provides qubit registers, standard gates (Hadamard, Pauli, CNOT, Toffoli, phase, T), measurement, Bell state preparation, circuit composition, and coprocessor-accelerated state vector simulation via AcceleratorGate. - -## 27. ShellIntegration.jl -- **name**: ShellIntegration -- **uuid**: c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f -- **version**: 0.1.0 -- **subdir**: packages/ShellIntegration.jl -- **description**: Capability-restricted shell execution from Julia. Provides sandboxed command execution with configurable allow/deny lists, timeout enforcement, output capture, and audit logging for safe system interaction from Julia workflows. - -## 28. SiliconCore.jl -- **name**: SiliconCore -- **uuid**: c4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a -- **version**: 0.1.0 -- **subdir**: packages/SiliconCore.jl -- **description**: Cross-platform CPU feature detection and hardware capability analysis. Probes Linux, macOS, Windows, and BSD systems for SIMD instruction sets (SSE through AVX-512, NEON, SVE2, RVV), cache hierarchy, core topology, and platform classification across x86_64, aarch64, and RISC-V. - -## 29. Skein.jl -- **name**: Skein -- **uuid**: e8a1f3d0-7c42-4e9a-b5d1-3a7f8c2e1d0b -- **version**: 0.1.0 -- **subdir**: packages/Skein.jl -- **description**: Skein relation computation and knot polynomial evaluation. Implements skein module algebra, Kauffman bracket via skein relations, Jones polynomial computation, and bulk import/export for KnotInfo-style datasets with GPU-accelerated polynomial arithmetic. - -## 30. SMTLib.jl -- **name**: SMTLib -- **uuid**: 7d3f9a2c-8b4e-5c1f-a6d0-9e8f7b2c3d4e -- **version**: 0.1.0 -- **subdir**: packages/SMTLib.jl -- **description**: Lightweight Julia interface to SMT solvers (Z3, CVC5) via SMT-LIB2 format. Provides a complete pipeline from Julia expressions to SMT-LIB2 scripts, solver invocation, model parsing, and unsatisfiable core extraction with GPU-accelerated batch solving. - -## 31. SoftwareSovereign.jl -- **name**: SoftwareSovereign -- **uuid**: cc72cefe-1ea1-4255-93cd-1af1078aa475 -- **version**: 0.1.0 -- **subdir**: packages/SoftwareSovereign.jl -- **description**: Software sovereignty and supply chain analysis. Provides dependency auditing, license compliance checking, SBOM generation, provenance verification, and sovereignty scoring for assessing digital autonomy and reducing vendor lock-in risk. - -## 32. TradeUnionism.jl -- **name**: TradeUnionism -- **uuid**: 28827ff7-c05d-49d1-8ea0-4ff47f2d6875 -- **version**: 0.1.0 -- **subdir**: packages/TradeUnionism.jl -- **description**: Trade union organising and collective bargaining toolkit. Provides membership management, cost proposal modelling, geospatial branch mapping (haversine distance), campaign branding, ballot management, and collective agreement tracking. - -## 33. ViableSystems.jl -- **name**: ViableSystems -- **uuid**: a6c07668-559f-42e4-88f9-b00ef4c02498 -- **version**: 0.1.0 -- **subdir**: packages/ViableSystems.jl -- **description**: Viable System Model (VSM) implementation based on Stafford Beer's cybernetics framework. Models Systems 1-5 (operations, coordination, control, intelligence, policy), recursive structure, variety management, and boundary objects for organisational diagnosis. - -## 34. ZeroProb.jl -- **name**: ZeroProb -- **uuid**: f9e8c2e0-8b4a-4d5f-9a3c-1e2d3c4b5a6f -- **version**: 0.1.0 -- **subdir**: packages/ZeroProb.jl -- **description**: Zero-probability event handling and black swan analysis. Provides frameworks for reasoning about measure-zero events in finance, risk management, betting systems, and scientific edge cases where standard probability models break down. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 000000000..592353679 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,30 @@ +== TEST-NEEDS.md — julia-ecosystem + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current Test State + +[cols=",,",options="header",] +|=== +|Category |Count |Notes +|Test files |15 |Current state +|=== + +=== What’s Covered + +* [x] 15 existing test file(s) +* [x] Julia test suite + +=== Still Missing (for CRG B+) + +* [ ] Zig FFI tests (if applicable) +* [ ] CI/CD test automation +* [ ] Property-based tests +* [ ] Edge case coverage + +=== Run Tests + +[source,bash] +---- +cd packages && julia -e 'using Pkg; Pkg.test()' +---- diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 47c91a525..000000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,27 +0,0 @@ -# TEST-NEEDS.md — julia-ecosystem - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current Test State - -| Category | Count | Notes | -|----------|-------|-------| -| Test files | 15 | Current state | - -## What's Covered - -- [x] 15 existing test file(s) -- [x] Julia test suite - -## Still Missing (for CRG B+) - -- [ ] Zig FFI tests (if applicable) -- [ ] CI/CD test automation -- [ ] Property-based tests -- [ ] Edge case coverage - -## Run Tests - -```bash -cd packages && julia -e 'using Pkg; Pkg.test()' -``` diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 58% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index e685d7a63..d51386cd0 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,15 @@ - - +== TOPOLOGY.md — julia-ecosystem -# TOPOLOGY.md — julia-ecosystem +=== Purpose -## Purpose +Central monorepo unifying 20+ hyperpolymath Julia libraries into +cohesive post-disciplinary research and verified computing ecosystem. +Spans formal logic, cryptography, historical dynamics, labor organizing, +and domain-specific applications. -Central monorepo unifying 20+ hyperpolymath Julia libraries into cohesive post-disciplinary research and verified computing ecosystem. Spans formal logic, cryptography, historical dynamics, labor organizing, and domain-specific applications. +=== Module Map -## Module Map - -``` +.... julia-ecosystem/ ├── logic/ │ ├── Axiom.jl # Formal logic and set theory @@ -26,17 +26,17 @@ julia-ecosystem/ │ └── ... (domain-specific apps) ├── README.adoc # Ecosystem overview └── Project.toml # Monorepo manifest -``` +.... -## Data Flow +=== Data Flow -``` +.... [Research Question] ──► [Pick Library] ──► [Computation] ──► [Verified Results] -``` +.... -## Key Invariants +=== Key Invariants -- All libraries share common Julia ecosystem infrastructure -- Cross-library dependencies managed via shared Project.toml -- Unified testing, CI/CD, and documentation -- Post-disciplinary focus: bridges multiple domains +* All libraries share common Julia ecosystem infrastructure +* Cross-library dependencies managed via shared Project.toml +* Unified testing, CI/CD, and documentation +* Post-disciplinary focus: bridges multiple domains diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 000000000..b39d90eb7 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — julia-ecosystem (Developer) + +=== What is julia-ecosystem? + +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 825a03283..000000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — julia-ecosystem (Developer) - -## What is julia-ecosystem? -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 000000000..4c34d0b06 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — julia-ecosystem (User) + +=== What is julia-ecosystem? + +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 3de3747d0..000000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — julia-ecosystem (User) - -## What is julia-ecosystem? -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/packages/Causals.jl/ABI-FFI-README.md b/packages/Axiology.jl/ABI-FFI-README.adoc similarity index 74% rename from packages/Causals.jl/ABI-FFI-README.md rename to packages/Axiology.jl/ABI-FFI-README.adoc index 08d35da64..8e5244189 100644 --- a/packages/Causals.jl/ABI-FFI-README.md +++ b/packages/Axiology.jl/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/Axiology.jl/CODE_OF_CONDUCT.adoc b/packages/Axiology.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/Axiology.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Axiology.jl/CODE_OF_CONDUCT.md b/packages/Axiology.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/Axiology.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Axiology.jl/CONTRIBUTING.adoc b/packages/Axiology.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/Axiology.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Axiology.jl/CONTRIBUTING.md b/packages/Axiology.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/Axiology.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Axiology.jl/SECURITY.adoc b/packages/Axiology.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/Axiology.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Axiology.jl/SECURITY.md b/packages/Axiology.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/Axiology.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Axiology.jl/SONNET-TASKS.adoc b/packages/Axiology.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..114032e87 --- /dev/null +++ b/packages/Axiology.jl/SONNET-TASKS.adoc @@ -0,0 +1,560 @@ +== SONNET-TASKS.md – Axiology.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 35% +____ + +The README claims "`Production Ready - 1,088 lines of code, 45/45 tests +passing`" and STATE.scm claims `+overall-completion 100+`. Both are +FALSE. The source files contain critical duplicate orphan code blocks +after every function in `+fairness.jl+` and several in `+welfare.jl+` +that will cause Julia parse errors at module load time. The test suite +cannot possibly pass in its current state. Additionally, four API +functions advertised in the README do not exist, the examples directory +contains unrelated files, and `+verify_value+` is a trivial stub. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update STATE.scm with honest completion percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/Axiology.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Remove duplicate orphan code blocks in fairness.jl (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/src/fairness.jl+` + +*Problem:* Every function in this file has a complete, documented +implementation that ends with `+end+`, immediately followed by an orphan +duplicate of the function body (without the `+function+` declaration). +In Julia, code after `+end+` at top level is executed at load time, +causing errors. There are 6 orphan blocks: + +* Lines 101-119: orphan duplicate of `+demographic_parity+` body +* Lines 201-238: orphan duplicate of `+equalized_odds+` body +* Lines 313-335: orphan duplicate of `+equal_opportunity+` body +* Lines 406-424: orphan duplicate of `+disparate_impact+` body +* Lines 502-518: orphan duplicate of `+individual_fairness+` body (also +hardcodes 0.8 instead of using `+similarity_threshold+` parameter) +* Lines 616-642: orphan duplicate of `+satisfy(::Fairness, ::Dict)+` +body (also lacks `+individual_fairness+` metric support) + +Also: duplicate SPDX header on lines 1-2 and 4-5. + +*What to do:* 1. Delete line 4 +(`+# SPDX-License-Identifier: CC-BY-SA-4.0+`) and line 5 +(`+# Copyright (c) 2026 Jonathan D.A. Jewell +`) +– these are duplicates of lines 1-2. 2. Delete lines 101-119 (orphan +`+demographic_parity+` body after the real function’s `+end+` on line +100). 3. Delete lines 201-238 (orphan `+equalized_odds+` body after the +real function’s `+end+` on line 200). 4. Delete lines 313-335 (orphan +`+equal_opportunity+` body after the real function’s `+end+` on line +312). 5. Delete lines 406-424 (orphan `+disparate_impact+` body after +the real function’s `+end+` on line 405). 6. Delete lines 502-518 +(orphan `+individual_fairness+` body after the real function’s `+end+` +on line 501). 7. Delete lines 616-642 (orphan `+satisfy+` body after the +real function’s `+end+` on line 615). 8. IMPORTANT: Delete from highest +line numbers first to avoid line number shifts. 9. After deletion, +verify there are exactly 6 `+function+` declarations and 1 `+satisfy+` +method in the file. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +# This must not error: +include("src/types.jl") +include("src/fairness.jl") +# Verify functions work: +using Statistics +@assert demographic_parity([1,0,1,0], [:a,:b,:a,:b]) == 0.0 +@assert equalized_odds([1,0,1,0], [1,0,1,0], [:a,:b,:a,:b]) == 0.0 +@assert equal_opportunity([1,0,1,0], [1,0,1,0], [:a,:b,:a,:b]) == 0.0 +@assert disparate_impact([1,1,0,0], [:a,:b,:a,:b]) == 1.0 +println("TASK 1 PASSED") +---- + +''''' + +=== TASK 2: Remove duplicate orphan code blocks in welfare.jl (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/src/welfare.jl+` + +*Problem:* Three functions have orphan duplicate bodies after their +`+end+`: + +* Lines 123-124: orphan duplicate of `+rawlsian_welfare+` body (just +`+return minimum(utilities)+` and `+end+`) +* Lines 179-180: orphan duplicate of `+egalitarian_welfare+` body (just +`+return -var(utilities)+` and `+end+`) +* Lines 241-257: orphan duplicate of `+satisfy(::Welfare, ::Dict)+` body + +Also: duplicate SPDX header on lines 1-2 and 4-5. + +*What to do:* 1. Delete line 4 and line 5 (duplicate SPDX header). 2. +Delete lines 241-257 (orphan `+satisfy(Welfare)+` body after the real +function’s `+end+` on line 240). 3. Delete lines 179-180 (orphan +`+egalitarian_welfare+` body after the real function’s `+end+` on line +178). 4. Delete lines 123-124 (orphan `+rawlsian_welfare+` body after +the real function’s `+end+` on line 122). 5. Delete from highest line +numbers first. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +include("src/types.jl") +include("src/fairness.jl") # Must work after Task 1 +include("src/welfare.jl") +# Verify functions work: +@assert utilitarian_welfare([10.0, 8.0, 12.0]) == 30.0 +@assert rawlsian_welfare([10.0, 8.0, 12.0]) == 8.0 +@assert egalitarian_welfare([10.0, 10.0, 10.0]) == 0.0 +println("TASK 2 PASSED") +---- + +''''' + +=== TASK 3: Remove duplicate SPDX header in optimization.jl (LOW) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/src/optimization.jl+` + +*Problem:* Duplicate SPDX header on lines 1-2 and 4-5. + +*What to do:* 1. Delete line 4 +(`+# SPDX-License-Identifier: CC-BY-SA-4.0+`) and line 5 +(`+# Copyright (c) 2026 Jonathan D.A. Jewell +`). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +# Full module load test: +using Axiology +@assert Axiology.value_score(Fairness(metric=:demographic_parity, threshold=0.1), + Dict(:predictions => [1,0,1,0], :protected => [:a,:b,:a,:b])) == 1.0 +println("TASK 3 PASSED") +---- + +''''' + +=== TASK 4: Verify full module loads and tests pass (CRITICAL) + +*Files:* All `+src/*.jl+` and `+test/runtests.jl+` + +*Problem:* After Tasks 1-3, the module should load cleanly. Run the full +test suite to confirm the 45 tests listed in `+test/runtests.jl+` all +pass. + +*What to do:* 1. Run `+julia --project=. -e 'using Pkg; Pkg.test()'+` +from the repo root. 2. If any tests fail, fix them. The test +expectations should match the documented (non-orphan) implementations. +3. If there are remaining load errors, track down and fix any additional +orphan code. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +Pkg.test() +# All tests must pass with 0 failures, 0 errors. +println("TASK 4 PASSED") +---- + +''''' + +=== TASK 5: Remove unrelated example files (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Axiology.jl/examples/SafeDOMExample.res+` - +`+/var$REPOS_DIR/Axiology.jl/examples/web-project-deno.json+` + +*Problem:* `+SafeDOMExample.res+` is a ReScript file for DOM +manipulation that has nothing to do with Axiology.jl. It also uses an +`+AGPL-3.0-or-later+` SPDX header, which violates the project’s license +policy. `+web-project-deno.json+` is an unrelated Deno project config. +Both are clearly copy-paste artifacts from the RSR template or another +project. + +*What to do:* 1. Delete +`+/var$REPOS_DIR/Axiology.jl/examples/SafeDOMExample.res+`. 2. Delete +`+/var$REPOS_DIR/Axiology.jl/examples/web-project-deno.json+`. 3. Create +a real example file at +`+/var$REPOS_DIR/Axiology.jl/examples/basic_usage.jl+` that +demonstrates: - Creating Fairness, Welfare, Profit, Efficiency, and +Safety values - Using `+satisfy+` to check value satisfaction - Using +`+maximize+` to compute value scores - Using `+pareto_frontier+` for +multi-objective optimization - Using `+weighted_score+` for aggregation +4. The example file must use `+# SPDX-License-Identifier: CC-BY-SA-4.0+` +header. 5. The example must actually run: +`+julia --project=. examples/basic_usage.jl+` + +*Verification:* + +[source,julia] +---- +# Run the example: +cd("/var$REPOS_DIR/Axiology.jl") +include("examples/basic_usage.jl") +# Must complete without errors and print meaningful output. +println("TASK 5 PASSED") +---- + +''''' + +=== TASK 6: Fix STATE.scm to reflect honest completion (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/.machine_readable/STATE.scm+` + +*Problem:* STATE.scm claims `+overall-completion 100+` and +`+phase "production-ready"+`. This is dishonest. After Tasks 1-4, the +core library works, but: - `+verify_value+` is a trivial stub (just +reads `+proof[:verified]+`) - `+maximize(Efficiency)+` returns hardcoded +`+1.0+` for pareto/kaldor_hicks metrics - No ML framework integration +exists - No formal verification integration exists - README advertises 4 +functions that don’t exist - `+value_score+` for Welfare uses hardcoded +normalization assumptions + +*What to do:* 1. Change `+overall-completion+` from `+100+` to `+65+`. +2. Change `+phase+` from `+"production-ready"+` to `+"alpha"+`. 3. +Update the `+Type Definitions+` component: change `+completion+` from +`+10+` to `+100+` and `+status+` from `+"minimal"+` to `+"complete"+` +(it IS complete after Tasks 1-2). 4. Update `+Julia Implementation+` +component: change `+completion+` from `+100+` to `+70+`, change +`+description+` to note that core functions work but `+verify_value+` is +a stub, `+maximize(Efficiency)+` has placeholder returns, and +normalization in `+value_score+` uses hardcoded assumptions. 5. Add a +new component for "`ML Integration`" with `+status "not-started"+` and +`+completion 0+`. 6. Add a new component for "`Formal Verification`" +with `+status "stub"+` and `+completion 5+` (only `+verify_value+` +exists as a trivial wrapper). 7. Update `+updated+` date to +`+"2026-02-12"+`. + +*Verification:* + +[source,bash] +---- +# Check that STATE.scm is valid Scheme and contains updated values: +grep 'overall-completion 65' /var$REPOS_DIR/Axiology.jl/.machine_readable/STATE.scm +grep 'phase "alpha"' /var$REPOS_DIR/Axiology.jl/.machine_readable/STATE.scm +echo "TASK 6 PASSED" +---- + +''''' + +=== TASK 7: Fix README.adoc false claims (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/README.adoc+` + +*Problem:* Multiple false claims and advertised-but-nonexistent API: + +* Line 10: Claims "`Production Ready`" – should say "`Alpha`" after +Tasks 1-4 +* Line 174: Documents `+select_solution(solutions, preference)+` – this +function DOES NOT EXIST +* Line 179: Documents `+echidna_verify(value, system)+` – this function +DOES NOT EXIST +* Line 182: Documents `+fairlearn_constraint(value)+` – this function +DOES NOT EXIST +* Line 185: Documents `+flux_loss(value)+` – this function DOES NOT +EXIST +* Lines 86-93: Example uses +`+train(algorithm, data, constraints=[fairness])+` – no such function +* Lines 104-113: Example uses +`+select_solution(solutions, preference=:balanced)+` – no such function +* Lines 119-138: Example uses `+prove+`, `+Verified+`, +`+verification.counterexample+` – none exist +* Lines 238-241: Development status checkboxes are wrong (Pareto IS +implemented, marked unchecked) +* Lines 269-274: Claims dual MIT/PMPL license but project actually uses +MPL-2.0 only + +*What to do:* 1. Change line 10 status to: +`+> **Status**: Alpha - Core value system functional, integration APIs planned+` +2. Remove the `+=== Integration APIs+` section (lines 177-186) entirely. +These functions do not exist. 3. Fix the Usage Examples to use actual +API signatures that exist in the codebase. Replace the fake `+train()+`, +`+select_solution()+`, `+prove()+`, `+Verified+` examples with real +working examples using `+satisfy+`, `+maximize+`, `+value_score+`, +`+weighted_score+`, `+pareto_frontier+`. 4. Fix the Development Status +checkboxes: - Check `+[x] Multi-objective optimization+` (Pareto +frontier IS implemented) - Keep +`+[ ] Formal verification integration with ECHIDNA+` unchecked - Keep +`+[ ] ML fairness library integration+` unchecked - Keep +`+[ ] Comprehensive documentation+` unchecked 5. Fix the License +section: Remove mention of MIT. The license is MPL-2.0 per the LICENSE +file and SPDX headers. 6. Update the ECHIDNA Integration section to +clearly state it is PLANNED, not implemented. + +*Verification:* + +[source,bash] +---- +# Verify no mention of nonexistent functions: +! grep -q 'select_solution' /var$REPOS_DIR/Axiology.jl/README.adoc +! grep -q 'echidna_verify' /var$REPOS_DIR/Axiology.jl/README.adoc +! grep -q 'fairlearn_constraint' /var$REPOS_DIR/Axiology.jl/README.adoc +! grep -q 'flux_loss' /var$REPOS_DIR/Axiology.jl/README.adoc +! grep -q 'Production Ready' /var$REPOS_DIR/Axiology.jl/README.adoc +echo "TASK 7 PASSED" +---- + +''''' + +=== TASK 8: Fix ROADMAP.adoc incorrect checkboxes (LOW) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/ROADMAP.adoc+` + +*Problem:* Line 14 marks "`Multi-objective optimization (Pareto +frontiers)`" as unchecked `+[ ]+`, but `+pareto_frontier+`, +`+dominated+`, `+value_score+`, `+weighted_score+`, and +`+normalize_scores+` are all implemented in `+optimization.jl+`. Lines +61-65 mark all fairness metrics as unchecked, but +`+demographic_parity+`, `+equalized_odds+`, `+equal_opportunity+`, +`+disparate_impact+`, and `+individual_fairness+` are all implemented in +`+fairness.jl+`. + +*What to do:* 1. Line 14: Change +`+* [ ] Multi-objective optimization (Pareto frontiers)+` to +`+* [x] Multi-objective optimization (Pareto frontiers)+` 2. Lines +61-65: Check all five fairness metrics that are implemented: - +`+* [x] Demographic parity (group fairness)+` - +`+* [x] Equalized odds (conditional fairness)+` - +`+* [ ] Predictive parity (calibration)+` (keep unchecked, not +implemented) - `+* [x] Individual fairness (Lipschitz continuity)+` - +`+* [ ] Counterfactual fairness (causal)+` (keep unchecked, not +implemented) 3. Under v0.2.0, check "`Implement Pareto frontier +algorithm for value tradeoffs`". + +*Verification:* + +[source,bash] +---- +grep '\[x\] Multi-objective optimization' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc +grep '\[x\] Demographic parity' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc +grep '\[x\] Equalized odds' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc +grep '\[x\] Individual fairness' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc +echo "TASK 8 PASSED" +---- + +''''' + +=== TASK 9: Implement real verify_value logic (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/src/welfare.jl+` (lines 730-733) + +*Problem:* `+verify_value(value::Value, proof::Dict)::Bool+` is a +trivial stub that only reads `+proof[:verified]+`. It does no actual +verification. The docstring (lines 694-729) describes checking for a +`+:prover+` key and `+:details+` key, but the function ignores them +entirely. + +*What to do:* 1. Expand `+verify_value+` to: - Require +`+proof[:verified]+` to be a `+Bool+` (error if missing or wrong type) - +If `+value isa Safety+` and `+value.critical == true+`, also require +that `+proof+` contains a `+:prover+` key (it should be verified by a +named prover, not just asserted) - Log/return the prover name and +details if present - Return `+proof[:verified]+` as before for the +boolean result, but with the added validation 2. Add a `+verify_value+` +method specifically for `+Safety+` that enforces critical safety proofs +must have a `+:prover+` field. 3. Add tests in `+test/runtests.jl+` for +the new validation behavior: - Test that a critical Safety value with no +`+:prover+` in proof returns `+false+` or errors - Test that a +non-critical Safety value without `+:prover+` still works - Test that +other Value types work as before + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +using Axiology + +# Non-critical safety: no prover needed +s_noncrit = Safety(invariant="test", critical=false) +@assert verify_value(s_noncrit, Dict(:verified => true)) == true + +# Critical safety: prover should be required +s_crit = Safety(invariant="test", critical=true) +@assert verify_value(s_crit, Dict(:verified => true, :prover => :Lean)) == true + +# Other value types still work: +f = Fairness(metric=:demographic_parity, threshold=0.05) +@assert verify_value(f, Dict(:verified => true)) == true +@assert verify_value(f, Dict(:verified => false)) == false + +println("TASK 9 PASSED") +---- + +''''' + +=== TASK 10: Improve maximize(Efficiency) for pareto/kaldor_hicks (LOW) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/src/welfare.jl+` (lines 560-574) + +*Problem:* `+maximize(value::Efficiency, initial_state::Dict)+` returns +a hardcoded `+1.0+` for `+:pareto+` and `+:kaldor_hicks+` metrics (line +570). The docstring on line 540 explicitly acknowledges this is a +"`placeholder`". For `+:pareto+`, it should return `+1.0+` if +`+state[:is_pareto_efficient]+` is `+true+` and `+0.0+` otherwise. For +`+:kaldor_hicks+`, it should return `+state[:net_gain]+`. + +*What to do:* 1. For `+:pareto+` metric: read +`+initial_state[:is_pareto_efficient]+` and return `+1.0+` if true, +`+0.0+` if false. Error if key is missing. 2. For `+:kaldor_hicks+` +metric: read `+initial_state[:net_gain]+` and return it directly. Error +if key is missing. 3. Update the docstring to remove the "`placeholder`" +language. 4. Add tests: - +`+maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => true))+` +returns `+1.0+` - +`+maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => false))+` +returns `+0.0+` - +`+maximize(Efficiency(metric=:kaldor_hicks, target=100.0), Dict(:net_gain => 150.0))+` +returns `+150.0+` + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +using Axiology + +@assert maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => true)) == 1.0 +@assert maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => false)) == 0.0 +@assert maximize(Efficiency(metric=:kaldor_hicks, target=100.0), Dict(:net_gain => 150.0)) == 150.0 +@assert maximize(Efficiency(metric=:computation_time), Dict(:computation_time => 0.5)) == -0.5 + +println("TASK 10 PASSED") +---- + +''''' + +=== TASK 11: Add equal_opportunity to test suite (LOW) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/test/runtests.jl+` + +*Problem:* The test suite tests `+demographic_parity+`, +`+disparate_impact+`, and `+individual_fairness+` (via `+satisfy+`), but +never directly tests `+equalized_odds+` or `+equal_opportunity+` metric +functions. `+individual_fairness+` is also only tested indirectly +through `+satisfy+`. Add direct tests for completeness. + +*What to do:* 1. Add a `+@testset "Equalized Odds"+` block inside +"`Fairness Metrics`" that: - Tests perfect equalized odds (same TPR and +FPR across groups) returns 0.0 - Tests a case with known unequal TPR/FPR +and verifies disparity > 0.0 2. Add a `+@testset "Equal Opportunity"+` +block inside "`Fairness Metrics`" that: - Tests perfect equal +opportunity (same TPR across groups) returns 0.0 - Tests a case with +unequal TPR 3. Add a `+@testset "Individual Fairness"+` block inside +"`Fairness Metrics`" that: - Tests with a similarity matrix where +similar individuals get similar predictions (returns ~0.0) - Tests with +a similarity matrix where similar individuals get different predictions +(returns > 0) + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +Pkg.test() +# Verify the new testsets appear in output and pass +println("TASK 11 PASSED") +---- + +''''' + +=== TASK 12: Add edge case tests (LOW) + +*Files:* `+/var$REPOS_DIR/Axiology.jl/test/runtests.jl+` + +*Problem:* No tests for edge cases or error conditions: - Empty vectors +- Single-group protected attributes - Zero-weight values in +weighted_score - Invalid metric symbols (should error) - Missing state +keys (should error) + +*What to do:* 1. Add a `+@testset "Edge Cases"+` block with subtests +for: - `+demographic_parity+` with single group returns 0.0 - +`+disparate_impact+` with single group returns 1.0 - +`+utilitarian_welfare+` with empty vector returns 0.0 - +`+rawlsian_welfare+` with empty vector throws error - +`+egalitarian_welfare+` with single element returns 0.0 - +`+normalize_scores+` with identical scores returns all 1.0 - +`+normalize_scores+` with empty vector throws ArgumentError - +`+Fairness+` constructor with invalid metric throws AssertionError - +`+Safety+` constructor with empty invariant throws AssertionError - +`+weighted_score+` with all zero weights returns 0.0 - +`+satisfy(Fairness, Dict())+` without `+:predictions+` throws error + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Axiology.jl") +using Pkg; Pkg.activate(".") +Pkg.test() +println("TASK 12 PASSED") +---- + +''''' + +=== FINAL VERIFICATION + +After all tasks are complete, run the following sequence: + +[source,bash] +---- +cd /var$REPOS_DIR/Axiology.jl + +# 1. Module loads without errors +julia --project=. -e 'using Axiology; println("Module loaded successfully")' + +# 2. Full test suite passes +julia --project=. -e 'using Pkg; Pkg.test()' + +# 3. No orphan code blocks remain (no bare @assert at top level outside functions) +julia --project=. -e ' + for f in ["src/fairness.jl", "src/welfare.jl", "src/optimization.jl"] + content = read(f, String) + # Count function declarations vs end statements + funcs = count(r"^function ", content) + println("$f: $funcs function declarations") + end + println("Source structure check passed") +' + +# 4. No remaining stubs or placeholders +grep -rn "placeholder\|not implemented\|TODO\|FIXME\|HACK\|XXX\|STUB" src/ || echo "No stubs found" + +# 5. No AGPL headers (wrong license) +grep -rn "AGPL" . --include="*.jl" --include="*.res" --include="*.json" || echo "No AGPL found" + +# 6. Example runs +julia --project=. examples/basic_usage.jl + +# 7. STATE.scm is honest +grep 'overall-completion 65' .machine_readable/STATE.scm && echo "STATE.scm is honest" + +echo "ALL VERIFICATION PASSED" +---- diff --git a/packages/Axiology.jl/SONNET-TASKS.md b/packages/Axiology.jl/SONNET-TASKS.md deleted file mode 100644 index a12347fb5..000000000 --- a/packages/Axiology.jl/SONNET-TASKS.md +++ /dev/null @@ -1,481 +0,0 @@ -# SONNET-TASKS.md -- Axiology.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 35% - -The README claims "Production Ready - 1,088 lines of code, 45/45 tests passing" and STATE.scm -claims `overall-completion 100`. Both are FALSE. The source files contain critical duplicate -orphan code blocks after every function in `fairness.jl` and several in `welfare.jl` that will -cause Julia parse errors at module load time. The test suite cannot possibly pass in its current -state. Additionally, four API functions advertised in the README do not exist, the examples -directory contains unrelated files, and `verify_value` is a trivial stub. - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update STATE.scm with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/Axiology.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Remove duplicate orphan code blocks in fairness.jl (CRITICAL) - -**Files:** `/var$REPOS_DIR/Axiology.jl/src/fairness.jl` - -**Problem:** Every function in this file has a complete, documented implementation that ends -with `end`, immediately followed by an orphan duplicate of the function body (without the -`function` declaration). In Julia, code after `end` at top level is executed at load time, -causing errors. There are 6 orphan blocks: - -- Lines 101-119: orphan duplicate of `demographic_parity` body -- Lines 201-238: orphan duplicate of `equalized_odds` body -- Lines 313-335: orphan duplicate of `equal_opportunity` body -- Lines 406-424: orphan duplicate of `disparate_impact` body -- Lines 502-518: orphan duplicate of `individual_fairness` body (also hardcodes 0.8 instead of using `similarity_threshold` parameter) -- Lines 616-642: orphan duplicate of `satisfy(::Fairness, ::Dict)` body (also lacks `individual_fairness` metric support) - -Also: duplicate SPDX header on lines 1-2 and 4-5. - -**What to do:** -1. Delete line 4 (`# SPDX-License-Identifier: CC-BY-SA-4.0`) and line 5 (`# Copyright (c) 2026 Jonathan D.A. Jewell `) -- these are duplicates of lines 1-2. -2. Delete lines 101-119 (orphan `demographic_parity` body after the real function's `end` on line 100). -3. Delete lines 201-238 (orphan `equalized_odds` body after the real function's `end` on line 200). -4. Delete lines 313-335 (orphan `equal_opportunity` body after the real function's `end` on line 312). -5. Delete lines 406-424 (orphan `disparate_impact` body after the real function's `end` on line 405). -6. Delete lines 502-518 (orphan `individual_fairness` body after the real function's `end` on line 501). -7. Delete lines 616-642 (orphan `satisfy` body after the real function's `end` on line 615). -8. IMPORTANT: Delete from highest line numbers first to avoid line number shifts. -9. After deletion, verify there are exactly 6 `function` declarations and 1 `satisfy` method in the file. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -# This must not error: -include("src/types.jl") -include("src/fairness.jl") -# Verify functions work: -using Statistics -@assert demographic_parity([1,0,1,0], [:a,:b,:a,:b]) == 0.0 -@assert equalized_odds([1,0,1,0], [1,0,1,0], [:a,:b,:a,:b]) == 0.0 -@assert equal_opportunity([1,0,1,0], [1,0,1,0], [:a,:b,:a,:b]) == 0.0 -@assert disparate_impact([1,1,0,0], [:a,:b,:a,:b]) == 1.0 -println("TASK 1 PASSED") -``` - ---- - -## TASK 2: Remove duplicate orphan code blocks in welfare.jl (CRITICAL) - -**Files:** `/var$REPOS_DIR/Axiology.jl/src/welfare.jl` - -**Problem:** Three functions have orphan duplicate bodies after their `end`: - -- Lines 123-124: orphan duplicate of `rawlsian_welfare` body (just `return minimum(utilities)` and `end`) -- Lines 179-180: orphan duplicate of `egalitarian_welfare` body (just `return -var(utilities)` and `end`) -- Lines 241-257: orphan duplicate of `satisfy(::Welfare, ::Dict)` body - -Also: duplicate SPDX header on lines 1-2 and 4-5. - -**What to do:** -1. Delete line 4 and line 5 (duplicate SPDX header). -2. Delete lines 241-257 (orphan `satisfy(Welfare)` body after the real function's `end` on line 240). -3. Delete lines 179-180 (orphan `egalitarian_welfare` body after the real function's `end` on line 178). -4. Delete lines 123-124 (orphan `rawlsian_welfare` body after the real function's `end` on line 122). -5. Delete from highest line numbers first. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -include("src/types.jl") -include("src/fairness.jl") # Must work after Task 1 -include("src/welfare.jl") -# Verify functions work: -@assert utilitarian_welfare([10.0, 8.0, 12.0]) == 30.0 -@assert rawlsian_welfare([10.0, 8.0, 12.0]) == 8.0 -@assert egalitarian_welfare([10.0, 10.0, 10.0]) == 0.0 -println("TASK 2 PASSED") -``` - ---- - -## TASK 3: Remove duplicate SPDX header in optimization.jl (LOW) - -**Files:** `/var$REPOS_DIR/Axiology.jl/src/optimization.jl` - -**Problem:** Duplicate SPDX header on lines 1-2 and 4-5. - -**What to do:** -1. Delete line 4 (`# SPDX-License-Identifier: CC-BY-SA-4.0`) and line 5 (`# Copyright (c) 2026 Jonathan D.A. Jewell `). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -# Full module load test: -using Axiology -@assert Axiology.value_score(Fairness(metric=:demographic_parity, threshold=0.1), - Dict(:predictions => [1,0,1,0], :protected => [:a,:b,:a,:b])) == 1.0 -println("TASK 3 PASSED") -``` - ---- - -## TASK 4: Verify full module loads and tests pass (CRITICAL) - -**Files:** All `src/*.jl` and `test/runtests.jl` - -**Problem:** After Tasks 1-3, the module should load cleanly. Run the full test suite to confirm -the 45 tests listed in `test/runtests.jl` all pass. - -**What to do:** -1. Run `julia --project=. -e 'using Pkg; Pkg.test()'` from the repo root. -2. If any tests fail, fix them. The test expectations should match the documented (non-orphan) implementations. -3. If there are remaining load errors, track down and fix any additional orphan code. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -Pkg.test() -# All tests must pass with 0 failures, 0 errors. -println("TASK 4 PASSED") -``` - ---- - -## TASK 5: Remove unrelated example files (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Axiology.jl/examples/SafeDOMExample.res` -- `/var$REPOS_DIR/Axiology.jl/examples/web-project-deno.json` - -**Problem:** `SafeDOMExample.res` is a ReScript file for DOM manipulation that has nothing to do -with Axiology.jl. It also uses an `AGPL-3.0-or-later` SPDX header, which violates the project's -license policy. `web-project-deno.json` is an unrelated Deno project config. Both are clearly -copy-paste artifacts from the RSR template or another project. - -**What to do:** -1. Delete `/var$REPOS_DIR/Axiology.jl/examples/SafeDOMExample.res`. -2. Delete `/var$REPOS_DIR/Axiology.jl/examples/web-project-deno.json`. -3. Create a real example file at `/var$REPOS_DIR/Axiology.jl/examples/basic_usage.jl` that demonstrates: - - Creating Fairness, Welfare, Profit, Efficiency, and Safety values - - Using `satisfy` to check value satisfaction - - Using `maximize` to compute value scores - - Using `pareto_frontier` for multi-objective optimization - - Using `weighted_score` for aggregation -4. The example file must use `# SPDX-License-Identifier: CC-BY-SA-4.0` header. -5. The example must actually run: `julia --project=. examples/basic_usage.jl` - -**Verification:** -```julia -# Run the example: -cd("/var$REPOS_DIR/Axiology.jl") -include("examples/basic_usage.jl") -# Must complete without errors and print meaningful output. -println("TASK 5 PASSED") -``` - ---- - -## TASK 6: Fix STATE.scm to reflect honest completion (MEDIUM) - -**Files:** `/var$REPOS_DIR/Axiology.jl/.machine_readable/STATE.scm` - -**Problem:** STATE.scm claims `overall-completion 100` and `phase "production-ready"`. This is -dishonest. After Tasks 1-4, the core library works, but: -- `verify_value` is a trivial stub (just reads `proof[:verified]`) -- `maximize(Efficiency)` returns hardcoded `1.0` for pareto/kaldor_hicks metrics -- No ML framework integration exists -- No formal verification integration exists -- README advertises 4 functions that don't exist -- `value_score` for Welfare uses hardcoded normalization assumptions - -**What to do:** -1. Change `overall-completion` from `100` to `65`. -2. Change `phase` from `"production-ready"` to `"alpha"`. -3. Update the `Type Definitions` component: change `completion` from `10` to `100` and `status` from `"minimal"` to `"complete"` (it IS complete after Tasks 1-2). -4. Update `Julia Implementation` component: change `completion` from `100` to `70`, change `description` to note that core functions work but `verify_value` is a stub, `maximize(Efficiency)` has placeholder returns, and normalization in `value_score` uses hardcoded assumptions. -5. Add a new component for "ML Integration" with `status "not-started"` and `completion 0`. -6. Add a new component for "Formal Verification" with `status "stub"` and `completion 5` (only `verify_value` exists as a trivial wrapper). -7. Update `updated` date to `"2026-02-12"`. - -**Verification:** -```bash -# Check that STATE.scm is valid Scheme and contains updated values: -grep 'overall-completion 65' /var$REPOS_DIR/Axiology.jl/.machine_readable/STATE.scm -grep 'phase "alpha"' /var$REPOS_DIR/Axiology.jl/.machine_readable/STATE.scm -echo "TASK 6 PASSED" -``` - ---- - -## TASK 7: Fix README.adoc false claims (MEDIUM) - -**Files:** `/var$REPOS_DIR/Axiology.jl/README.adoc` - -**Problem:** Multiple false claims and advertised-but-nonexistent API: - -- Line 10: Claims "Production Ready" -- should say "Alpha" after Tasks 1-4 -- Line 174: Documents `select_solution(solutions, preference)` -- this function DOES NOT EXIST -- Line 179: Documents `echidna_verify(value, system)` -- this function DOES NOT EXIST -- Line 182: Documents `fairlearn_constraint(value)` -- this function DOES NOT EXIST -- Line 185: Documents `flux_loss(value)` -- this function DOES NOT EXIST -- Lines 86-93: Example uses `train(algorithm, data, constraints=[fairness])` -- no such function -- Lines 104-113: Example uses `select_solution(solutions, preference=:balanced)` -- no such function -- Lines 119-138: Example uses `prove`, `Verified`, `verification.counterexample` -- none exist -- Lines 238-241: Development status checkboxes are wrong (Pareto IS implemented, marked unchecked) -- Lines 269-274: Claims dual MIT/PMPL license but project actually uses MPL-2.0 only - -**What to do:** -1. Change line 10 status to: `> **Status**: Alpha - Core value system functional, integration APIs planned` -2. Remove the `=== Integration APIs` section (lines 177-186) entirely. These functions do not exist. -3. Fix the Usage Examples to use actual API signatures that exist in the codebase. Replace the - fake `train()`, `select_solution()`, `prove()`, `Verified` examples with real working examples - using `satisfy`, `maximize`, `value_score`, `weighted_score`, `pareto_frontier`. -4. Fix the Development Status checkboxes: - - Check `[x] Multi-objective optimization` (Pareto frontier IS implemented) - - Keep `[ ] Formal verification integration with ECHIDNA` unchecked - - Keep `[ ] ML fairness library integration` unchecked - - Keep `[ ] Comprehensive documentation` unchecked -5. Fix the License section: Remove mention of MIT. The license is MPL-2.0 per the - LICENSE file and SPDX headers. -6. Update the ECHIDNA Integration section to clearly state it is PLANNED, not implemented. - -**Verification:** -```bash -# Verify no mention of nonexistent functions: -! grep -q 'select_solution' /var$REPOS_DIR/Axiology.jl/README.adoc -! grep -q 'echidna_verify' /var$REPOS_DIR/Axiology.jl/README.adoc -! grep -q 'fairlearn_constraint' /var$REPOS_DIR/Axiology.jl/README.adoc -! grep -q 'flux_loss' /var$REPOS_DIR/Axiology.jl/README.adoc -! grep -q 'Production Ready' /var$REPOS_DIR/Axiology.jl/README.adoc -echo "TASK 7 PASSED" -``` - ---- - -## TASK 8: Fix ROADMAP.adoc incorrect checkboxes (LOW) - -**Files:** `/var$REPOS_DIR/Axiology.jl/ROADMAP.adoc` - -**Problem:** Line 14 marks "Multi-objective optimization (Pareto frontiers)" as unchecked `[ ]`, -but `pareto_frontier`, `dominated`, `value_score`, `weighted_score`, and `normalize_scores` are -all implemented in `optimization.jl`. Lines 61-65 mark all fairness metrics as unchecked, but -`demographic_parity`, `equalized_odds`, `equal_opportunity`, `disparate_impact`, and -`individual_fairness` are all implemented in `fairness.jl`. - -**What to do:** -1. Line 14: Change `* [ ] Multi-objective optimization (Pareto frontiers)` to `* [x] Multi-objective optimization (Pareto frontiers)` -2. Lines 61-65: Check all five fairness metrics that are implemented: - - `* [x] Demographic parity (group fairness)` - - `* [x] Equalized odds (conditional fairness)` - - `* [ ] Predictive parity (calibration)` (keep unchecked, not implemented) - - `* [x] Individual fairness (Lipschitz continuity)` - - `* [ ] Counterfactual fairness (causal)` (keep unchecked, not implemented) -3. Under v0.2.0, check "Implement Pareto frontier algorithm for value tradeoffs". - -**Verification:** -```bash -grep '\[x\] Multi-objective optimization' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc -grep '\[x\] Demographic parity' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc -grep '\[x\] Equalized odds' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc -grep '\[x\] Individual fairness' /var$REPOS_DIR/Axiology.jl/ROADMAP.adoc -echo "TASK 8 PASSED" -``` - ---- - -## TASK 9: Implement real verify_value logic (MEDIUM) - -**Files:** `/var$REPOS_DIR/Axiology.jl/src/welfare.jl` (lines 730-733) - -**Problem:** `verify_value(value::Value, proof::Dict)::Bool` is a trivial stub that only reads -`proof[:verified]`. It does no actual verification. The docstring (lines 694-729) describes -checking for a `:prover` key and `:details` key, but the function ignores them entirely. - -**What to do:** -1. Expand `verify_value` to: - - Require `proof[:verified]` to be a `Bool` (error if missing or wrong type) - - If `value isa Safety` and `value.critical == true`, also require that `proof` contains - a `:prover` key (it should be verified by a named prover, not just asserted) - - Log/return the prover name and details if present - - Return `proof[:verified]` as before for the boolean result, but with the added validation -2. Add a `verify_value` method specifically for `Safety` that enforces critical safety proofs - must have a `:prover` field. -3. Add tests in `test/runtests.jl` for the new validation behavior: - - Test that a critical Safety value with no `:prover` in proof returns `false` or errors - - Test that a non-critical Safety value without `:prover` still works - - Test that other Value types work as before - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -using Axiology - -# Non-critical safety: no prover needed -s_noncrit = Safety(invariant="test", critical=false) -@assert verify_value(s_noncrit, Dict(:verified => true)) == true - -# Critical safety: prover should be required -s_crit = Safety(invariant="test", critical=true) -@assert verify_value(s_crit, Dict(:verified => true, :prover => :Lean)) == true - -# Other value types still work: -f = Fairness(metric=:demographic_parity, threshold=0.05) -@assert verify_value(f, Dict(:verified => true)) == true -@assert verify_value(f, Dict(:verified => false)) == false - -println("TASK 9 PASSED") -``` - ---- - -## TASK 10: Improve maximize(Efficiency) for pareto/kaldor_hicks (LOW) - -**Files:** `/var$REPOS_DIR/Axiology.jl/src/welfare.jl` (lines 560-574) - -**Problem:** `maximize(value::Efficiency, initial_state::Dict)` returns a hardcoded `1.0` for -`:pareto` and `:kaldor_hicks` metrics (line 570). The docstring on line 540 explicitly -acknowledges this is a "placeholder". For `:pareto`, it should return `1.0` if -`state[:is_pareto_efficient]` is `true` and `0.0` otherwise. For `:kaldor_hicks`, it should -return `state[:net_gain]`. - -**What to do:** -1. For `:pareto` metric: read `initial_state[:is_pareto_efficient]` and return `1.0` if true, `0.0` if false. Error if key is missing. -2. For `:kaldor_hicks` metric: read `initial_state[:net_gain]` and return it directly. Error if key is missing. -3. Update the docstring to remove the "placeholder" language. -4. Add tests: - - `maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => true))` returns `1.0` - - `maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => false))` returns `0.0` - - `maximize(Efficiency(metric=:kaldor_hicks, target=100.0), Dict(:net_gain => 150.0))` returns `150.0` - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -using Axiology - -@assert maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => true)) == 1.0 -@assert maximize(Efficiency(metric=:pareto), Dict(:is_pareto_efficient => false)) == 0.0 -@assert maximize(Efficiency(metric=:kaldor_hicks, target=100.0), Dict(:net_gain => 150.0)) == 150.0 -@assert maximize(Efficiency(metric=:computation_time), Dict(:computation_time => 0.5)) == -0.5 - -println("TASK 10 PASSED") -``` - ---- - -## TASK 11: Add equal_opportunity to test suite (LOW) - -**Files:** `/var$REPOS_DIR/Axiology.jl/test/runtests.jl` - -**Problem:** The test suite tests `demographic_parity`, `disparate_impact`, and `individual_fairness` -(via `satisfy`), but never directly tests `equalized_odds` or `equal_opportunity` metric -functions. `individual_fairness` is also only tested indirectly through `satisfy`. Add direct -tests for completeness. - -**What to do:** -1. Add a `@testset "Equalized Odds"` block inside "Fairness Metrics" that: - - Tests perfect equalized odds (same TPR and FPR across groups) returns 0.0 - - Tests a case with known unequal TPR/FPR and verifies disparity > 0.0 -2. Add a `@testset "Equal Opportunity"` block inside "Fairness Metrics" that: - - Tests perfect equal opportunity (same TPR across groups) returns 0.0 - - Tests a case with unequal TPR -3. Add a `@testset "Individual Fairness"` block inside "Fairness Metrics" that: - - Tests with a similarity matrix where similar individuals get similar predictions (returns ~0.0) - - Tests with a similarity matrix where similar individuals get different predictions (returns > 0) - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -Pkg.test() -# Verify the new testsets appear in output and pass -println("TASK 11 PASSED") -``` - ---- - -## TASK 12: Add edge case tests (LOW) - -**Files:** `/var$REPOS_DIR/Axiology.jl/test/runtests.jl` - -**Problem:** No tests for edge cases or error conditions: -- Empty vectors -- Single-group protected attributes -- Zero-weight values in weighted_score -- Invalid metric symbols (should error) -- Missing state keys (should error) - -**What to do:** -1. Add a `@testset "Edge Cases"` block with subtests for: - - `demographic_parity` with single group returns 0.0 - - `disparate_impact` with single group returns 1.0 - - `utilitarian_welfare` with empty vector returns 0.0 - - `rawlsian_welfare` with empty vector throws error - - `egalitarian_welfare` with single element returns 0.0 - - `normalize_scores` with identical scores returns all 1.0 - - `normalize_scores` with empty vector throws ArgumentError - - `Fairness` constructor with invalid metric throws AssertionError - - `Safety` constructor with empty invariant throws AssertionError - - `weighted_score` with all zero weights returns 0.0 - - `satisfy(Fairness, Dict())` without `:predictions` throws error - -**Verification:** -```julia -cd("/var$REPOS_DIR/Axiology.jl") -using Pkg; Pkg.activate(".") -Pkg.test() -println("TASK 12 PASSED") -``` - ---- - -## FINAL VERIFICATION - -After all tasks are complete, run the following sequence: - -```bash -cd /var$REPOS_DIR/Axiology.jl - -# 1. Module loads without errors -julia --project=. -e 'using Axiology; println("Module loaded successfully")' - -# 2. Full test suite passes -julia --project=. -e 'using Pkg; Pkg.test()' - -# 3. No orphan code blocks remain (no bare @assert at top level outside functions) -julia --project=. -e ' - for f in ["src/fairness.jl", "src/welfare.jl", "src/optimization.jl"] - content = read(f, String) - # Count function declarations vs end statements - funcs = count(r"^function ", content) - println("$f: $funcs function declarations") - end - println("Source structure check passed") -' - -# 4. No remaining stubs or placeholders -grep -rn "placeholder\|not implemented\|TODO\|FIXME\|HACK\|XXX\|STUB" src/ || echo "No stubs found" - -# 5. No AGPL headers (wrong license) -grep -rn "AGPL" . --include="*.jl" --include="*.res" --include="*.json" || echo "No AGPL found" - -# 6. Example runs -julia --project=. examples/basic_usage.jl - -# 7. STATE.scm is honest -grep 'overall-completion 65' .machine_readable/STATE.scm && echo "STATE.scm is honest" - -echo "ALL VERIFICATION PASSED" -``` diff --git a/packages/Axiology.jl/TOPOLOGY.md b/packages/Axiology.jl/TOPOLOGY.adoc similarity index 88% rename from packages/Axiology.jl/TOPOLOGY.md rename to packages/Axiology.jl/TOPOLOGY.adoc index 6c2639716..d3cee45ec 100644 --- a/packages/Axiology.jl/TOPOLOGY.md +++ b/packages/Axiology.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Axiology.jl — Project Topology -# Axiology.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE LOGIC @@ -65,26 +61,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~65% Core value system functional -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Type Definitions ──────► Satisfy Check ──────► Optimization (Maximize) │ ┌─────────┴─────────┐ ▼ ▼ ML Integration Formal Verification -``` +.... -## 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/packages/Axiology.jl/docs/theory/AXIOLOGY_FOUNDATIONS.adoc b/packages/Axiology.jl/docs/theory/AXIOLOGY_FOUNDATIONS.adoc new file mode 100644 index 000000000..aa361b0dc --- /dev/null +++ b/packages/Axiology.jl/docs/theory/AXIOLOGY_FOUNDATIONS.adoc @@ -0,0 +1,320 @@ +== Axiology: Theoretical Foundations + +=== Etymology and Cross-Linguistic Analysis + +==== Ancient Greek Origins + +*Axiology* derives from two Ancient Greek roots: - *ἀξία* (_axiā_) - +"`value, worth`" (from ἄξιος _axios_ - "`worthy`") - *-λογία* (_-logia_) +- "`study of, discourse`" (from λόγος _logos_) + +The term was coined in *1902* by French philosopher *Paul Lapie* and +independently by *Eduard von Hartmann* (German: _Axiologie_) to describe +the systematic philosophical study of value. + +==== Cross-Linguistic Terminology + +[cols=",,",options="header",] +|=== +|Language |Term |Literal Meaning +|*Greek* |Αξιολογία (_Axiología_) |Value-study (original) +|*Latin* |_Scientia valoris_ |Science of value +|*German* |_Axiologie_ / _Wertlehre_ |Value-theory +|*French* |_Axiologie_ / _Théorie de la valeur_ |Value-theory +|*Russian* |Аксиология (_Aksiologiya_) |Axiology +|*Japanese* |価値論 (_Kachironnot_) |Value-theory +|*Chinese* |价值论 (_Jiàzhílùn_) |Value-theory +|*Arabic* |علم القيم (_’Ilm al-Qiyam_) |Science of values +|*Sanskrit* |मूल्य-विज्ञान (_Mūlya-vijñāna_) |Value-knowledge +|=== + +''''' + +=== Historical Development + +==== Ancient Antecedents (Before "`Axiology`") + +===== Greek Philosophy (5th-3rd century BCE) + +*Socrates* (470-399 BCE): - Questioned conventional values ("`What is +the good?`") - Introduced value-inquiry as central to philosophy - +_"`The unexamined life is not worth living`"_ - value of self-knowledge + +*Plato* (428-348 BCE): - _Theory of Forms_: Absolute values (Good, +Beautiful, Just) exist independently - _Republic_: Hierarchy of values +(wisdom > courage > temperance > justice) - _Form of the Good_ - +ultimate value, source of all other values + +*Aristotle* (384-322 BCE): - _Nicomachean Ethics_: Virtue as excellence +(_aretē_) - *Intrinsic vs. Instrumental Value*: Distinction between ends +and means - _Eudaimonia_ (flourishing) as highest human value + +===== Medieval Philosophy (4th-14th century CE) + +*Augustine of Hippo* (354-430 CE): - Christian values hierarchy: God +(highest) → soul → body → material goods - _De Doctrina Christiana_: +Things to be "`used`" (_uti_) vs. "`enjoyed`" (_frui_) + +*Thomas Aquinas* (1225-1274): - Natural Law theory: Universal values +grounded in human nature - Hierarchy of goods: Divine → intellectual → +physical + +===== Early Modern (16th-18th century) + +*David Hume* (1711-1776): - Is-Ought Problem: Can’t derive value +judgments from factual statements - Sentiment theory of value: Values +grounded in human sentiments + +*Immanuel Kant* (1724-1804): - *Categorical Imperative*: Persons have +absolute value (ends-in-themselves) - Moral worth independent of +consequences - Foundation for deontological ethics + +''''' + +==== Formal Axiology (1900-Present) + +===== Founding Era (1900-1920) + +*Eduard von Hartmann* (1842-1906): - _Grundriss der Axiologie_ (1909) - +Systematized value theory as distinct philosophical discipline + +*Paul Lapie* (1869-1927): - _Logique de la volonté_ (1902) - Coined +"`axiologie`" independently + +*Alexius Meinong* (1853-1920): - _Zur Grundlegung der allgemeinen +Werttheorie_ (1923) - Value as objective property of objects - +Value-feelings (_Wertgefühle_) vs. value-properties + +===== Phenomenological Axiology (1913-1928) + +*Max Scheler* (1874-1928): - _Der Formalismus in der Ethik_ (1913-1916) +- Values as _a priori_ intuited essences - *Hierarchy of Values* (low → +high): 1. Pleasant/unpleasant (sensory) 2. Noble/vulgar (vital) 3. +Spiritual values (intellectual, aesthetic, legal) 4. Holy/unholy +(religious) - Values known through emotional intuition (_Wertfühlen_) + +*Nicolai Hartmann* (1882-1950): - _Ethik_ (1926) - Objective value +realism: Values exist independently of subjects - Strength vs. Height: +Strong values (e.g., justice) vs. high values (e.g., love) + +===== Formal Axiology (1967-Present) + +*Robert S. Hartman* (1910-1973): - _The Structure of Value_ (1967) - +*Mathematical axiology*: Value as degree of concept-fulfillment - Three +dimensions of value: 1. *Systemic* (_S_): Conceptual perfection +(mathematics, logic) 2. *Extrinsic* (_E_): Practical utility (tools, +instruments) 3. *Intrinsic* (_I_): Unique worth (persons, art, +experiences) - Axiomatic value theory (18 axioms) + +''''' + +=== Contemporary Schools + +==== Value Realism + +*Position*: Values exist objectively, independent of human minds + +*Representatives*: - *G.E. Moore* (1873-1958): "`Good`" as non-natural +property - *Nicolai Hartmann*: Values as ideal essences - *David Brink*: +Moral realism, values as objective features + +*Arguments*: - Convergence: Cultures converge on basic values (e.g., +harm is bad) - Moral phenomenology: Values _seem_ objective - Best +explanation: Objectivity explains disagreement (we’re all trying to +discover truth) + +==== Value Subjectivism + +*Position*: Values are projections of human preferences/emotions + +*Representatives*: - *David Hume*: Sentimentalism - *A.J. Ayer*: +Emotivism - value statements are expressions of emotion - *Simon +Blackburn*: Quasi-realism + +*Arguments*: - Metaphysical parsimony: No need for strange "`value +properties`" - Diversity: Radical value disagreements across cultures - +Motivation: Values necessarily motivate → must be grounded in desires + +==== Value Constructivism + +*Position*: Values are constructed through social/rational procedures + +*Representatives*: - *John Rawls*: Justice as fair agreement behind +"`veil of ignorance`" - *Christine Korsgaard*: Kantian constructivism - +*Jürgen Habermas*: Discourse ethics + +*Arguments*: - Objectivity without metaphysics: Intersubjective +agreement - Respect for autonomy: Values we give ourselves - Democratic +legitimacy: Values emerge from dialogue + +''''' + +=== Axiology in Economics + +==== Classical Economics (18th-19th century) + +*Adam Smith* (1723-1790): - _The Wealth of Nations_ (1776) - +*Diamond-Water Paradox*: Diamonds (less useful) more valuable than water +- Use-value vs. exchange-value distinction + +*David Ricardo* (1772-1823): - Labor theory of value: Value derives from +labor input + +*Karl Marx* (1818-1883): - _Das Kapital_ (1867) - Exchange-value +vs. use-value - Critique: Capitalism treats labor as commodity + +==== Marginalist Revolution (1870s) + +*William Stanley Jevons*, *Carl Menger*, *Léon Walras*: - *Marginal +utility theory*: Value = utility of last unit consumed - Solved +diamond-water paradox: Water’s marginal utility is low (abundant) + +==== Welfare Economics (1900-Present) + +*Vilfredo Pareto* (1848-1923): - *Pareto efficiency*: No one can be made +better off without someone worse off - Foundation for modern welfare +analysis + +*John Hicks* & *Nicholas Kaldor* (1939): - *Kaldor-Hicks criterion*: +Compensation principle for policy evaluation + +*Amartya Sen* (1933-Present): - Nobel Prize 1998 - _Collective Choice +and Social Welfare_ (1970) - *Capability approach*: Value = capabilities +(freedoms) not just utility - Critique of utilitarianism: Ignores +distribution, adaptive preferences + +''''' + +=== Axiology in Computer Science & AI + +==== Decision Theory + +*John von Neumann* & *Oskar Morgenstern* (1944): - _Theory of Games and +Economic Behavior_ - *Expected utility theory*: Rational choice under +uncertainty - Axioms: Completeness, transitivity, continuity, +independence + +==== Preference Learning + +*Machine learning of value functions*: - Inverse reinforcement learning +(Ng & Russell, 2000) - Learning from human feedback (RLHF) - Preference +elicitation algorithms + +==== AI Alignment & Value Loading + +*Stuart Russell* (2019): - _Human Compatible: AI and the Problem of +Control_ - *Value alignment problem*: How to ensure AI optimizes human +values - Uncertainty about human values → provably beneficial AI + +*Nick Bostrom* (2014): - _Superintelligence_ - *Instrumental +convergence*: AIs converge on instrumental goals regardless of terminal +values - Paperclip maximizer thought experiment + +''''' + +=== Formal Representations + +==== Preference Relations + +Given set latexmath:[X] of alternatives, preference relation +latexmath:[\succsim] ("`at least as good as`"): + +*Properties*: - *Completeness*: +latexmath:[\forall x,y \in X: x \succsim y \lor y \succsim x] - +*Transitivity*: +latexmath:[x \succsim y \land y \succsim z \Rightarrow x \succsim z] - +*Reflexivity*: latexmath:[x \succsim x] + +*Strict preference*: +latexmath:[x \succ y \iff x \succsim y \land \neg(y \succsim x)] + +*Indifference*: +latexmath:[x \sim y \iff x \succsim y \land y \succsim x] + +==== Utility Functions + +*Representation theorem* (Debreu, 1954): If latexmath:[\succsim] is +complete, transitive, continuous, then latexmath:[\exists] utility +function latexmath:[u: X \to \mathbb{R}] such that: + +[latexmath] +++++ +x \succsim y \iff u(x) \geq u(y) +++++ + +*Ordinal utility*: Only order matters, not magnitude + +*Cardinal utility*: Magnitude differences are meaningful + +==== Social Welfare Functions + +*Aggregation*: latexmath:[n] individuals, utilities +latexmath:[u_1, \ldots, u_n] + +*Utilitarian* (Bentham): + +[latexmath] +++++ +W = \sum_{i=1}^n u_i +++++ + +*Rawlsian* (maximin): + +[latexmath] +++++ +W = \min_i u_i +++++ + +*Weighted sum*: + +[latexmath] +++++ +W = \sum_{i=1}^n w_i u_i, \quad \sum_i w_i = 1 +++++ + +*Nash* (product): + +[latexmath] +++++ +W = \prod_{i=1}^n u_i +++++ + +''''' + +=== Connections to This Library + +This implementation operationalizes: + +[arabic] +. *Classical axiology* → Type system (Fairness, Welfare, etc.) +. *Formal axiology* → Measurable value functions +. *Welfare economics* → Social welfare functions +. *AI alignment* → Verification of value satisfaction +. *Multi-criteria decision* → Pareto frontier analysis + +''''' + +=== References + +==== Primary Sources + +* Aristotle. (350 BCE). _Nicomachean Ethics_. +* Kant, I. (1785). _Groundwork of the Metaphysics of Morals_. +* Scheler, M. (1916). _Formalism in Ethics and Non-Formal Ethics of +Values_. +* Hartman, R.S. (1967). _The Structure of Value_. + +==== Contemporary + +* Sen, A. (1970). _Collective Choice and Social Welfare_. +* Rawls, J. (1971). _A Theory of Justice_. +* Bostrom, N. (2014). _Superintelligence_. +* Russell, S. (2019). _Human Compatible_. + +==== Technical + +* von Neumann, J., & Morgenstern, O. (1944). _Theory of Games and +Economic Behavior_. +* Arrow, K. (1951). _Social Choice and Individual Values_. +* Ng, A.Y., & Russell, S. (2000). "`Algorithms for Inverse Reinforcement +Learning`". diff --git a/packages/Axiology.jl/docs/theory/AXIOLOGY_FOUNDATIONS.md b/packages/Axiology.jl/docs/theory/AXIOLOGY_FOUNDATIONS.md deleted file mode 100644 index 3d2245df8..000000000 --- a/packages/Axiology.jl/docs/theory/AXIOLOGY_FOUNDATIONS.md +++ /dev/null @@ -1,312 +0,0 @@ -# Axiology: Theoretical Foundations - -## Etymology and Cross-Linguistic Analysis - -### Ancient Greek Origins - -**Axiology** derives from two Ancient Greek roots: -- **ἀξία** (*axiā*) - "value, worth" (from ἄξιος *axios* - "worthy") -- **-λογία** (*-logia*) - "study of, discourse" (from λόγος *logos*) - -The term was coined in **1902** by French philosopher **Paul Lapie** and independently by **Eduard von Hartmann** (German: *Axiologie*) to describe the systematic philosophical study of value. - -### Cross-Linguistic Terminology - -| Language | Term | Literal Meaning | -|----------|------|-----------------| -| **Greek** | Αξιολογία (*Axiología*) | Value-study (original) | -| **Latin** | *Scientia valoris* | Science of value | -| **German** | *Axiologie* / *Wertlehre* | Value-theory | -| **French** | *Axiologie* / *Théorie de la valeur* | Value-theory | -| **Russian** | Аксиология (*Aksiologiya*) | Axiology | -| **Japanese** | 価値論 (*Kachironnot*) | Value-theory | -| **Chinese** | 价值论 (*Jiàzhílùn*) | Value-theory | -| **Arabic** | علم القيم (*'Ilm al-Qiyam*) | Science of values | -| **Sanskrit** | मूल्य-विज्ञान (*Mūlya-vijñāna*) | Value-knowledge | - ---- - -## Historical Development - -### Ancient Antecedents (Before "Axiology") - -#### Greek Philosophy (5th-3rd century BCE) - -**Socrates** (470-399 BCE): -- Questioned conventional values ("What is the good?") -- Introduced value-inquiry as central to philosophy -- *"The unexamined life is not worth living"* - value of self-knowledge - -**Plato** (428-348 BCE): -- *Theory of Forms*: Absolute values (Good, Beautiful, Just) exist independently -- *Republic*: Hierarchy of values (wisdom > courage > temperance > justice) -- *Form of the Good* - ultimate value, source of all other values - -**Aristotle** (384-322 BCE): -- *Nicomachean Ethics*: Virtue as excellence (*aretē*) -- **Intrinsic vs. Instrumental Value**: Distinction between ends and means -- *Eudaimonia* (flourishing) as highest human value - -#### Medieval Philosophy (4th-14th century CE) - -**Augustine of Hippo** (354-430 CE): -- Christian values hierarchy: God (highest) → soul → body → material goods -- *De Doctrina Christiana*: Things to be "used" (*uti*) vs. "enjoyed" (*frui*) - -**Thomas Aquinas** (1225-1274): -- Natural Law theory: Universal values grounded in human nature -- Hierarchy of goods: Divine → intellectual → physical - -#### Early Modern (16th-18th century) - -**David Hume** (1711-1776): -- Is-Ought Problem: Can't derive value judgments from factual statements -- Sentiment theory of value: Values grounded in human sentiments - -**Immanuel Kant** (1724-1804): -- **Categorical Imperative**: Persons have absolute value (ends-in-themselves) -- Moral worth independent of consequences -- Foundation for deontological ethics - ---- - -### Formal Axiology (1900-Present) - -#### Founding Era (1900-1920) - -**Eduard von Hartmann** (1842-1906): -- *Grundriss der Axiologie* (1909) -- Systematized value theory as distinct philosophical discipline - -**Paul Lapie** (1869-1927): -- *Logique de la volonté* (1902) -- Coined "axiologie" independently - -**Alexius Meinong** (1853-1920): -- *Zur Grundlegung der allgemeinen Werttheorie* (1923) -- Value as objective property of objects -- Value-feelings (*Wertgefühle*) vs. value-properties - -#### Phenomenological Axiology (1913-1928) - -**Max Scheler** (1874-1928): -- *Der Formalismus in der Ethik* (1913-1916) -- Values as *a priori* intuited essences -- **Hierarchy of Values** (low → high): - 1. Pleasant/unpleasant (sensory) - 2. Noble/vulgar (vital) - 3. Spiritual values (intellectual, aesthetic, legal) - 4. Holy/unholy (religious) -- Values known through emotional intuition (*Wertfühlen*) - -**Nicolai Hartmann** (1882-1950): -- *Ethik* (1926) -- Objective value realism: Values exist independently of subjects -- Strength vs. Height: Strong values (e.g., justice) vs. high values (e.g., love) - -#### Formal Axiology (1967-Present) - -**Robert S. Hartman** (1910-1973): -- *The Structure of Value* (1967) -- **Mathematical axiology**: Value as degree of concept-fulfillment -- Three dimensions of value: - 1. **Systemic** (*S*): Conceptual perfection (mathematics, logic) - 2. **Extrinsic** (*E*): Practical utility (tools, instruments) - 3. **Intrinsic** (*I*): Unique worth (persons, art, experiences) -- Axiomatic value theory (18 axioms) - ---- - -## Contemporary Schools - -### Value Realism - -**Position**: Values exist objectively, independent of human minds - -**Representatives**: -- **G.E. Moore** (1873-1958): "Good" as non-natural property -- **Nicolai Hartmann**: Values as ideal essences -- **David Brink**: Moral realism, values as objective features - -**Arguments**: -- Convergence: Cultures converge on basic values (e.g., harm is bad) -- Moral phenomenology: Values *seem* objective -- Best explanation: Objectivity explains disagreement (we're all trying to discover truth) - -### Value Subjectivism - -**Position**: Values are projections of human preferences/emotions - -**Representatives**: -- **David Hume**: Sentimentalism -- **A.J. Ayer**: Emotivism - value statements are expressions of emotion -- **Simon Blackburn**: Quasi-realism - -**Arguments**: -- Metaphysical parsimony: No need for strange "value properties" -- Diversity: Radical value disagreements across cultures -- Motivation: Values necessarily motivate → must be grounded in desires - -### Value Constructivism - -**Position**: Values are constructed through social/rational procedures - -**Representatives**: -- **John Rawls**: Justice as fair agreement behind "veil of ignorance" -- **Christine Korsgaard**: Kantian constructivism -- **Jürgen Habermas**: Discourse ethics - -**Arguments**: -- Objectivity without metaphysics: Intersubjective agreement -- Respect for autonomy: Values we give ourselves -- Democratic legitimacy: Values emerge from dialogue - ---- - -## Axiology in Economics - -### Classical Economics (18th-19th century) - -**Adam Smith** (1723-1790): -- *The Wealth of Nations* (1776) -- **Diamond-Water Paradox**: Diamonds (less useful) more valuable than water -- Use-value vs. exchange-value distinction - -**David Ricardo** (1772-1823): -- Labor theory of value: Value derives from labor input - -**Karl Marx** (1818-1883): -- *Das Kapital* (1867) -- Exchange-value vs. use-value -- Critique: Capitalism treats labor as commodity - -### Marginalist Revolution (1870s) - -**William Stanley Jevons**, **Carl Menger**, **Léon Walras**: -- **Marginal utility theory**: Value = utility of last unit consumed -- Solved diamond-water paradox: Water's marginal utility is low (abundant) - -### Welfare Economics (1900-Present) - -**Vilfredo Pareto** (1848-1923): -- **Pareto efficiency**: No one can be made better off without someone worse off -- Foundation for modern welfare analysis - -**John Hicks** & **Nicholas Kaldor** (1939): -- **Kaldor-Hicks criterion**: Compensation principle for policy evaluation - -**Amartya Sen** (1933-Present): -- Nobel Prize 1998 -- *Collective Choice and Social Welfare* (1970) -- **Capability approach**: Value = capabilities (freedoms) not just utility -- Critique of utilitarianism: Ignores distribution, adaptive preferences - ---- - -## Axiology in Computer Science & AI - -### Decision Theory - -**John von Neumann** & **Oskar Morgenstern** (1944): -- *Theory of Games and Economic Behavior* -- **Expected utility theory**: Rational choice under uncertainty -- Axioms: Completeness, transitivity, continuity, independence - -### Preference Learning - -**Machine learning of value functions**: -- Inverse reinforcement learning (Ng & Russell, 2000) -- Learning from human feedback (RLHF) -- Preference elicitation algorithms - -### AI Alignment & Value Loading - -**Stuart Russell** (2019): -- *Human Compatible: AI and the Problem of Control* -- **Value alignment problem**: How to ensure AI optimizes human values -- Uncertainty about human values → provably beneficial AI - -**Nick Bostrom** (2014): -- *Superintelligence* -- **Instrumental convergence**: AIs converge on instrumental goals regardless of terminal values -- Paperclip maximizer thought experiment - ---- - -## Formal Representations - -### Preference Relations - -Given set $X$ of alternatives, preference relation $\succsim$ ("at least as good as"): - -**Properties**: -- **Completeness**: $\forall x,y \in X: x \succsim y \lor y \succsim x$ -- **Transitivity**: $x \succsim y \land y \succsim z \Rightarrow x \succsim z$ -- **Reflexivity**: $x \succsim x$ - -**Strict preference**: $x \succ y \iff x \succsim y \land \neg(y \succsim x)$ - -**Indifference**: $x \sim y \iff x \succsim y \land y \succsim x$ - -### Utility Functions - -**Representation theorem** (Debreu, 1954): -If $\succsim$ is complete, transitive, continuous, then $\exists$ utility function $u: X \to \mathbb{R}$ such that: - -$$x \succsim y \iff u(x) \geq u(y)$$ - -**Ordinal utility**: Only order matters, not magnitude - -**Cardinal utility**: Magnitude differences are meaningful - -### Social Welfare Functions - -**Aggregation**: $n$ individuals, utilities $u_1, \ldots, u_n$ - -**Utilitarian** (Bentham): -$$W = \sum_{i=1}^n u_i$$ - -**Rawlsian** (maximin): -$$W = \min_i u_i$$ - -**Weighted sum**: -$$W = \sum_{i=1}^n w_i u_i, \quad \sum_i w_i = 1$$ - -**Nash** (product): -$$W = \prod_{i=1}^n u_i$$ - ---- - -## Connections to This Library - -This implementation operationalizes: - -1. **Classical axiology** → Type system (Fairness, Welfare, etc.) -2. **Formal axiology** → Measurable value functions -3. **Welfare economics** → Social welfare functions -4. **AI alignment** → Verification of value satisfaction -5. **Multi-criteria decision** → Pareto frontier analysis - ---- - -## References - -### Primary Sources - -- Aristotle. (350 BCE). *Nicomachean Ethics*. -- Kant, I. (1785). *Groundwork of the Metaphysics of Morals*. -- Scheler, M. (1916). *Formalism in Ethics and Non-Formal Ethics of Values*. -- Hartman, R.S. (1967). *The Structure of Value*. - -### Contemporary - -- Sen, A. (1970). *Collective Choice and Social Welfare*. -- Rawls, J. (1971). *A Theory of Justice*. -- Bostrom, N. (2014). *Superintelligence*. -- Russell, S. (2019). *Human Compatible*. - -### Technical - -- von Neumann, J., & Morgenstern, O. (1944). *Theory of Games and Economic Behavior*. -- Arrow, K. (1951). *Social Choice and Individual Values*. -- Ng, A.Y., & Russell, S. (2000). "Algorithms for Inverse Reinforcement Learning". diff --git a/packages/Axiology.jl/docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc b/packages/Axiology.jl/docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc new file mode 100644 index 000000000..6503c33f2 --- /dev/null +++ b/packages/Axiology.jl/docs/theory/CROSS_CULTURAL_PERSPECTIVES.adoc @@ -0,0 +1,435 @@ +== Cross-Cultural Perspectives on Value Theory + +=== Beyond Western Philosophy + +==== Indian Philosophy + +===== Vedic Period (1500-500 BCE) + +*Ṛta* (ऋत) - Cosmic Order/Truth: - Pre-axial concept of value as cosmic +harmony - Foundation for later dharma concept - Value inherent in +natural order + +*Upanishads* (800-200 BCE): - *Brahman* as ultimate reality and value - +*Ātman* (self) identified with Brahman - Value hierarchy: Knowledge > +ritual > material + +===== Classical Hindu Philosophy + +*Puruṣārthas* (Four Aims of Life): 1. *Dharma* (धर्म) - Righteousness, +moral law 2. *Artha* (अर्थ) - Prosperity, economic value 3. *Kāma* (काम) +- Pleasure, aesthetic/emotional value 4. *Mokṣa* (मोक्ष) - Liberation +(highest value) + +*Bhagavad Gītā* (circa 200 BCE-200 CE): - *Svadharma*: Value relative to +one’s station (_varṇa_) - *Niṣkāma karma*: Action without attachment to +fruits - Three paths (_mārgas_): Knowledge, devotion, action + +===== Buddhist Axiology + +*Four Noble Truths* (Catvāri Ārya Satyāni): 1. _Duḥkha_ - +Suffering/dissatisfaction (disvalue) 2. _Samudaya_ - Origin of suffering +(craving/_tṛṣṇā_) 3. _Nirodha_ - Cessation (value achieved through +elimination) 4. _Mārga_ - Path to cessation + +*Middle Way* (_Madhyamā-Pratipad_): - Rejection of extremes (asceticism +vs. hedonism) - Value as balance, not maximization + +*Dependent Origination* (_Pratītyasamutpāda_): - Values lack inherent +existence - Contextual, relational value theory + +*Mahāyāna*: Bodhisattva ideal - compassion as supreme value + +===== Jain Ethics + +*Ahiṃsā* (अहिंसा) - Non-violence: - Primary value, more extreme than +Hindu/Buddhist - Extends to thoughts, words, deeds + +*Anekāntavāda* - Many-sidedness: - No single perspective captures +complete truth - Value pluralism as metaphysical necessity + +*Syādvāda* - Conditional predication: - Seven-fold judgment +(_Saptabhaṅgī_) - Truth and value are contextual, multi-aspected + +''''' + +==== Chinese Philosophy + +===== Confucianism (儒家) + +*Confucius* (孔子, 551-479 BCE): + +*Five Constants* (_Wǔcháng_ 五常): 1. *Rén* (仁) - Benevolence, humanity +2. *Yì* (义) - Righteousness, justice 3. *Lǐ* (礼) - Ritual propriety, +etiquette 4. *Zhì* (智) - Wisdom, knowledge 5. *Xìn* (信) - Integrity, +trustworthiness + +*Five Relationships* (_Wǔlún_ 五伦): - Ruler-subject, father-son, +husband-wife, elder-younger, friend-friend - Value as relational +harmony, not individual rights + +*Mencius* (孟子, 372-289 BCE): - Human nature is inherently good (_xìng +shàn_ 性善) - Four sprouts: Compassion, shame, courtesy, moral judgment +- Value cultivation through education + +*Xunzi* (荀子, 313-238 BCE): - Human nature is inherently selfish - +Value created through ritual and education - Constructivist axiology + +===== Daoism (道家) + +*Laozi* (老子, 6th century BCE?): + +*Dào* (道) - Way/Path: - Ultimate reality, pre-conceptual - Value in +spontaneity (_zìrán_ 自然 - "`self-so-ness`") - *Wú wéi* (無為) - +Non-action/effortless action + +*Dé* (德) - Virtue/Power: - Not moral virtue, but potency - Alignment +with Dào + +*Value Paradoxes*: - "`The highest good is like water`" (soft > hard) - +"`Know the masculine, keep to the feminine`" - Reversal of conventional +values + +*Zhuangzi* (莊子, 369-286 BCE): - Relativism: "`Is-ness`" (_shì fēi_ +是非) is conventional - Value freedom from fixed values - _Qíwù_ (齊物) +- Equalizing things + +===== Mohism (墨家) + +*Mozi* (墨子, 470-391 BCE): + +*Jiān’ài* (兼愛) - Universal love: - Equal concern for all +(vs. Confucian graded love) - Consequentialist ethics: Value = utility + +*Ten Doctrines*: Anti-war, anti-fate, meritocracy, frugality - Early +utilitarian calculus: "`Benefit all under heaven`" + +===== Legalism (法家) + +*Han Feizi* (韓非子, 280-233 BCE): - Law (_fǎ_ 法) as supreme value - +Reject morality in governance - Value = state power and order + +''''' + +==== Islamic Philosophy + +===== Quranic Axiology + +*Tawḥīd* (توحيد) - Unity of God: - All value derives from divine will - +God as _al-Ḥaqq_ (الحق) - The Truth/Reality + +*Justice* (_’Adl_ عدل): - Central Quranic value - Divine justice as +template for human justice + +*Mercy* (_Raḥma_ رحمة): - "`In the name of God, the Merciful, the +Compassionate`" - Balance with justice + +===== Islamic Philosophy (Falsafa) + +*Al-Farabi* (870-950 CE): - _Al-Madīna al-Fāḍila_ (The Virtuous City) - +Happiness (_sa’āda_) as highest value - Integration of Aristotle with +Islam + +*Ibn Sina (Avicenna)* (980-1037): - Essence-existence distinction - +Necessary Being (God) as source of all value - Neo-Platonic emanationism + +*Al-Ghazali* (1058-1111): - Critique of rationalist ethics - +Occasionalism: God creates anew each moment - Value in divine command, +not reason + +*Ibn Rushd (Averroes)* (1126-1198): - Defended philosophy against +Al-Ghazali - Harmony of reason and revelation - Double truth theory + +===== Sufism + +*Maqāmāt* (Stages) and *Aḥwāl* (States): - Value as spiritual progress - +Love (_'`ishq__) as highest value - Union with God (__fanā`'_) + +*Rumi* (1207-1273): - "`Love is the bridge between you and everything`" +- Value transcends rational calculation + +''''' + +==== African Philosophy + +===== Ubuntu Philosophy (Southern Africa) + +*"`Umuntu ngumuntu ngabantu`"* (Zulu): - "`A person is a person through +other persons`" - Relational ontology → relational axiology - Individual +value inseparable from community + +*Botho/Ubuntu* (Tswana/Zulu): - Compassion, reciprocity, dignity, +harmony - Communitarian ethics vs. Western individualism + +*Restorative Justice*: - Value: Healing relationships > punishment - +Applied in South African Truth & Reconciliation Commission + +===== Ancient Egyptian _Ma’at_ + +*Ma’at* (𓅓𓁐𓏏𓁐): - Truth, justice, cosmic order (1500+ BCE) - Pharaoh’s +role: Maintain ma’at - Heart weighed against feather of ma’at in +afterlife - Precursor to later justice concepts + +===== Yoruba Philosophy (West Africa) + +*Ìwà* - Character/essence: - Central value concept - "`Ìwà l’ẹwà`" - +Character is beauty + +*Àjẹ* - Spiritual/economic power: - Integration of material and +spiritual value - Wealth without character is disvalued + +''''' + +==== Indigenous American Philosophies + +===== Lakota Values + +*Wóčhekiye* - Seven Sacred Rites: - Value in ritual and connection to +land + +*Mitákuye Oyásʼiŋ* - "`All my relations`": - Kinship extends to all +beings - Ecological value theory + +===== Nahua Philosophy (Aztec/Mexica) + +*In Xóchitl In Cuícatl* - "`Flower and song`": - Truth/value expressed +through poetry and art - Aesthetic epistemology + +*Teotl* - Divine energy/power: - Monist ontology → unified value theory +- Balance of opposites + +*Tloque Nahuaque* - "`Lord of the Near and Far`": - Ultimate +value/reality + +''''' + +==== Japanese Philosophy + +===== Shinto + +*Kami* (神) - Sacred spirit/force: - Value in natural phenomena - Purity +(_kiyome_) as value + +*Wa* (和) - Harmony: - Social cohesion as supreme value - Influences +business ethics (_kaizen_, _nemawashi_) + +===== Zen Buddhism + +*Mu* (無) - Emptiness/nothingness: - Value in non-attachment - Direct +experience > conceptual knowledge + +*Wabi-Sabi* (侘寂): - Beauty in imperfection and impermanence - +Aesthetic value theory + +*Bushido* (武士道) - Way of the Warrior: - Honor, loyalty, +self-discipline - Death over dishonor + +''''' + +=== Heterodox Western Traditions + +==== Austrian School Economics + +*Carl Menger* (1840-1921): - *Subjective theory of value*: Value is not +intrinsic but subjective - Marginal utility: Value of next unit, not +total - Ordinal rankings suffice (no cardinal utility needed) + +*Ludwig von Mises* (1881-1973): - _Human Action_ (1949) - *Praxeology*: +Study of purposeful human action - Value scales: Individuals rank ends +ordinally - Critique of interpersonal utility comparisons (welfare +economics impossible) + +*Friedrich Hayek* (1899-1992): - *Spontaneous order*: Values emerge from +decentralized process - Knowledge problem: Central planning can’t +aggregate dispersed value information - Tradition as repository of +evolved values + +*Murray Rothbard* (1926-1995): - Natural rights axiom: Self-ownership - +Deontological libertarianism - Critique of consequentialist ethics + +''''' + +==== Anarchist Value Theory + +*Pierre-Joseph Proudhon* (1809-1865): - "`Property is theft`" - +Mutualism: Value in reciprocal exchange - Labor theory of value +(pre-Marxist) + +*Peter Kropotkin* (1842-1921): - _Mutual Aid_ (1902) - Cooperation as +evolutionary value - Anarcho-communism: "`From each… to each…`" + +*Emma Goldman* (1869-1940): - Individual autonomy as primary value - +Critique of authority (state, church, patriarchy) + +''''' + +==== Feminist Axiology + +*Carol Gilligan* (1936-Present): - _In a Different Voice_ (1982) - +*Ethics of care* vs. ethics of justice - Relational values, contextual +reasoning + +*Nel Noddings* (1929-Present): - Caring as fundamental value - Receptive +attention to particular others + +*Virginia Held* (1929-Present): - Care ethics as comprehensive moral +theory - Critique of social contract theory’s individualism + +*Audre Lorde* (1934-1992): - "`The master’s tools will never dismantle +the master’s house`" - Value of difference and diversity - +Intersectional analysis + +''''' + +==== Ecological/Deep Ecology + +*Aldo Leopold* (1887-1948): - _A Sand County Almanac_ (1949) - *Land +Ethic*: "`A thing is right when it tends to preserve the integrity, +stability, and beauty of the biotic community`" - Intrinsic value of +ecosystems + +*Arne Næss* (1912-2009): - Deep ecology vs. shallow ecology - +*Self-realization*: Expanded ecological self - Biocentric equality: All +life has equal right to flourish + +*Holmes Rolston III* (1932-Present): - Environmental values: Intrinsic, +instrumental, systemic - Nature creates value (not just humans) + +''''' + +==== Pragmatist Axiology + +*William James* (1842-1910): - Pragmatic theory of truth: Value is +"`cash value`" in experience - Pluralism: No single value system + +*John Dewey* (1859-1952): - _Theory of Valuation_ (1939) - Values as +outcomes of inquiry - Continuity of means and ends + +*Hilary Putnam* (1926-2016): - Fact-value entanglement - "`Thick`" +ethical concepts: Cruel, kind, brave + +''''' + +=== Comparative Analysis + +[width="100%",cols="22%,28%,24%,26%",options="header",] +|=== +|Tradition |Primary Value |Metaphysics |Epistemology +|*Confucian* |Harmony (_hé_) |Relational |Ritual cultivation +|*Daoist* |Spontaneity (_zìrán_) |Monist (Dao) |Non-conceptual knowing +|*Buddhist* |Cessation (_nirodha_) |Emptiness |Meditation +|*Hindu* |Liberation (_mokṣa_) |Brahman |Knowledge (_jñāna_) +|*Islamic* |Divine will (_irāda_) |Theistic |Revelation + reason +|*Ubuntu* |Community (_ubuntu_) |Relational |Communal wisdom +|*Austrian* |Subjective preference |Individualist |Praxeological +|*Feminist* |Care |Relational |Contextual +|*Deep Ecology* |Biocentric equality |Ecological holism |Expanded self +|=== + +''''' + +=== Implications for Axiology.jl + +==== Multi-Cultural Value Systems + +This library can encode diverse value traditions: + +*Confucian Harmony* (五常): + +[source,julia] +---- +harmony = Welfare( + metric = :relational_balance, + components = [:ruler_subject, :father_son, :husband_wife, :elder_younger, :friend_friend] +) +---- + +*Ubuntu Relational Ethics*: + +[source,julia] +---- +ubuntu = Fairness( + metric = :community_welfare, + protected_attributes = [:individual, :community], + threshold = 0.0 # No individual disadvantage acceptable +) +---- + +*Buddhist Middle Way*: + +[source,julia] +---- +middle_way = Efficiency( + metric = :balance, + avoid_extremes = [:asceticism, :hedonism] +) +---- + +*Islamic Justice* (_’Adl_): + +[source,julia] +---- +adl = Fairness( + metric = :divine_justice, + includes_mercy = true +) +---- + +*Deep Ecology Biocentric Equality*: + +[source,julia] +---- +biocentric = Safety( + invariant = "∀ species. equal right to flourish", + scope = :all_life +) +---- + +==== Pluralistic Value Aggregation + +Supporting non-Western value systems requires: 1. *Non-utilitarian +aggregation* (Rawlsian, lexicographic) 2. *Relational values* (not just +individual utility) 3. *Threshold constraints* (deontological) 4. +*Context-sensitivity* (particularist ethics) + +''''' + +=== References + +==== Indian Philosophy + +* Radhakrishnan, S., & Moore, C. (1957). _A Sourcebook in Indian +Philosophy_. +* Hiriyanna, M. (1932). _Outlines of Indian Philosophy_. + +==== Chinese Philosophy + +* Chan, W.-T. (1963). _A Source Book in Chinese Philosophy_. +* Graham, A.C. (1989). _Disputers of the Tao_. + +==== Islamic Philosophy + +* Nasr, S.H., & Leaman, O. (Eds.). (1996). _History of Islamic +Philosophy_. +* Fakhry, M. (2004). _A History of Islamic Philosophy_. + +==== African Philosophy + +* Ramose, M.B. (1999). _African Philosophy Through Ubuntu_. +* Wiredu, K. (1996). _Cultural Universals and Particulars_. + +==== Austrian School + +* Mises, L. von. (1949). _Human Action_. +* Hayek, F.A. (1988). _The Fatal Conceit_. + +==== Feminist Ethics + +* Gilligan, C. (1982). _In a Different Voice_. +* Held, V. (2006). _The Ethics of Care_. + +==== Deep Ecology + +* Næss, A. (1973). "`The Shallow and the Deep, Long-Range Ecology +Movement`". +* Rolston, H. (1988). _Environmental Ethics_. diff --git a/packages/Axiology.jl/docs/theory/CROSS_CULTURAL_PERSPECTIVES.md b/packages/Axiology.jl/docs/theory/CROSS_CULTURAL_PERSPECTIVES.md deleted file mode 100644 index 08e58f6a5..000000000 --- a/packages/Axiology.jl/docs/theory/CROSS_CULTURAL_PERSPECTIVES.md +++ /dev/null @@ -1,481 +0,0 @@ -# Cross-Cultural Perspectives on Value Theory - -## Beyond Western Philosophy - -### Indian Philosophy - -#### Vedic Period (1500-500 BCE) - -**Ṛta** (ऋत) - Cosmic Order/Truth: -- Pre-axial concept of value as cosmic harmony -- Foundation for later dharma concept -- Value inherent in natural order - -**Upanishads** (800-200 BCE): -- **Brahman** as ultimate reality and value -- **Ātman** (self) identified with Brahman -- Value hierarchy: Knowledge > ritual > material - -#### Classical Hindu Philosophy - -**Puruṣārthas** (Four Aims of Life): -1. **Dharma** (धर्म) - Righteousness, moral law -2. **Artha** (अर्थ) - Prosperity, economic value -3. **Kāma** (काम) - Pleasure, aesthetic/emotional value -4. **Mokṣa** (मोक्ष) - Liberation (highest value) - -**Bhagavad Gītā** (circa 200 BCE-200 CE): -- **Svadharma**: Value relative to one's station (*varṇa*) -- **Niṣkāma karma**: Action without attachment to fruits -- Three paths (*mārgas*): Knowledge, devotion, action - -#### Buddhist Axiology - -**Four Noble Truths** (Catvāri Ārya Satyāni): -1. *Duḥkha* - Suffering/dissatisfaction (disvalue) -2. *Samudaya* - Origin of suffering (craving/*tṛṣṇā*) -3. *Nirodha* - Cessation (value achieved through elimination) -4. *Mārga* - Path to cessation - -**Middle Way** (*Madhyamā-Pratipad*): -- Rejection of extremes (asceticism vs. hedonism) -- Value as balance, not maximization - -**Dependent Origination** (*Pratītyasamutpāda*): -- Values lack inherent existence -- Contextual, relational value theory - -**Mahāyāna**: Bodhisattva ideal - compassion as supreme value - -#### Jain Ethics - -**Ahiṃsā** (अहिंसा) - Non-violence: -- Primary value, more extreme than Hindu/Buddhist -- Extends to thoughts, words, deeds - -**Anekāntavāda** - Many-sidedness: -- No single perspective captures complete truth -- Value pluralism as metaphysical necessity - -**Syādvāda** - Conditional predication: -- Seven-fold judgment (*Saptabhaṅgī*) -- Truth and value are contextual, multi-aspected - ---- - -### Chinese Philosophy - -#### Confucianism (儒家) - -**Confucius** (孔子, 551-479 BCE): - -**Five Constants** (*Wǔcháng* 五常): -1. **Rén** (仁) - Benevolence, humanity -2. **Yì** (义) - Righteousness, justice -3. **Lǐ** (礼) - Ritual propriety, etiquette -4. **Zhì** (智) - Wisdom, knowledge -5. **Xìn** (信) - Integrity, trustworthiness - -**Five Relationships** (*Wǔlún* 五伦): -- Ruler-subject, father-son, husband-wife, elder-younger, friend-friend -- Value as relational harmony, not individual rights - -**Mencius** (孟子, 372-289 BCE): -- Human nature is inherently good (*xìng shàn* 性善) -- Four sprouts: Compassion, shame, courtesy, moral judgment -- Value cultivation through education - -**Xunzi** (荀子, 313-238 BCE): -- Human nature is inherently selfish -- Value created through ritual and education -- Constructivist axiology - -#### Daoism (道家) - -**Laozi** (老子, 6th century BCE?): - -**Dào** (道) - Way/Path: -- Ultimate reality, pre-conceptual -- Value in spontaneity (*zìrán* 自然 - "self-so-ness") -- **Wú wéi** (無為) - Non-action/effortless action - -**Dé** (德) - Virtue/Power: -- Not moral virtue, but potency -- Alignment with Dào - -**Value Paradoxes**: -- "The highest good is like water" (soft > hard) -- "Know the masculine, keep to the feminine" -- Reversal of conventional values - -**Zhuangzi** (莊子, 369-286 BCE): -- Relativism: "Is-ness" (*shì fēi* 是非) is conventional -- Value freedom from fixed values -- *Qíwù* (齊物) - Equalizing things - -#### Mohism (墨家) - -**Mozi** (墨子, 470-391 BCE): - -**Jiān'ài** (兼愛) - Universal love: -- Equal concern for all (vs. Confucian graded love) -- Consequentialist ethics: Value = utility - -**Ten Doctrines**: Anti-war, anti-fate, meritocracy, frugality -- Early utilitarian calculus: "Benefit all under heaven" - -#### Legalism (法家) - -**Han Feizi** (韓非子, 280-233 BCE): -- Law (*fǎ* 法) as supreme value -- Reject morality in governance -- Value = state power and order - ---- - -### Islamic Philosophy - -#### Quranic Axiology - -**Tawḥīd** (توحيد) - Unity of God: -- All value derives from divine will -- God as *al-Ḥaqq* (الحق) - The Truth/Reality - -**Justice** (*'Adl* عدل): -- Central Quranic value -- Divine justice as template for human justice - -**Mercy** (*Raḥma* رحمة): -- "In the name of God, the Merciful, the Compassionate" -- Balance with justice - -#### Islamic Philosophy (Falsafa) - -**Al-Farabi** (870-950 CE): -- *Al-Madīna al-Fāḍila* (The Virtuous City) -- Happiness (*sa'āda*) as highest value -- Integration of Aristotle with Islam - -**Ibn Sina (Avicenna)** (980-1037): -- Essence-existence distinction -- Necessary Being (God) as source of all value -- Neo-Platonic emanationism - -**Al-Ghazali** (1058-1111): -- Critique of rationalist ethics -- Occasionalism: God creates anew each moment -- Value in divine command, not reason - -**Ibn Rushd (Averroes)** (1126-1198): -- Defended philosophy against Al-Ghazali -- Harmony of reason and revelation -- Double truth theory - -#### Sufism - -**Maqāmāt** (Stages) and **Aḥwāl** (States): -- Value as spiritual progress -- Love (*'ishq*) as highest value -- Union with God (*fanā'*) - -**Rumi** (1207-1273): -- "Love is the bridge between you and everything" -- Value transcends rational calculation - ---- - -### African Philosophy - -#### Ubuntu Philosophy (Southern Africa) - -**"Umuntu ngumuntu ngabantu"** (Zulu): -- "A person is a person through other persons" -- Relational ontology → relational axiology -- Individual value inseparable from community - -**Botho/Ubuntu** (Tswana/Zulu): -- Compassion, reciprocity, dignity, harmony -- Communitarian ethics vs. Western individualism - -**Restorative Justice**: -- Value: Healing relationships > punishment -- Applied in South African Truth & Reconciliation Commission - -#### Ancient Egyptian *Ma'at* - -**Ma'at** (𓅓𓁐𓏏𓁐): -- Truth, justice, cosmic order (1500+ BCE) -- Pharaoh's role: Maintain ma'at -- Heart weighed against feather of ma'at in afterlife -- Precursor to later justice concepts - -#### Yoruba Philosophy (West Africa) - -**Ìwà** - Character/essence: -- Central value concept -- "Ìwà l'ẹwà" - Character is beauty - -**Àjẹ** - Spiritual/economic power: -- Integration of material and spiritual value -- Wealth without character is disvalued - ---- - -### Indigenous American Philosophies - -#### Lakota Values - -**Wóčhekiye** - Seven Sacred Rites: -- Value in ritual and connection to land - -**Mitákuye Oyásʼiŋ** - "All my relations": -- Kinship extends to all beings -- Ecological value theory - -#### Nahua Philosophy (Aztec/Mexica) - -**In Xóchitl In Cuícatl** - "Flower and song": -- Truth/value expressed through poetry and art -- Aesthetic epistemology - -**Teotl** - Divine energy/power: -- Monist ontology → unified value theory -- Balance of opposites - -**Tloque Nahuaque** - "Lord of the Near and Far": -- Ultimate value/reality - ---- - -### Japanese Philosophy - -#### Shinto - -**Kami** (神) - Sacred spirit/force: -- Value in natural phenomena -- Purity (*kiyome*) as value - -**Wa** (和) - Harmony: -- Social cohesion as supreme value -- Influences business ethics (*kaizen*, *nemawashi*) - -#### Zen Buddhism - -**Mu** (無) - Emptiness/nothingness: -- Value in non-attachment -- Direct experience > conceptual knowledge - -**Wabi-Sabi** (侘寂): -- Beauty in imperfection and impermanence -- Aesthetic value theory - -**Bushido** (武士道) - Way of the Warrior: -- Honor, loyalty, self-discipline -- Death over dishonor - ---- - -## Heterodox Western Traditions - -### Austrian School Economics - -**Carl Menger** (1840-1921): -- **Subjective theory of value**: Value is not intrinsic but subjective -- Marginal utility: Value of next unit, not total -- Ordinal rankings suffice (no cardinal utility needed) - -**Ludwig von Mises** (1881-1973): -- *Human Action* (1949) -- **Praxeology**: Study of purposeful human action -- Value scales: Individuals rank ends ordinally -- Critique of interpersonal utility comparisons (welfare economics impossible) - -**Friedrich Hayek** (1899-1992): -- **Spontaneous order**: Values emerge from decentralized process -- Knowledge problem: Central planning can't aggregate dispersed value information -- Tradition as repository of evolved values - -**Murray Rothbard** (1926-1995): -- Natural rights axiom: Self-ownership -- Deontological libertarianism -- Critique of consequentialist ethics - ---- - -### Anarchist Value Theory - -**Pierre-Joseph Proudhon** (1809-1865): -- "Property is theft" -- Mutualism: Value in reciprocal exchange -- Labor theory of value (pre-Marxist) - -**Peter Kropotkin** (1842-1921): -- *Mutual Aid* (1902) -- Cooperation as evolutionary value -- Anarcho-communism: "From each... to each..." - -**Emma Goldman** (1869-1940): -- Individual autonomy as primary value -- Critique of authority (state, church, patriarchy) - ---- - -### Feminist Axiology - -**Carol Gilligan** (1936-Present): -- *In a Different Voice* (1982) -- **Ethics of care** vs. ethics of justice -- Relational values, contextual reasoning - -**Nel Noddings** (1929-Present): -- Caring as fundamental value -- Receptive attention to particular others - -**Virginia Held** (1929-Present): -- Care ethics as comprehensive moral theory -- Critique of social contract theory's individualism - -**Audre Lorde** (1934-1992): -- "The master's tools will never dismantle the master's house" -- Value of difference and diversity -- Intersectional analysis - ---- - -### Ecological/Deep Ecology - -**Aldo Leopold** (1887-1948): -- *A Sand County Almanac* (1949) -- **Land Ethic**: "A thing is right when it tends to preserve the integrity, stability, and beauty of the biotic community" -- Intrinsic value of ecosystems - -**Arne Næss** (1912-2009): -- Deep ecology vs. shallow ecology -- **Self-realization**: Expanded ecological self -- Biocentric equality: All life has equal right to flourish - -**Holmes Rolston III** (1932-Present): -- Environmental values: Intrinsic, instrumental, systemic -- Nature creates value (not just humans) - ---- - -### Pragmatist Axiology - -**William James** (1842-1910): -- Pragmatic theory of truth: Value is "cash value" in experience -- Pluralism: No single value system - -**John Dewey** (1859-1952): -- *Theory of Valuation* (1939) -- Values as outcomes of inquiry -- Continuity of means and ends - -**Hilary Putnam** (1926-2016): -- Fact-value entanglement -- "Thick" ethical concepts: Cruel, kind, brave - ---- - -## Comparative Analysis - -| Tradition | Primary Value | Metaphysics | Epistemology | -|-----------|---------------|-------------|--------------| -| **Confucian** | Harmony (*hé*) | Relational | Ritual cultivation | -| **Daoist** | Spontaneity (*zìrán*) | Monist (Dao) | Non-conceptual knowing | -| **Buddhist** | Cessation (*nirodha*) | Emptiness | Meditation | -| **Hindu** | Liberation (*mokṣa*) | Brahman | Knowledge (*jñāna*) | -| **Islamic** | Divine will (*irāda*) | Theistic | Revelation + reason | -| **Ubuntu** | Community (*ubuntu*) | Relational | Communal wisdom | -| **Austrian** | Subjective preference | Individualist | Praxeological | -| **Feminist** | Care | Relational | Contextual | -| **Deep Ecology** | Biocentric equality | Ecological holism | Expanded self | - ---- - -## Implications for Axiology.jl - -### Multi-Cultural Value Systems - -This library can encode diverse value traditions: - -**Confucian Harmony** (五常): -```julia -harmony = Welfare( - metric = :relational_balance, - components = [:ruler_subject, :father_son, :husband_wife, :elder_younger, :friend_friend] -) -``` - -**Ubuntu Relational Ethics**: -```julia -ubuntu = Fairness( - metric = :community_welfare, - protected_attributes = [:individual, :community], - threshold = 0.0 # No individual disadvantage acceptable -) -``` - -**Buddhist Middle Way**: -```julia -middle_way = Efficiency( - metric = :balance, - avoid_extremes = [:asceticism, :hedonism] -) -``` - -**Islamic Justice** (*'Adl*): -```julia -adl = Fairness( - metric = :divine_justice, - includes_mercy = true -) -``` - -**Deep Ecology Biocentric Equality**: -```julia -biocentric = Safety( - invariant = "∀ species. equal right to flourish", - scope = :all_life -) -``` - -### Pluralistic Value Aggregation - -Supporting non-Western value systems requires: -1. **Non-utilitarian aggregation** (Rawlsian, lexicographic) -2. **Relational values** (not just individual utility) -3. **Threshold constraints** (deontological) -4. **Context-sensitivity** (particularist ethics) - ---- - -## References - -### Indian Philosophy -- Radhakrishnan, S., & Moore, C. (1957). *A Sourcebook in Indian Philosophy*. -- Hiriyanna, M. (1932). *Outlines of Indian Philosophy*. - -### Chinese Philosophy -- Chan, W.-T. (1963). *A Source Book in Chinese Philosophy*. -- Graham, A.C. (1989). *Disputers of the Tao*. - -### Islamic Philosophy -- Nasr, S.H., & Leaman, O. (Eds.). (1996). *History of Islamic Philosophy*. -- Fakhry, M. (2004). *A History of Islamic Philosophy*. - -### African Philosophy -- Ramose, M.B. (1999). *African Philosophy Through Ubuntu*. -- Wiredu, K. (1996). *Cultural Universals and Particulars*. - -### Austrian School -- Mises, L. von. (1949). *Human Action*. -- Hayek, F.A. (1988). *The Fatal Conceit*. - -### Feminist Ethics -- Gilligan, C. (1982). *In a Different Voice*. -- Held, V. (2006). *The Ethics of Care*. - -### Deep Ecology -- Næss, A. (1973). "The Shallow and the Deep, Long-Range Ecology Movement". -- Rolston, H. (1988). *Environmental Ethics*. diff --git a/packages/Axiom.jl/ABI-FFI-README.adoc b/packages/Axiom.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..521633f94 --- /dev/null +++ b/packages/Axiom.jl/ABI-FFI-README.adoc @@ -0,0 +1,69 @@ +== Axiom.jl ABI / FFI Notes + +This file documents the current ABI/FFI split for Axiom.jl. + +=== Canonical ABI Spec (Idris2) + +The Idris2 ABI scaffold now lives under: + +* `+src/Abi/Types.idr+` +* `+src/Abi/Layout.idr+` +* `+src/Abi/Foreign.idr+` + +These modules use concrete `+axiom_*+` symbol names and no unresolved +template placeholders. + +==== Idris2 validation + +[source,bash] +---- +idris2 --source-dir src --check src/Abi/Types.idr +idris2 --source-dir src --check src/Abi/Layout.idr +idris2 --source-dir src --check src/Abi/Foreign.idr +---- + +=== Runtime FFI Used in Production Paths + +Current production-tested backend FFI path is Julia <-> Zig: + +* Julia bridge: `+src/backends/zig_ffi.jl+` +* Zig C ABI exports: `+ffi/zig/src/main.zig+` + +This path is covered by CI/readiness checks (backend parity + runtime +smoke). + +=== Zig FFI Status + +`+ffi/zig/+` is now concrete (non-template) and exports concrete +`+axiom_*+` symbols: + +* implementation: `+ffi/zig/src/main.zig+` +* build/test entry: `+ffi/zig/build.zig+` +* integration coverage: `+ffi/zig/test/integration_test.zig+` +* C header: `+ffi/zig/include/axiom.h+` + +Validation: + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +=== Bidirectionality Status + +* Implemented and exercised: +** host -> runtime calls (`+axiom_process+`, `+axiom_process_array+`, +etc.) +** runtime -> host callback bridge (`+axiom_register_callback+`, +`+axiom_invoke_callback+`) +* Idris side includes concrete callback pointer registration and +callback invoke declarations in `+src/Abi/Foreign.idr+`. +* Still not a full cross-language compatibility matrix across all +planned targets, but no longer template-only. + +=== Practical Guidance + +For release/readiness decisions, treat the Zig FFI path as +authoritative. Treat Idris2 ABI files as formal scaffold/specification +that now typechecks and uses concrete Axiom naming. diff --git a/packages/Axiom.jl/ABI-FFI-README.md b/packages/Axiom.jl/ABI-FFI-README.md deleted file mode 100644 index bf90d3602..000000000 --- a/packages/Axiom.jl/ABI-FFI-README.md +++ /dev/null @@ -1,60 +0,0 @@ -# Axiom.jl ABI / FFI Notes - -This file documents the current ABI/FFI split for Axiom.jl. - -## Canonical ABI Spec (Idris2) - -The Idris2 ABI scaffold now lives under: - -- `src/Abi/Types.idr` -- `src/Abi/Layout.idr` -- `src/Abi/Foreign.idr` - -These modules use concrete `axiom_*` symbol names and no unresolved template placeholders. - -### Idris2 validation - -```bash -idris2 --source-dir src --check src/Abi/Types.idr -idris2 --source-dir src --check src/Abi/Layout.idr -idris2 --source-dir src --check src/Abi/Foreign.idr -``` - -## Runtime FFI Used in Production Paths - -Current production-tested backend FFI path is Julia <-> Zig: - -- Julia bridge: `src/backends/zig_ffi.jl` -- Zig C ABI exports: `ffi/zig/src/main.zig` - -This path is covered by CI/readiness checks (backend parity + runtime smoke). - -## Zig FFI Status - -`ffi/zig/` is now concrete (non-template) and exports concrete `axiom_*` symbols: - -- implementation: `ffi/zig/src/main.zig` -- build/test entry: `ffi/zig/build.zig` -- integration coverage: `ffi/zig/test/integration_test.zig` -- C header: `ffi/zig/include/axiom.h` - -Validation: - -```bash -cd ffi/zig -zig build test -``` - -## Bidirectionality Status - -- Implemented and exercised: - - host -> runtime calls (`axiom_process`, `axiom_process_array`, etc.) - - runtime -> host callback bridge (`axiom_register_callback`, `axiom_invoke_callback`) -- Idris side includes concrete callback pointer registration and callback invoke declarations in `src/Abi/Foreign.idr`. -- Still not a full cross-language compatibility matrix across all planned targets, but no longer template-only. - -## Practical Guidance - -For release/readiness decisions, treat the Zig FFI path as authoritative. -Treat Idris2 ABI files as formal scaffold/specification that now typechecks and -uses concrete Axiom naming. diff --git a/packages/Axiom.jl/CODE_OF_CONDUCT.adoc b/packages/Axiom.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..8a96a40de --- /dev/null +++ b/packages/Axiom.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,92 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment: + +* *Emotional Safety*: Creating space for experimentation without shame +* *Technical Excellence*: Valuing correctness and quality +* *Respectful Disagreement*: Engaging with ideas, not attacking people +* *Collaborative Learning*: Sharing knowledge generously +* *Inclusive Language*: Using welcoming and accessible language + +Examples of unacceptable behavior: + +* Harassment, discrimination, or exclusionary behavior +* Trolling, insulting comments, or personal attacks +* Public or private harassment +* Publishing others’ private information without consent +* Dismissing or attacking inclusion efforts +* Other conduct inappropriate in a professional setting + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +* GitHub/GitLab repositories +* Issue trackers and pull requests +* Mailing lists and forums +* Chat platforms (Discord, etc.) +* Conferences and meetups +* Social media when representing the project + +=== Enforcement + +==== Reporting + +Report violations to: conduct@axiom-jl.org + +All reports will be reviewed promptly and confidentially. + +==== Response Guidelines + +Community leaders will follow these steps: + +[arabic] +. *Acknowledgment*: Within 48 hours +. *Investigation*: Fair review of the situation +. *Decision*: Based on severity and context +. *Communication*: Inform all parties of the outcome + +==== Enforcement Actions + +[cols=",,",options="header",] +|=== +|Level |Action |Duration +|1. Correction |Private warning, explanation |N/A +|2. Warning |Public warning, no interaction |30 days +|3. Temporary Ban |Suspension from community |90 days +|4. Permanent Ban |Permanent exclusion |Indefinite +|=== + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +''''' + +_This Code of Conduct is part of our RSR compliance commitment to +emotionally safe software development._ diff --git a/packages/Axiom.jl/CODE_OF_CONDUCT.md b/packages/Axiom.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 7837362ac..000000000 --- a/packages/Axiom.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,93 +0,0 @@ - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment: - -* **Emotional Safety**: Creating space for experimentation without shame -* **Technical Excellence**: Valuing correctness and quality -* **Respectful Disagreement**: Engaging with ideas, not attacking people -* **Collaborative Learning**: Sharing knowledge generously -* **Inclusive Language**: Using welcoming and accessible language - -Examples of unacceptable behavior: - -* Harassment, discrimination, or exclusionary behavior -* Trolling, insulting comments, or personal attacks -* Public or private harassment -* Publishing others' private information without consent -* Dismissing or attacking inclusion efforts -* Other conduct inappropriate in a professional setting - -## Scope - -This Code of Conduct applies within all community spaces, including: - -* GitHub/GitLab repositories -* Issue trackers and pull requests -* Mailing lists and forums -* Chat platforms (Discord, etc.) -* Conferences and meetups -* Social media when representing the project - -## Enforcement - -### Reporting - -Report violations to: conduct@axiom-jl.org - -All reports will be reviewed promptly and confidentially. - -### Response Guidelines - -Community leaders will follow these steps: - -1. **Acknowledgment**: Within 48 hours -2. **Investigation**: Fair review of the situation -3. **Decision**: Based on severity and context -4. **Communication**: Inform all parties of the outcome - -### Enforcement Actions - -| Level | Action | Duration | -|-------|--------|----------| -| 1. Correction | Private warning, explanation | N/A | -| 2. Warning | Public warning, no interaction | 30 days | -| 3. Temporary Ban | Suspension from community | 90 days | -| 4. Permanent Ban | Permanent exclusion | Indefinite | - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations - ---- - -*This Code of Conduct is part of our RSR compliance commitment to emotionally safe software development.* diff --git a/packages/Axiom.jl/GOVERNANCE.adoc b/packages/Axiom.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..641692ae1 --- /dev/null +++ b/packages/Axiom.jl/GOVERNANCE.adoc @@ -0,0 +1,161 @@ +== Governance + +=== Overview + +Axiom.jl uses a *Benevolent Dictator for Life (BDFL) + Consensus* model, +inspired by successful open source projects while incorporating RSR +principles. + +=== Decision Making + +==== Levels of Decision + +[width="100%",cols="31%,30%,39%",options="header",] +|=== +|Level |Scope |Process +|*Minor* |Bug fixes, docs, typos |Single maintainer approval +|*Standard* |Features, refactors |Two maintainer approval +|*Major* |Architecture, breaking changes |BDFL + community RFC +|*Governance* |This document, CoC changes |BDFL + supermajority vote +|=== + +==== RFC Process + +For major changes: + +[arabic] +. *Draft RFC*: Open issue with `+[RFC]+` prefix +. *Discussion Period*: Minimum 14 days +. *Revision*: Address feedback +. *Final Comment Period*: 7 days +. *Decision*: BDFL decision with reasoning + +=== Roles + +==== BDFL (Benevolent Dictator for Life) + +*Current BDFL*: [Project Founder] + +Responsibilities: - Final arbiter on technical disputes - Guardian of +project vision - Emergency decisions when needed + +The BDFL can be changed by unanimous agreement of Core Contributors. + +==== Core Contributors + +Contributors with merge rights. Requirements: + +* Sustained contributions over 6+ months +* Deep understanding of codebase +* Demonstrated alignment with project values +* Nominated by existing Core Contributor +* Approved by BDFL + +*Current Core Contributors*: See `+MAINTAINERS.md+` + +==== Contributors + +Anyone who has contributed code, docs, issues, or reviews. + +==== Community Members + +Anyone participating in discussions, using the software, or providing +feedback. + +=== Tri-Perimeter Contribution Framework (TPCF) + +Following RSR standards, contributions are organized by trust level: + +==== 🔒 Perimeter 1 (Core) + +*Access*: Core Contributors only + +Areas: - Build system (flake.nix, Justfile) - CI/CD configuration - +Security-critical code - FFI boundaries - Release process + +==== 🧠 Perimeter 2 (Expert) + +*Access*: Trusted Contributors (established track record) + +Areas: - Core algorithms - Verification system - Backend implementations +- API design - Performance-critical code + +==== 🌱 Perimeter 3 (Community) + +*Access*: Open to all + +Areas: - Documentation - Examples - Tests - Bug reports - Feature +proposals - Community support + +=== Meetings + +==== Technical Meetings + +* *Frequency*: Monthly +* *Format*: Video call + text summary +* *Agenda*: Posted 7 days in advance +* *Notes*: Published in `+docs/meetings/+` + +==== Community Calls + +* *Frequency*: Quarterly +* *Format*: Open video call +* *Purpose*: Community Q&A, roadmap discussion + +=== Conflict Resolution + +[arabic] +. *Discussion*: Try to resolve through discussion +. *Mediation*: Involve neutral third party +. *Escalation*: Bring to Core Contributors +. *Final Decision*: BDFL makes final call + +=== Changes to Governance + +This document can be changed through: + +[arabic] +. RFC process (standard) +. 14-day discussion period +. Supermajority (2/3) approval from Core Contributors +. BDFL approval + +=== Code of Conduct + +All participants must follow our link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +Violations should be reported to: conduct@axiom-jl.org + +=== Licensing Decisions + +* Core framework: MIT License +* All contributions must be MIT-compatible +* Third-party dependencies reviewed for license compatibility +* SPDX headers required on all source files + +=== Financial Transparency + +* Funding sources listed in `+FUNDING.yml+` +* Financial reports published quarterly (when applicable) +* No individual may receive >50% of project funds +* All spending decisions made by Core Contributors + +=== Succession Planning + +If the BDFL becomes unavailable: + +[arabic] +. Core Contributors elect interim leader (simple majority) +. 90-day period to establish new governance +. Options: New BDFL, Steering Committee, or Foundation + +=== Contact + +* General: hello@axiom-jl.org +* Governance questions: governance@axiom-jl.org +* Security issues: security@axiom-jl.org + +''''' + +_This governance model follows RSR community governance standards._ diff --git a/packages/Axiom.jl/GOVERNANCE.md b/packages/Axiom.jl/GOVERNANCE.md deleted file mode 100644 index 60ab00b9e..000000000 --- a/packages/Axiom.jl/GOVERNANCE.md +++ /dev/null @@ -1,167 +0,0 @@ - -# Governance - -## Overview - -Axiom.jl uses a **Benevolent Dictator for Life (BDFL) + Consensus** model, inspired by successful open source projects while incorporating RSR principles. - -## Decision Making - -### Levels of Decision - -| Level | Scope | Process | -|-------|-------|---------| -| **Minor** | Bug fixes, docs, typos | Single maintainer approval | -| **Standard** | Features, refactors | Two maintainer approval | -| **Major** | Architecture, breaking changes | BDFL + community RFC | -| **Governance** | This document, CoC changes | BDFL + supermajority vote | - -### RFC Process - -For major changes: - -1. **Draft RFC**: Open issue with `[RFC]` prefix -2. **Discussion Period**: Minimum 14 days -3. **Revision**: Address feedback -4. **Final Comment Period**: 7 days -5. **Decision**: BDFL decision with reasoning - -## Roles - -### BDFL (Benevolent Dictator for Life) - -**Current BDFL**: [Project Founder] - -Responsibilities: -- Final arbiter on technical disputes -- Guardian of project vision -- Emergency decisions when needed - -The BDFL can be changed by unanimous agreement of Core Contributors. - -### Core Contributors - -Contributors with merge rights. Requirements: - -- Sustained contributions over 6+ months -- Deep understanding of codebase -- Demonstrated alignment with project values -- Nominated by existing Core Contributor -- Approved by BDFL - -**Current Core Contributors**: See `MAINTAINERS.md` - -### Contributors - -Anyone who has contributed code, docs, issues, or reviews. - -### Community Members - -Anyone participating in discussions, using the software, or providing feedback. - -## Tri-Perimeter Contribution Framework (TPCF) - -Following RSR standards, contributions are organized by trust level: - -### 🔒 Perimeter 1 (Core) - -**Access**: Core Contributors only - -Areas: -- Build system (flake.nix, Justfile) -- CI/CD configuration -- Security-critical code -- FFI boundaries -- Release process - -### 🧠 Perimeter 2 (Expert) - -**Access**: Trusted Contributors (established track record) - -Areas: -- Core algorithms -- Verification system -- Backend implementations -- API design -- Performance-critical code - -### 🌱 Perimeter 3 (Community) - -**Access**: Open to all - -Areas: -- Documentation -- Examples -- Tests -- Bug reports -- Feature proposals -- Community support - -## Meetings - -### Technical Meetings - -- **Frequency**: Monthly -- **Format**: Video call + text summary -- **Agenda**: Posted 7 days in advance -- **Notes**: Published in `docs/meetings/` - -### Community Calls - -- **Frequency**: Quarterly -- **Format**: Open video call -- **Purpose**: Community Q&A, roadmap discussion - -## Conflict Resolution - -1. **Discussion**: Try to resolve through discussion -2. **Mediation**: Involve neutral third party -3. **Escalation**: Bring to Core Contributors -4. **Final Decision**: BDFL makes final call - -## Changes to Governance - -This document can be changed through: - -1. RFC process (standard) -2. 14-day discussion period -3. Supermajority (2/3) approval from Core Contributors -4. BDFL approval - -## Code of Conduct - -All participants must follow our [Code of Conduct](CODE_OF_CONDUCT.md). - -Violations should be reported to: conduct@axiom-jl.org - -## Licensing Decisions - -- Core framework: MIT License -- All contributions must be MIT-compatible -- Third-party dependencies reviewed for license compatibility -- SPDX headers required on all source files - -## Financial Transparency - -- Funding sources listed in `FUNDING.yml` -- Financial reports published quarterly (when applicable) -- No individual may receive >50% of project funds -- All spending decisions made by Core Contributors - -## Succession Planning - -If the BDFL becomes unavailable: - -1. Core Contributors elect interim leader (simple majority) -2. 90-day period to establish new governance -3. Options: New BDFL, Steering Committee, or Foundation - -## Contact - -- General: hello@axiom-jl.org -- Governance questions: governance@axiom-jl.org -- Security issues: security@axiom-jl.org - ---- - -*This governance model follows RSR community governance standards.* diff --git a/packages/Axiom.jl/MAINTAINERS.adoc b/packages/Axiom.jl/MAINTAINERS.adoc index 48d978175..e62348cd8 100644 --- a/packages/Axiom.jl/MAINTAINERS.adoc +++ b/packages/Axiom.jl/MAINTAINERS.adoc @@ -1,47 +1,88 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the maintainers of Axiom.jl and their +responsibilities. -== Current Maintainers +=== Core Maintainers -[cols="2,3,2",options="header"] +Core maintainers have full write access and are responsible for the +project’s direction. + +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Areas +|Project Founder |@Hyperpolymath |BDFL |Architecture, Vision |=== -| Name | Role | Contact -| Jonathan D.A. Jewell -| Lead Maintainer -| https://github.com/hyperpolymath[@hyperpolymath] +=== Area Maintainers + +Area maintainers have expertise and responsibility for specific areas. + +[cols=",,",options="header",] |=== +|Area |Maintainer(s) |Description +|Julia Core |Unassigned |Core Julia implementation +|Rust Backend |Unassigned |Rust FFI and performance +|Zig Backend |Unassigned |Zig FFI and SIMD +|Verification |Unassigned |@ensure, @prove, certificates +|Documentation |Unassigned |Wiki, tutorials, API docs +|CI/CD |Unassigned |Build, test, release +|=== + +=== Responsibilities + +==== All Maintainers + +* Respond to issues and PRs within 7 days +* Follow the Code of Conduct +* Review code according to contribution guidelines +* Participate in governance decisions + +==== Core Maintainers + +* Guide overall project direction +* Make final decisions on disputed issues +* Manage releases +* Handle security issues +* Mentor new contributors + +==== Area Maintainers + +* Expert review for their area +* First response for area-specific issues +* Documentation for their area +* Onboarding contributors to their area + +=== Becoming a Maintainer -== Responsibilities +==== Requirements -Maintainers are responsible for: +[arabic] +. *Sustained Contribution*: 6+ months of regular contributions +. *Quality*: Consistently high-quality code and reviews +. *Community*: Helpful and respectful interactions +. *Understanding*: Deep knowledge of the codebase -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +==== Process -== Becoming a Maintainer +[arabic] +. Nomination by existing maintainer +. Discussion among maintainers (private) +. Vote (simple majority of core maintainers) +. Announcement and onboarding -Contributors who demonstrate: +=== Emeritus Maintainers -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +Maintainers who have stepped back but made significant contributions: -May be invited to become maintainers at the discretion of existing maintainers. +_None yet - we’re a new project!_ -== Decision Making +=== Contact -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +* General questions: maintainers@axiom-jl.org +* Security issues: security@axiom-jl.org +* Governance: governance@axiom-jl.org -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +_This document is part of RSR compliance for transparent governance._ diff --git a/packages/Axiom.jl/MAINTAINERS.md b/packages/Axiom.jl/MAINTAINERS.md deleted file mode 100644 index ca4443e22..000000000 --- a/packages/Axiom.jl/MAINTAINERS.md +++ /dev/null @@ -1,80 +0,0 @@ -# Maintainers - -This document lists the maintainers of Axiom.jl and their responsibilities. - -## Core Maintainers - -Core maintainers have full write access and are responsible for the project's direction. - -| Name | GitHub | Role | Areas | -|------|--------|------|-------| -| Project Founder | @Hyperpolymath | BDFL | Architecture, Vision | - -## Area Maintainers - -Area maintainers have expertise and responsibility for specific areas. - -| Area | Maintainer(s) | Description | -|------|---------------|-------------| -| Julia Core | Unassigned | Core Julia implementation | -| Rust Backend | Unassigned | Rust FFI and performance | -| Zig Backend | Unassigned | Zig FFI and SIMD | -| Verification | Unassigned | @ensure, @prove, certificates | -| Documentation | Unassigned | Wiki, tutorials, API docs | -| CI/CD | Unassigned | Build, test, release | - -## Responsibilities - -### All Maintainers - -- Respond to issues and PRs within 7 days -- Follow the Code of Conduct -- Review code according to contribution guidelines -- Participate in governance decisions - -### Core Maintainers - -- Guide overall project direction -- Make final decisions on disputed issues -- Manage releases -- Handle security issues -- Mentor new contributors - -### Area Maintainers - -- Expert review for their area -- First response for area-specific issues -- Documentation for their area -- Onboarding contributors to their area - -## Becoming a Maintainer - -### Requirements - -1. **Sustained Contribution**: 6+ months of regular contributions -2. **Quality**: Consistently high-quality code and reviews -3. **Community**: Helpful and respectful interactions -4. **Understanding**: Deep knowledge of the codebase - -### Process - -1. Nomination by existing maintainer -2. Discussion among maintainers (private) -3. Vote (simple majority of core maintainers) -4. Announcement and onboarding - -## Emeritus Maintainers - -Maintainers who have stepped back but made significant contributions: - -*None yet - we're a new project!* - -## Contact - -- General questions: maintainers@axiom-jl.org -- Security issues: security@axiom-jl.org -- Governance: governance@axiom-jl.org - ---- - -*This document is part of RSR compliance for transparent governance.* diff --git a/packages/Axiom.jl/SECURITY.adoc b/packages/Axiom.jl/SECURITY.adoc new file mode 100644 index 000000000..2b37e2a16 --- /dev/null +++ b/packages/Axiom.jl/SECURITY.adoc @@ -0,0 +1,143 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +We take security vulnerabilities seriously. If you discover a security +issue, please report it responsibly. + +==== How to Report + +*DO NOT* open a public GitHub issue for security vulnerabilities. + +Instead, please report security issues via: + +[arabic] +. *Email*: security@axiom-jl.org (preferred) +. *GitLab Security Advisory*: Use the confidential issue feature +. *PGP Encrypted Email*: See `+.well-known/security.txt+` for our PGP +key + +==== What to Include + +Please include the following in your report: + +* Description of the vulnerability +* Steps to reproduce +* Potential impact assessment +* Any suggested fixes (optional) + +==== Response Timeline + +[cols=",",options="header",] +|=== +|Action |Timeline +|Acknowledgment |Within 48 hours +|Initial assessment |Within 7 days +|Status update |Every 14 days +|Fix release |Depends on severity +|=== + +==== Severity Levels + +[cols=",,",options="header",] +|=== +|Severity |Description |Target Fix Time +|Critical |Remote code execution, data breach |24-72 hours +|High |Privilege escalation, significant data exposure |7 days +|Medium |Limited data exposure, DoS |30 days +|Low |Minor issues, hardening |90 days +|=== + +=== Security Measures + +==== Code Security + +* *Memory Safety*: Rust and Zig backends provide memory safety +guarantees +* *Type Safety*: Julia’s type system prevents many classes of bugs +* *Formal Verification*: `+@prove+` macro enables mathematical +correctness proofs +* *Runtime Checks*: `+@ensure+` macro validates invariants at runtime + +==== Supply Chain Security + +* *Dependency Auditing*: Regular `+cargo audit+` and `+cargo deny+` +checks +* *SBOM Generation*: Software Bill of Materials available +* *Reproducible Builds*: Nix flake ensures reproducibility +* *Signed Releases*: All releases are signed with GPG + +==== Development Practices + +* *Code Review*: All changes require review +* *CI/CD Security*: Automated security scanning in pipeline +* *Secrets Management*: No secrets in repository +* *SPDX Headers*: All source files have license headers + +=== Security Features for Users + +==== Verification System + +Axiom.jl provides built-in security features for ML models: + +[source,julia] +---- +# Runtime bounds checking +@ensure all(0 .≤ output .≤ 1) "Output must be valid probabilities" + +# Formal verification +@prove BoundedOutputs(0.0, 1.0) model + +# Verification certificates +cert = generate_certificate(model, properties) +---- + +==== Deterministic Inference + +For safety-critical applications: + +[source,julia] +---- +Axiom.set_deterministic!(true) # Reproducible results +---- + +==== Input Validation + +[source,julia] +---- +@ensure valid_input(x) "Input validation failed" +@ensure no_nan(x) "Input contains NaN values" +---- + +=== Security Advisories + +Security advisories are published at: + +* GitHub Security Advisories +* `+.well-known/security.txt+` +* Mailing list (security-announce@axiom-jl.org) + +=== Acknowledgments + +We thank the following security researchers for responsible disclosure: + +_No vulnerabilities reported yet._ + +=== Contact + +* Security Team: security@axiom-jl.org +* PGP Key: See `+.well-known/security.txt+` +* Response Team: See `+MAINTAINERS.md+` + +''''' + +_This security policy follows https://www.rfc-editor.org/rfc/rfc9116[RFC +9116] and RSR security standards._ diff --git a/packages/Axiom.jl/SECURITY.md b/packages/Axiom.jl/SECURITY.md deleted file mode 100644 index 0aa4b2ae0..000000000 --- a/packages/Axiom.jl/SECURITY.md +++ /dev/null @@ -1,128 +0,0 @@ - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly. - -### How to Report - -**DO NOT** open a public GitHub issue for security vulnerabilities. - -Instead, please report security issues via: - -1. **Email**: security@axiom-jl.org (preferred) -2. **GitLab Security Advisory**: Use the confidential issue feature -3. **PGP Encrypted Email**: See `.well-known/security.txt` for our PGP key - -### What to Include - -Please include the following in your report: - -- Description of the vulnerability -- Steps to reproduce -- Potential impact assessment -- Any suggested fixes (optional) - -### Response Timeline - -| Action | Timeline | -|--------|----------| -| Acknowledgment | Within 48 hours | -| Initial assessment | Within 7 days | -| Status update | Every 14 days | -| Fix release | Depends on severity | - -### Severity Levels - -| Severity | Description | Target Fix Time | -|----------|-------------|-----------------| -| Critical | Remote code execution, data breach | 24-72 hours | -| High | Privilege escalation, significant data exposure | 7 days | -| Medium | Limited data exposure, DoS | 30 days | -| Low | Minor issues, hardening | 90 days | - -## Security Measures - -### Code Security - -- **Memory Safety**: Rust and Zig backends provide memory safety guarantees -- **Type Safety**: Julia's type system prevents many classes of bugs -- **Formal Verification**: `@prove` macro enables mathematical correctness proofs -- **Runtime Checks**: `@ensure` macro validates invariants at runtime - -### Supply Chain Security - -- **Dependency Auditing**: Regular `cargo audit` and `cargo deny` checks -- **SBOM Generation**: Software Bill of Materials available -- **Reproducible Builds**: Nix flake ensures reproducibility -- **Signed Releases**: All releases are signed with GPG - -### Development Practices - -- **Code Review**: All changes require review -- **CI/CD Security**: Automated security scanning in pipeline -- **Secrets Management**: No secrets in repository -- **SPDX Headers**: All source files have license headers - -## Security Features for Users - -### Verification System - -Axiom.jl provides built-in security features for ML models: - -```julia -# Runtime bounds checking -@ensure all(0 .≤ output .≤ 1) "Output must be valid probabilities" - -# Formal verification -@prove BoundedOutputs(0.0, 1.0) model - -# Verification certificates -cert = generate_certificate(model, properties) -``` - -### Deterministic Inference - -For safety-critical applications: - -```julia -Axiom.set_deterministic!(true) # Reproducible results -``` - -### Input Validation - -```julia -@ensure valid_input(x) "Input validation failed" -@ensure no_nan(x) "Input contains NaN values" -``` - -## Security Advisories - -Security advisories are published at: - -- GitHub Security Advisories -- `.well-known/security.txt` -- Mailing list (security-announce@axiom-jl.org) - -## Acknowledgments - -We thank the following security researchers for responsible disclosure: - -*No vulnerabilities reported yet.* - -## Contact - -- Security Team: security@axiom-jl.org -- PGP Key: See `.well-known/security.txt` -- Response Team: See `MAINTAINERS.md` - ---- - -*This security policy follows [RFC 9116](https://www.rfc-editor.org/rfc/rfc9116) and RSR security standards.* diff --git a/packages/Axiom.jl/SONNET-TASKS.adoc b/packages/Axiom.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..b450c9c7f --- /dev/null +++ b/packages/Axiom.jl/SONNET-TASKS.adoc @@ -0,0 +1,436 @@ +== SONNET-TASKS.md — Axiom.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, open-items, and +placeholder code in this repo. *Honest completion before this file:* +~45-50% (STATE.scm claims 65% — overstated) +____ + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. *Read this entire file before starting any task.* +. *Do tasks in the order listed.* Earlier tasks unblock later ones. +. *After completing each task, run the verification command listed for +that task.* If it fails, fix it before moving on. +. *Do NOT mark a task done unless verification passes.* +. *Update STATE.scm* with honest completion percentages after each task. +. *Commit after each completed task* with message format: +`+fix(component): complete +` +. *Julia version:* 1.10+ (check Project.toml compat) +. *Run full test suite* after every 3 tasks: +`+cd /var$REPOS_DIR/Axiom.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix Autograd — Replace Toy Implementation (HIGHEST PRIORITY) + +*Files:* `+src/autograd/gradient.jl+`, `+src/autograd/tape.jl+` + +*Problem:* The autograd system is ~30% complete. `+backward!()+` only +handles trivial topological sort with no real gradient computation. No +support for matrix ops, broadcasting, reshaping. The code itself admits: +"`This is a minimal implementation - production would use Zygote.jl or +Enzyme.jl`" + +*What to do:* 1. Add `+Zygote+` to `+[deps]+` in `+Project.toml+` (NOT +weakdeps — this is core functionality) 2. Rewrite +`+src/autograd/gradient.jl+` to use Zygote as the backend: - +`+gradient(f, params...)+` should call `+Zygote.gradient(f, params...)+` +- `+backward!(tape)+` should use Zygote’s pullback mechanism - +`+jacobian(f, x)+` should use `+Zygote.jacobian(f, x)+` 3. Keep the +`+Tape+` type in `+tape.jl+` as a recording/debugging wrapper around +Zygote, not a replacement 4. Ensure all existing layer types (`+Dense+`, +`+Conv2d+`, etc.) work with the new autograd 5. The training loop in +`+src/training/train.jl+` must work end-to-end with the new autograd + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/Axiom.jl +julia --project=. -e ' +using Axiom +# Test 1: gradient of scalar function +g = Axiom.gradient(x -> x^2 + 3x, 2.0) +@assert g[1] ≈ 7.0 "Scalar gradient failed: got $(g[1]), expected 7.0" + +# Test 2: gradient through Dense layer +d = Axiom.Dense(4, 2) +x = randn(Float32, 4) +loss(m) = sum(m(x)) +g = Axiom.gradient(loss, d) +@assert g !== nothing "Dense gradient returned nothing" +@assert length(g) > 0 "Dense gradient empty" + +# Test 3: jacobian +J = Axiom.jacobian(x -> [x[1]^2, x[1]*x[2]], [3.0, 4.0]) +@assert size(J) == (2, 2) "Jacobian wrong size" +println("AUTOGRAD TESTS PASSED") +' +---- + +''''' + +=== TASK 2: Fix Proof Export — Replace Stubs With Real Implementations + +*Files:* `+src/proof_export.jl+` + +*Problem:* - `+export_lean()+` generates files with `+sorry+` (unproven +placeholder) - `+export_coq()+` generates with `+Admitted+` (unproven +placeholder) - `+export_isabelle()+` generates with `+sledgehammer+` +comment - `+import_lean_certificate()+` → hard +`+error("not yet implemented")+` - `+import_coq_certificate()+` → hard +`+error("not yet implemented")+` - `+import_isabelle_certificate()+` → +hard `+error("not yet implemented")+` - Helper functions do naive string +replacements, not real translation + +*What to do:* 1. *Export functions:* Generate actual proof obligations, +not empty templates. - `+export_lean()+`: Generate Lean 4 syntax with +`+theorem+` declarations and actual proof structure from the +verification properties. Use `+by decide+`, `+by simp+`, `+by omega+` +tactics where applicable for decidable properties (like finite outputs, +bounded values). For undecidable properties, leave `+sorry+` but add a +`+-- PROOF OBLIGATION: +` comment. - `+export_coq()+`: +Generate Coq with `+Theorem+` + `+Proof.+` blocks. Use `+auto+`, +`+omega+`, `+lia+` tactics for arithmetic properties. Mark genuinely +unproven obligations with +`+Admitted (* PROOF OBLIGATION: *)+`. - +`+export_isabelle()+`: Generate Isabelle/HOL with `+lemma+` + +`+proof -+` blocks. Use `+by auto+`, `+by simp+`, `+by arith+` where +applicable. 2. *Import functions:* Parse proof assistant output files: - +`+import_lean_certificate(path)+`: Read a `+.lean+` file, check for +`+sorry+`-free status (no unproven obligations), extract theorem names +and types, return a `+ProofCertificate+` struct. - +`+import_coq_certificate(path)+`: Read a `+.v+` file, check for +`+Admitted+`-free status, extract theorem names. - +`+import_isabelle_certificate(path)+`: Read a `+.thy+` file, check for +`+oops+`-free status, extract lemma names. 3. *Helper functions:* +Replace naive string replacements with proper Julia-to-proof-language +type mapping: - `+Float32+` → `+real+` (Lean), `+R+` (Coq), `+real+` +(Isabelle) - `+Vector{Float32}+` → `+List Real+` (Lean), `+list R+` +(Coq), `+real list+` (Isabelle) - Matrix types → appropriate dependent +types + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/Axiom.jl +julia --project=. -e ' +using Axiom + +# Create a simple verified model +d = Axiom.Dense(4, 2) + +# Test Lean export +lean_code = Axiom.export_lean(d, [:finite_output, :bounded_weights]) +@assert occursin("theorem", lean_code) "Lean export missing theorem declarations" +@assert occursin("Real", lean_code) || occursin("real", lean_code) "Lean export missing type mappings" +println("Lean export:\n", lean_code[1:min(200, length(lean_code))]) + +# Test Coq export +coq_code = Axiom.export_coq(d, [:finite_output]) +@assert occursin("Theorem", coq_code) "Coq export missing Theorem" +println("Coq export:\n", coq_code[1:min(200, length(coq_code))]) + +# Test Isabelle export +isa_code = Axiom.export_isabelle(d, [:finite_output]) +@assert occursin("lemma", isa_code) "Isabelle export missing lemma" +println("Isabelle export:\n", isa_code[1:min(200, length(isa_code))]) + +# Test import (create a mock certificate file) +tmpdir = mktempdir() +lean_cert = joinpath(tmpdir, "test.lean") +write(lean_cert, """ +theorem finite_output : ∀ x : Fin 4 → Real, ∃ y : Fin 2 → Real, True := by + intro x + exact ⟨fun _ => 0, trivial⟩ +""") +cert = Axiom.import_lean_certificate(lean_cert) +@assert cert !== nothing "Import returned nothing" +@assert cert.verified == true || cert.sorry_free == true "Certificate not marked verified" +println("PROOF EXPORT TESTS PASSED") +' +---- + +''''' + +=== TASK 3: Fix HuggingFace Integration — Implement or Remove (DONE) + +*STATUS: DONE* *ACTION: REMOVED* + +*REASONING:* The HuggingFace integration was not implemented and the +file containing the function stubs has been removed from the repository. +Per the task instructions, this feature has been removed. + +*Original Description:* > *Files:* `+src/integrations/huggingface.jl+`, +`+src/Axiom.jl+` (line ~130 where it’s commented out) > > *Problem:* > - +Module is *disabled* (commented out in main module) > - +`+build_gpt2()+`, `+build_vit()+`, `+build_resnet()+` → hard +`+error("not implemented")+` > - `+load_weights!()+` → empty function +body > - `+load_tokenizer()+` → returns `+nothing+` > - "`subtle parsing +issue`" mentioned but not fixed > > *What to do — pick ONE of these +approaches:* > > *Option A (RECOMMENDED): Implement properly* > 1. Fix +the "`subtle parsing issue`" in shapes.jl that breaks integration > 2. +Uncomment the `+include("integrations/huggingface.jl")+` in +`+src/Axiom.jl+` > 3. Implement `+build_gpt2()+`: Multi-head attention + +feed-forward blocks using existing Dense/LayerNorm layers > 4. Implement +`+build_vit()+`: Patch embedding + transformer encoder using existing +layers > 5. Implement `+build_resnet()+`: Conv2d + BatchNorm + residual +connections using existing layers > 6. Implement `+load_weights!()+`: +Parse PyTorch `+.bin+` files (they’re zip files containing numpy arrays +— use `+ZipFile.jl+` + manual binary parsing, or use `+PyCall+` via the +existing weak dependency) > 7. Implement `+load_tokenizer()+`: Parse +HuggingFace `+tokenizer.json+` format (JSON with vocab + merges) > > +*Option B: Remove cleanly* > If implementation is too complex, remove +the file entirely: > 1. Delete `+src/integrations/huggingface.jl+` > 2. +Remove all HuggingFace exports from `+src/Axiom.jl+` > 3. Remove +`+PyCall+` from `+[weakdeps]+` in Project.toml > 4. Remove +`+AxiomPyTorchExt+` from `+[extensions]+` > 5. Delete +`+ext/AxiomPyTorchExt.jl+` > 6. Update README.adoc to remove HuggingFace +claims > > *Do NOT leave it in its current broken-but-committed state.* +> > *Verification (Option A):* > +`+julia > cd /var$REPOS_DIR/Axiom.jl > julia --project=. -e ' > using Axiom > > # Test architecture builders (without weights — just structure) > gpt2 = Axiom.build_gpt2(; n_layers=2, n_heads=2, d_model=64, vocab_size=100) > @assert gpt2 !== nothing "GPT-2 builder returned nothing" > > vit = Axiom.build_vit(; n_layers=2, n_heads=2, d_model=64, patch_size=16, image_size=224, n_classes=10) > @assert vit !== nothing "ViT builder returned nothing" > > resnet = Axiom.build_resnet(; layers=[2,2,2,2], n_classes=10) > @assert resnet !== nothing "ResNet builder returned nothing" > > println("HUGGINGFACE INTEGRATION TESTS PASSED") > ' >+` +> > *Verification (Option B):* > +`+julia > cd /var$REPOS_DIR/Axiom.jl > julia --project=. -e ' > using Axiom > # Verify no broken exports > @assert !isdefined(Axiom, :load_from_huggingface) "HuggingFace not cleanly removed" > @assert !isdefined(Axiom, :build_gpt2) "GPT-2 not cleanly removed" > println("CLEAN REMOVAL VERIFIED") > ' >+` + +''''' + +=== TASK 4: Fix GPU Backend Stubs + +*Files:* `+src/backends/gpu_hooks.jl+`, `+ext/AxiomCUDAExt.jl+`, +`+ext/AxiomAMDGPUExt.jl+`, `+ext/AxiomMetalExt.jl+` + +*Problem:* - `+cuda_available()+` returns `+nothing+` (not even +`+false+`) - `+rocm_available()+` returns hardcoded `+false+` - +`+cuda_device_count()+` returns hardcoded `+0+` - Extension files exist +but are minimal + +*What to do:* 1. Fix `+gpu_hooks.jl+` to return proper `+false+` (not +`+nothing+`) when no GPU package loaded 2. Implement proper detection +via extension loading: - When CUDA.jl is loaded → `+AxiomCUDAExt+` +activates → `+cuda_available()+` calls `+CUDA.functional()+` - When +AMDGPU.jl is loaded → `+AxiomAMDGPUExt+` activates → +`+rocm_available()+` calls `+AMDGPU.functional()+` - When Metal.jl is +loaded → `+AxiomMetalExt+` activates → `+metal_available()+` calls +`+Metal.functional()+` 3. Each extension should implement: - +`+gpu_available()+` → `+Bool+` - `+gpu_device_count()+` → `+Int+` - +`+to_gpu(tensor)+` → GPU tensor - `+from_gpu(tensor)+` → CPU tensor 4. +The default (no extension loaded) must return `+false+`/`+0+` +consistently, never `+nothing+` + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/Axiom.jl +julia --project=. -e ' +using Axiom + +# Without GPU packages loaded, these should return false/0 (not nothing, not error) +@assert Axiom.cuda_available() === false "cuda_available() should be false, got $(Axiom.cuda_available())" +@assert Axiom.rocm_available() === false "rocm_available() should be false, got $(Axiom.rocm_available())" +@assert Axiom.metal_available() === false "metal_available() should be false, got $(Axiom.metal_available())" +@assert Axiom.cuda_device_count() === 0 "cuda_device_count() should be 0, got $(Axiom.cuda_device_count())" +println("GPU HOOKS TESTS PASSED (no GPU packages loaded)") +' +---- + +''''' + +=== TASK 5: Fix Model Metadata Placeholders + +*File:* `+src/model_metadata.jl+` + +*Problem:* - Line ~212: `+verify_and_claim!()+` sets `+verified = true+` +without actually verifying anything. Comment says +`+# open-item: Actually run verification via @prove+` - +`+input_shape_from_model()+` returns `+(0,)+` placeholder - +`+output_shape_from_model()+` returns `+(0,)+` placeholder + +*What to do:* 1. `+verify_and_claim!()+`: Actually call the verification +system. If `+@prove+` macro / verification checker is available, run it. +If verification fails, set `+verified = false+` and include failure +reason. 2. `+input_shape_from_model(model)+`: Inspect model’s first +layer to determine expected input shape. For `+Dense(in, out)+` → +`+(in,)+`. For `+Conv2d(in_ch, ...)+` with known kernel → derive from +channel count. 3. `+output_shape_from_model(model)+`: Inspect model’s +last layer to determine output shape. For `+Dense(in, out)+` → +`+(out,)+`. + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/Axiom.jl +julia --project=. -e ' +using Axiom +d = Axiom.Dense(10, 5) + +# Shape inference +in_shape = Axiom.input_shape_from_model(d) +@assert in_shape == (10,) "Expected (10,), got $in_shape" + +out_shape = Axiom.output_shape_from_model(d) +@assert out_shape == (5,) "Expected (5,), got $out_shape" + +println("MODEL METADATA TESTS PASSED") +' +---- + +''''' + +=== TASK 6: Fix Conv3d Stub + +*File:* `+src/layers/conv.jl+` (line ~94) + +*Problem:* `+Conv3d+` throws +`+error("Conv3d is conceptually supported but not yet implemented")+` + +*What to do:* 1. Implement `+Conv3d+` following the same pattern as +`+Conv2d+` but for 5D tensors (batch, channels, depth, height, width) 2. +Support same parameters: kernel_size, stride, padding, dilation 3. +Forward pass: 3D convolution using nested loops or `+NNlib.conv+` if +available + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/Axiom.jl +julia --project=. -e ' +using Axiom +c = Axiom.Conv3d(3, 16; kernel_size=(3,3,3), stride=(1,1,1), padding=(1,1,1)) +x = randn(Float32, 3, 8, 8, 8, 1) # channels, D, H, W, batch +y = c(x) +@assert size(y, 1) == 16 "Wrong output channels" +@assert size(y, 5) == 1 "Wrong batch dim" +println("CONV3D TESTS PASSED") +' +---- + +''''' + +=== TASK 7: Fix SMT Extension Dead Code (DONE) + +*STATUS: DONE* *ACTION: FIXED* + +*REASONING:* The SMT extension has been fully enabled in +`+Project.toml+`. Redundant/broken Rust FFI code was removed, and parse +errors in `+SMTLib.jl+` were fixed. AST-based block unwrapping was +implemented in `+prove.jl+` to support complex `+@prove+` blocks. + +*Original Description:* > *File:* `+ext/AxiomSMTExt.jl+` > > *Problem:* +Lines ~56-68 have unreachable return statements after an early return at +line ~54. + +''''' + +=== TASK 8: Fix Zig Backend — Either Implement or Remove (DONE) + +*STATUS: DONE* *ACTION: IMPLEMENTED* + +*REASONING:* The Zig build system has been updated to 0.15.2, +compilation errors fixed, and a full Julia FFI bridge implemented in +`+src/backends/zig_ffi.jl+`. End-to-end verification of matrix +multiplication confirmed the backend is functional. + +*Original Description:* > *File:* `+src/backends/zig_ffi.jl+`, +`+zig/src/axiom.zig+` > > *Problem:* All functions throw +`+ArgumentError+` for validation but have no actual `+ccall+` to any Zig +library. The `+ZIG_LIB+` constant references a path that doesn’t exist. + +''''' + +=== TASK 9: Implement Missing PyTorch/ONNX Exports + +*Files:* `+src/Axiom.jl+` (exports `+from_pytorch+`, `+to_onnx+` but +functions don’t exist) + +*Problem:* `+from_pytorch()+` and `+to_onnx()+` are exported in the +module but the functions are not defined anywhere in the codebase. + +*What to do — pick ONE:* + +*Option A: Implement* 1. Create `+src/interop/pytorch.jl+`: +`+from_pytorch(path::String)+` reads a `+.pt+` or `+.pth+` file and +reconstructs an Axiom model 2. Create `+src/interop/onnx.jl+`: +`+to_onnx(model, path::String)+` serializes an Axiom model to ONNX +format 3. Include both from `+src/Axiom.jl+` + +*Option B (RECOMMENDED): Remove exports* 1. Remove `+from_pytorch+` and +`+to_onnx+` from the export list in `+src/Axiom.jl+` 2. Add a doc +comment explaining these are planned future features 3. Update +README.adoc to remove interop claims + +*Do NOT leave phantom exports that error on use.* + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/Axiom.jl +julia --project=. -e ' +using Axiom +# Check no phantom exports +for sym in [:from_pytorch, :to_onnx] + if isdefined(Axiom, sym) + m = getfield(Axiom, sym) + @assert m isa Function "Export $sym exists but is not a function" + println("$sym: implemented") + else + println("$sym: removed (acceptable)") + end +end +println("INTEROP EXPORTS CHECK PASSED") +' +---- + +''''' + +=== TASK 10: Update STATE.scm With Honest Numbers + +*File:* `+.machine_readable/STATE.scm+` + +*After completing all above tasks*, update STATE.scm with honest +completion percentages. The format should reflect what was actually +implemented, not aspirational numbers. + +*Verification:* Read the file and confirm no component claims >90% +unless it truly is >90% complete. + +''''' + +=== FINAL VERIFICATION — RUN AFTER ALL TASKS + +[source,bash] +---- +cd /var$REPOS_DIR/Axiom.jl + +# 1. Full test suite +julia --project=. -e 'using Pkg; Pkg.test()' + +# 2. Check no remaining hard-error stubs +grep -rn 'error(".*not.*implement' src/ ext/ || echo "NO HARD ERROR STUBS REMAINING" + +# 3. Check no phantom exports +julia --project=. -e ' +using Axiom +for name in names(Axiom) + try + getfield(Axiom, name) + catch e + println("BROKEN EXPORT: $name — $e") + end +end +println("ALL EXPORTS VALID") +' + +# 4. Check no open-item/fix-item landmines +grep -rn 'open-item\|fix-item\|HACK\|XXX' src/ | head -20 +echo "(Some open-items are acceptable for future enhancements, but none should be for core functionality)" +---- diff --git a/packages/Axiom.jl/SONNET-TASKS.md b/packages/Axiom.jl/SONNET-TASKS.md deleted file mode 100644 index 591a52dc7..000000000 --- a/packages/Axiom.jl/SONNET-TASKS.md +++ /dev/null @@ -1,415 +0,0 @@ -# SONNET-TASKS.md — Axiom.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, open-items, and placeholder code in this repo. -> **Honest completion before this file:** ~45-50% (STATE.scm claims 65% — overstated) - ---- - -## GROUND RULES FOR SONNET - -1. **Read this entire file before starting any task.** -2. **Do tasks in the order listed.** Earlier tasks unblock later ones. -3. **After completing each task, run the verification command listed for that task.** If it fails, fix it before moving on. -4. **Do NOT mark a task done unless verification passes.** -5. **Update STATE.scm** with honest completion percentages after each task. -6. **Commit after each completed task** with message format: `fix(component): complete ` -7. **Julia version:** 1.10+ (check Project.toml compat) -8. **Run full test suite** after every 3 tasks: `cd /var$REPOS_DIR/Axiom.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix Autograd — Replace Toy Implementation (HIGHEST PRIORITY) - -**Files:** `src/autograd/gradient.jl`, `src/autograd/tape.jl` - -**Problem:** The autograd system is ~30% complete. `backward!()` only handles trivial topological sort with no real gradient computation. No support for matrix ops, broadcasting, reshaping. The code itself admits: "This is a minimal implementation - production would use Zygote.jl or Enzyme.jl" - -**What to do:** -1. Add `Zygote` to `[deps]` in `Project.toml` (NOT weakdeps — this is core functionality) -2. Rewrite `src/autograd/gradient.jl` to use Zygote as the backend: - - `gradient(f, params...)` should call `Zygote.gradient(f, params...)` - - `backward!(tape)` should use Zygote's pullback mechanism - - `jacobian(f, x)` should use `Zygote.jacobian(f, x)` -3. Keep the `Tape` type in `tape.jl` as a recording/debugging wrapper around Zygote, not a replacement -4. Ensure all existing layer types (`Dense`, `Conv2d`, etc.) work with the new autograd -5. The training loop in `src/training/train.jl` must work end-to-end with the new autograd - -**Verification:** -```julia -cd /var$REPOS_DIR/Axiom.jl -julia --project=. -e ' -using Axiom -# Test 1: gradient of scalar function -g = Axiom.gradient(x -> x^2 + 3x, 2.0) -@assert g[1] ≈ 7.0 "Scalar gradient failed: got $(g[1]), expected 7.0" - -# Test 2: gradient through Dense layer -d = Axiom.Dense(4, 2) -x = randn(Float32, 4) -loss(m) = sum(m(x)) -g = Axiom.gradient(loss, d) -@assert g !== nothing "Dense gradient returned nothing" -@assert length(g) > 0 "Dense gradient empty" - -# Test 3: jacobian -J = Axiom.jacobian(x -> [x[1]^2, x[1]*x[2]], [3.0, 4.0]) -@assert size(J) == (2, 2) "Jacobian wrong size" -println("AUTOGRAD TESTS PASSED") -' -``` - ---- - -## TASK 2: Fix Proof Export — Replace Stubs With Real Implementations - -**Files:** `src/proof_export.jl` - -**Problem:** -- `export_lean()` generates files with `sorry` (unproven placeholder) -- `export_coq()` generates with `Admitted` (unproven placeholder) -- `export_isabelle()` generates with `sledgehammer` comment -- `import_lean_certificate()` → hard `error("not yet implemented")` -- `import_coq_certificate()` → hard `error("not yet implemented")` -- `import_isabelle_certificate()` → hard `error("not yet implemented")` -- Helper functions do naive string replacements, not real translation - -**What to do:** -1. **Export functions:** Generate actual proof obligations, not empty templates. - - `export_lean()`: Generate Lean 4 syntax with `theorem` declarations and actual proof structure from the verification properties. Use `by decide`, `by simp`, `by omega` tactics where applicable for decidable properties (like finite outputs, bounded values). For undecidable properties, leave `sorry` but add a `-- PROOF OBLIGATION: ` comment. - - `export_coq()`: Generate Coq with `Theorem` + `Proof.` blocks. Use `auto`, `omega`, `lia` tactics for arithmetic properties. Mark genuinely unproven obligations with `Admitted (* PROOF OBLIGATION: *)`. - - `export_isabelle()`: Generate Isabelle/HOL with `lemma` + `proof -` blocks. Use `by auto`, `by simp`, `by arith` where applicable. -2. **Import functions:** Parse proof assistant output files: - - `import_lean_certificate(path)`: Read a `.lean` file, check for `sorry`-free status (no unproven obligations), extract theorem names and types, return a `ProofCertificate` struct. - - `import_coq_certificate(path)`: Read a `.v` file, check for `Admitted`-free status, extract theorem names. - - `import_isabelle_certificate(path)`: Read a `.thy` file, check for `oops`-free status, extract lemma names. -3. **Helper functions:** Replace naive string replacements with proper Julia-to-proof-language type mapping: - - `Float32` → `real` (Lean), `R` (Coq), `real` (Isabelle) - - `Vector{Float32}` → `List Real` (Lean), `list R` (Coq), `real list` (Isabelle) - - Matrix types → appropriate dependent types - -**Verification:** -```julia -cd /var$REPOS_DIR/Axiom.jl -julia --project=. -e ' -using Axiom - -# Create a simple verified model -d = Axiom.Dense(4, 2) - -# Test Lean export -lean_code = Axiom.export_lean(d, [:finite_output, :bounded_weights]) -@assert occursin("theorem", lean_code) "Lean export missing theorem declarations" -@assert occursin("Real", lean_code) || occursin("real", lean_code) "Lean export missing type mappings" -println("Lean export:\n", lean_code[1:min(200, length(lean_code))]) - -# Test Coq export -coq_code = Axiom.export_coq(d, [:finite_output]) -@assert occursin("Theorem", coq_code) "Coq export missing Theorem" -println("Coq export:\n", coq_code[1:min(200, length(coq_code))]) - -# Test Isabelle export -isa_code = Axiom.export_isabelle(d, [:finite_output]) -@assert occursin("lemma", isa_code) "Isabelle export missing lemma" -println("Isabelle export:\n", isa_code[1:min(200, length(isa_code))]) - -# Test import (create a mock certificate file) -tmpdir = mktempdir() -lean_cert = joinpath(tmpdir, "test.lean") -write(lean_cert, """ -theorem finite_output : ∀ x : Fin 4 → Real, ∃ y : Fin 2 → Real, True := by - intro x - exact ⟨fun _ => 0, trivial⟩ -""") -cert = Axiom.import_lean_certificate(lean_cert) -@assert cert !== nothing "Import returned nothing" -@assert cert.verified == true || cert.sorry_free == true "Certificate not marked verified" -println("PROOF EXPORT TESTS PASSED") -' -``` - ---- - -## TASK 3: Fix HuggingFace Integration — Implement or Remove (DONE) - -**STATUS: DONE** -**ACTION: REMOVED** - -**REASONING:** The HuggingFace integration was not implemented and the file containing the function stubs has been removed from the repository. Per the task instructions, this feature has been removed. - -**Original Description:** -> **Files:** `src/integrations/huggingface.jl`, `src/Axiom.jl` (line ~130 where it's commented out) -> -> **Problem:** -> - Module is **disabled** (commented out in main module) -> - `build_gpt2()`, `build_vit()`, `build_resnet()` → hard `error("not implemented")` -> - `load_weights!()` → empty function body -> - `load_tokenizer()` → returns `nothing` -> - "subtle parsing issue" mentioned but not fixed -> -> **What to do — pick ONE of these approaches:** -> -> **Option A (RECOMMENDED): Implement properly** -> 1. Fix the "subtle parsing issue" in shapes.jl that breaks integration -> 2. Uncomment the `include("integrations/huggingface.jl")` in `src/Axiom.jl` -> 3. Implement `build_gpt2()`: Multi-head attention + feed-forward blocks using existing Dense/LayerNorm layers -> 4. Implement `build_vit()`: Patch embedding + transformer encoder using existing layers -> 5. Implement `build_resnet()`: Conv2d + BatchNorm + residual connections using existing layers -> 6. Implement `load_weights!()`: Parse PyTorch `.bin` files (they're zip files containing numpy arrays — use `ZipFile.jl` + manual binary parsing, or use `PyCall` via the existing weak dependency) -> 7. Implement `load_tokenizer()`: Parse HuggingFace `tokenizer.json` format (JSON with vocab + merges) -> -> **Option B: Remove cleanly** -> If implementation is too complex, remove the file entirely: -> 1. Delete `src/integrations/huggingface.jl` -> 2. Remove all HuggingFace exports from `src/Axiom.jl` -> 3. Remove `PyCall` from `[weakdeps]` in Project.toml -> 4. Remove `AxiomPyTorchExt` from `[extensions]` -> 5. Delete `ext/AxiomPyTorchExt.jl` -> 6. Update README.adoc to remove HuggingFace claims -> -> **Do NOT leave it in its current broken-but-committed state.** -> -> **Verification (Option A):** -> ```julia -> cd /var$REPOS_DIR/Axiom.jl -> julia --project=. -e ' -> using Axiom -> -> # Test architecture builders (without weights — just structure) -> gpt2 = Axiom.build_gpt2(; n_layers=2, n_heads=2, d_model=64, vocab_size=100) -> @assert gpt2 !== nothing "GPT-2 builder returned nothing" -> -> vit = Axiom.build_vit(; n_layers=2, n_heads=2, d_model=64, patch_size=16, image_size=224, n_classes=10) -> @assert vit !== nothing "ViT builder returned nothing" -> -> resnet = Axiom.build_resnet(; layers=[2,2,2,2], n_classes=10) -> @assert resnet !== nothing "ResNet builder returned nothing" -> -> println("HUGGINGFACE INTEGRATION TESTS PASSED") -> ' -> ``` -> -> **Verification (Option B):** -> ```julia -> cd /var$REPOS_DIR/Axiom.jl -> julia --project=. -e ' -> using Axiom -> # Verify no broken exports -> @assert !isdefined(Axiom, :load_from_huggingface) "HuggingFace not cleanly removed" -> @assert !isdefined(Axiom, :build_gpt2) "GPT-2 not cleanly removed" -> println("CLEAN REMOVAL VERIFIED") -> ' -> ``` - ---- - -## TASK 4: Fix GPU Backend Stubs - -**Files:** `src/backends/gpu_hooks.jl`, `ext/AxiomCUDAExt.jl`, `ext/AxiomAMDGPUExt.jl`, `ext/AxiomMetalExt.jl` - -**Problem:** -- `cuda_available()` returns `nothing` (not even `false`) -- `rocm_available()` returns hardcoded `false` -- `cuda_device_count()` returns hardcoded `0` -- Extension files exist but are minimal - -**What to do:** -1. Fix `gpu_hooks.jl` to return proper `false` (not `nothing`) when no GPU package loaded -2. Implement proper detection via extension loading: - - When CUDA.jl is loaded → `AxiomCUDAExt` activates → `cuda_available()` calls `CUDA.functional()` - - When AMDGPU.jl is loaded → `AxiomAMDGPUExt` activates → `rocm_available()` calls `AMDGPU.functional()` - - When Metal.jl is loaded → `AxiomMetalExt` activates → `metal_available()` calls `Metal.functional()` -3. Each extension should implement: - - `gpu_available()` → `Bool` - - `gpu_device_count()` → `Int` - - `to_gpu(tensor)` → GPU tensor - - `from_gpu(tensor)` → CPU tensor -4. The default (no extension loaded) must return `false`/`0` consistently, never `nothing` - -**Verification:** -```julia -cd /var$REPOS_DIR/Axiom.jl -julia --project=. -e ' -using Axiom - -# Without GPU packages loaded, these should return false/0 (not nothing, not error) -@assert Axiom.cuda_available() === false "cuda_available() should be false, got $(Axiom.cuda_available())" -@assert Axiom.rocm_available() === false "rocm_available() should be false, got $(Axiom.rocm_available())" -@assert Axiom.metal_available() === false "metal_available() should be false, got $(Axiom.metal_available())" -@assert Axiom.cuda_device_count() === 0 "cuda_device_count() should be 0, got $(Axiom.cuda_device_count())" -println("GPU HOOKS TESTS PASSED (no GPU packages loaded)") -' -``` - ---- - -## TASK 5: Fix Model Metadata Placeholders - -**File:** `src/model_metadata.jl` - -**Problem:** -- Line ~212: `verify_and_claim!()` sets `verified = true` without actually verifying anything. Comment says `# open-item: Actually run verification via @prove` -- `input_shape_from_model()` returns `(0,)` placeholder -- `output_shape_from_model()` returns `(0,)` placeholder - -**What to do:** -1. `verify_and_claim!()`: Actually call the verification system. If `@prove` macro / verification checker is available, run it. If verification fails, set `verified = false` and include failure reason. -2. `input_shape_from_model(model)`: Inspect model's first layer to determine expected input shape. For `Dense(in, out)` → `(in,)`. For `Conv2d(in_ch, ...)` with known kernel → derive from channel count. -3. `output_shape_from_model(model)`: Inspect model's last layer to determine output shape. For `Dense(in, out)` → `(out,)`. - -**Verification:** -```julia -cd /var$REPOS_DIR/Axiom.jl -julia --project=. -e ' -using Axiom -d = Axiom.Dense(10, 5) - -# Shape inference -in_shape = Axiom.input_shape_from_model(d) -@assert in_shape == (10,) "Expected (10,), got $in_shape" - -out_shape = Axiom.output_shape_from_model(d) -@assert out_shape == (5,) "Expected (5,), got $out_shape" - -println("MODEL METADATA TESTS PASSED") -' -``` - ---- - -## TASK 6: Fix Conv3d Stub - -**File:** `src/layers/conv.jl` (line ~94) - -**Problem:** `Conv3d` throws `error("Conv3d is conceptually supported but not yet implemented")` - -**What to do:** -1. Implement `Conv3d` following the same pattern as `Conv2d` but for 5D tensors (batch, channels, depth, height, width) -2. Support same parameters: kernel_size, stride, padding, dilation -3. Forward pass: 3D convolution using nested loops or `NNlib.conv` if available - -**Verification:** -```julia -cd /var$REPOS_DIR/Axiom.jl -julia --project=. -e ' -using Axiom -c = Axiom.Conv3d(3, 16; kernel_size=(3,3,3), stride=(1,1,1), padding=(1,1,1)) -x = randn(Float32, 3, 8, 8, 8, 1) # channels, D, H, W, batch -y = c(x) -@assert size(y, 1) == 16 "Wrong output channels" -@assert size(y, 5) == 1 "Wrong batch dim" -println("CONV3D TESTS PASSED") -' -``` - ---- - -## TASK 7: Fix SMT Extension Dead Code (DONE) - -**STATUS: DONE** -**ACTION: FIXED** - -**REASONING:** The SMT extension has been fully enabled in `Project.toml`. Redundant/broken Rust FFI code was removed, and parse errors in `SMTLib.jl` were fixed. AST-based block unwrapping was implemented in `prove.jl` to support complex `@prove` blocks. - -**Original Description:** -> **File:** `ext/AxiomSMTExt.jl` -> -> **Problem:** Lines ~56-68 have unreachable return statements after an early return at line ~54. - - ---- - -## TASK 8: Fix Zig Backend — Either Implement or Remove (DONE) - -**STATUS: DONE** -**ACTION: IMPLEMENTED** - -**REASONING:** The Zig build system has been updated to 0.15.2, compilation errors fixed, and a full Julia FFI bridge implemented in `src/backends/zig_ffi.jl`. End-to-end verification of matrix multiplication confirmed the backend is functional. - -**Original Description:** -> **File:** `src/backends/zig_ffi.jl`, `zig/src/axiom.zig` -> -> **Problem:** All functions throw `ArgumentError` for validation but have no actual `ccall` to any Zig library. The `ZIG_LIB` constant references a path that doesn't exist. - - ---- - -## TASK 9: Implement Missing PyTorch/ONNX Exports - -**Files:** `src/Axiom.jl` (exports `from_pytorch`, `to_onnx` but functions don't exist) - -**Problem:** `from_pytorch()` and `to_onnx()` are exported in the module but the functions are not defined anywhere in the codebase. - -**What to do — pick ONE:** - -**Option A: Implement** -1. Create `src/interop/pytorch.jl`: `from_pytorch(path::String)` reads a `.pt` or `.pth` file and reconstructs an Axiom model -2. Create `src/interop/onnx.jl`: `to_onnx(model, path::String)` serializes an Axiom model to ONNX format -3. Include both from `src/Axiom.jl` - -**Option B (RECOMMENDED): Remove exports** -1. Remove `from_pytorch` and `to_onnx` from the export list in `src/Axiom.jl` -2. Add a doc comment explaining these are planned future features -3. Update README.adoc to remove interop claims - -**Do NOT leave phantom exports that error on use.** - -**Verification:** -```julia -cd /var$REPOS_DIR/Axiom.jl -julia --project=. -e ' -using Axiom -# Check no phantom exports -for sym in [:from_pytorch, :to_onnx] - if isdefined(Axiom, sym) - m = getfield(Axiom, sym) - @assert m isa Function "Export $sym exists but is not a function" - println("$sym: implemented") - else - println("$sym: removed (acceptable)") - end -end -println("INTEROP EXPORTS CHECK PASSED") -' -``` - ---- - -## TASK 10: Update STATE.scm With Honest Numbers - -**File:** `.machine_readable/STATE.scm` - -**After completing all above tasks**, update STATE.scm with honest completion percentages. The format should reflect what was actually implemented, not aspirational numbers. - -**Verification:** Read the file and confirm no component claims >90% unless it truly is >90% complete. - ---- - -## FINAL VERIFICATION — RUN AFTER ALL TASKS - -```bash -cd /var$REPOS_DIR/Axiom.jl - -# 1. Full test suite -julia --project=. -e 'using Pkg; Pkg.test()' - -# 2. Check no remaining hard-error stubs -grep -rn 'error(".*not.*implement' src/ ext/ || echo "NO HARD ERROR STUBS REMAINING" - -# 3. Check no phantom exports -julia --project=. -e ' -using Axiom -for name in names(Axiom) - try - getfield(Axiom, name) - catch e - println("BROKEN EXPORT: $name — $e") - end -end -println("ALL EXPORTS VALID") -' - -# 4. Check no open-item/fix-item landmines -grep -rn 'open-item\|fix-item\|HACK\|XXX' src/ | head -20 -echo "(Some open-items are acceptable for future enhancements, but none should be for core functionality)" -``` diff --git a/packages/Axiom.jl/TODO-URGENT-COPROCESSOR-CONSOLIDATION.adoc b/packages/Axiom.jl/TODO-URGENT-COPROCESSOR-CONSOLIDATION.adoc new file mode 100644 index 000000000..1b6dc4641 --- /dev/null +++ b/packages/Axiom.jl/TODO-URGENT-COPROCESSOR-CONSOLIDATION.adoc @@ -0,0 +1,77 @@ +== URGENT: Coprocessor Backend Consolidation + +*Date:* 2026-02-27 *Priority:* URGENT *Status:* NOT STARTED + +=== Problem + +`+src/backends/abstract.jl+` is *2,857 lines* mixing 6+ concerns in one +file. Total backend code: 4,346 lines across 4 files. The abstract.jl +monolith is unreadable, untestable, and blocks contributors from +understanding the extension points. + +=== Current State (4 files) + +[width="100%",cols="27%,30%,43%",options="header",] +|=== +|File |Lines |Contents +|`+abstract.jl+` |2,857 |Backend types, SmartBackend router, coprocessor +hooks, layer forwarding, compilation targets — ALL IN ONE FILE + +|`+zig_ffi.jl+` |634 |Zig FFI implementation + +|`+gpu_hooks.jl+` |470 |CUDA/Metal/ROCm hooks + +|`+julia_backend.jl+` |385 |Pure Julia reference impl +|=== + +=== Proposed Consolidation (7 files) + +[width="100%",cols="33%,32%,35%",options="header",] +|=== +|New File |Contents |Est. Lines +|`+abstract.jl+` (REDUCED) |Only: AbstractBackend base, 15 backend type +defs, CompilationTarget, registry |~200 + +|`+compute.jl+` |All Julia backend activation implementations (relu, +sigmoid, gelu, etc.) |~400 + +|`+accelerators.jl+` |GPU hooks (CUDA/Metal/ROCm), +TPU/NPU/DSP/PPU/FPGA/VPU/QPU/Crypto defs |~350 + +|`+coprocessor_hooks.jl+` |9 coprocessor extension hooks + fallback +dispatch |~130 + +|`+routing.jl+` |SmartBackend dispatch tables + backend-aware layer +forwarding |~250 + +|`+zig_ffi.jl+` (KEEP) |Zig FFI — already well-scoped |634 + +|`+julia_backend.jl+` (KEEP) |Reference impl — already well-scoped |385 +|=== + +=== 15 Backend Types (for reference) + +JuliaBackend, ZigBackend, CUDABackend, MetalBackend, ROCmBackend, +TPUBackend, NPUBackend, DSPBackend, PPUBackend, MathBackend, +FPGABackend, VPUBackend, QPUBackend, CryptoBackend, SmartBackend + +=== 9 Coprocessor Hooks + +`+backend_coprocessor_matmul+`, `+_conv2d+`, `+_relu+`, `+_softmax+`, +`+_batchnorm+`, `+_layernorm+`, `+_maxpool2d+`, `+_avgpool2d+`, +`+_global_avgpool2d+` + +=== Motivation + +IDApTIK’s coprocessors were consolidated from 10 files to 3 on +2026-02-27 (Compute, Security, IO). Same pattern applies here: group by +concern, not by implementation detail. The 2,857-line abstract.jl is the +worst offender — it needs to be split into at least 4 focused files. + +=== Rules + +* Every backend type, every hook, every activation MUST be preserved +* SmartBackend dispatch tables (from 2026-02-20 benchmarks) must not +change +* Zero functionality loss — only file reorganisation +* Update `+include()+` statements in the module wrapper accordingly diff --git a/packages/Axiom.jl/TODO-URGENT-COPROCESSOR-CONSOLIDATION.md b/packages/Axiom.jl/TODO-URGENT-COPROCESSOR-CONSOLIDATION.md deleted file mode 100644 index 7eb9247e6..000000000 --- a/packages/Axiom.jl/TODO-URGENT-COPROCESSOR-CONSOLIDATION.md +++ /dev/null @@ -1,58 +0,0 @@ -# URGENT: Coprocessor Backend Consolidation - -**Date:** 2026-02-27 -**Priority:** URGENT -**Status:** NOT STARTED - -## Problem - -`src/backends/abstract.jl` is **2,857 lines** mixing 6+ concerns in one file. -Total backend code: 4,346 lines across 4 files. The abstract.jl monolith is -unreadable, untestable, and blocks contributors from understanding the -extension points. - -## Current State (4 files) - -| File | Lines | Contents | -|------|-------|----------| -| `abstract.jl` | 2,857 | Backend types, SmartBackend router, coprocessor hooks, layer forwarding, compilation targets — ALL IN ONE FILE | -| `zig_ffi.jl` | 634 | Zig FFI implementation | -| `gpu_hooks.jl` | 470 | CUDA/Metal/ROCm hooks | -| `julia_backend.jl` | 385 | Pure Julia reference impl | - -## Proposed Consolidation (7 files) - -| New File | Contents | Est. Lines | -|----------|----------|-----------| -| `abstract.jl` (REDUCED) | Only: AbstractBackend base, 15 backend type defs, CompilationTarget, registry | ~200 | -| `compute.jl` | All Julia backend activation implementations (relu, sigmoid, gelu, etc.) | ~400 | -| `accelerators.jl` | GPU hooks (CUDA/Metal/ROCm), TPU/NPU/DSP/PPU/FPGA/VPU/QPU/Crypto defs | ~350 | -| `coprocessor_hooks.jl` | 9 coprocessor extension hooks + fallback dispatch | ~130 | -| `routing.jl` | SmartBackend dispatch tables + backend-aware layer forwarding | ~250 | -| `zig_ffi.jl` (KEEP) | Zig FFI — already well-scoped | 634 | -| `julia_backend.jl` (KEEP) | Reference impl — already well-scoped | 385 | - -## 15 Backend Types (for reference) - -JuliaBackend, ZigBackend, CUDABackend, MetalBackend, ROCmBackend, -TPUBackend, NPUBackend, DSPBackend, PPUBackend, MathBackend, -FPGABackend, VPUBackend, QPUBackend, CryptoBackend, SmartBackend - -## 9 Coprocessor Hooks - -`backend_coprocessor_matmul`, `_conv2d`, `_relu`, `_softmax`, -`_batchnorm`, `_layernorm`, `_maxpool2d`, `_avgpool2d`, `_global_avgpool2d` - -## Motivation - -IDApTIK's coprocessors were consolidated from 10 files to 3 on 2026-02-27 -(Compute, Security, IO). Same pattern applies here: group by concern, -not by implementation detail. The 2,857-line abstract.jl is the worst -offender — it needs to be split into at least 4 focused files. - -## Rules - -- Every backend type, every hook, every activation MUST be preserved -- SmartBackend dispatch tables (from 2026-02-20 benchmarks) must not change -- Zero functionality loss — only file reorganisation -- Update `include()` statements in the module wrapper accordingly diff --git a/packages/Axiom.jl/TOPOLOGY.adoc b/packages/Axiom.jl/TOPOLOGY.adoc new file mode 100644 index 000000000..7967b4b2a --- /dev/null +++ b/packages/Axiom.jl/TOPOLOGY.adoc @@ -0,0 +1,294 @@ +== Axiom.jl - System Architecture + +.... + Axiom.jl - Provably Correct Machine Learning + ============================================ + + User API Layer + +-----------------------------------------------------------------+ + | @axiom @ensure @prove* Sequential/Chain/Pipeline | + | Dense Conv2d BatchNorm LayerNorm MaxPool Dropout ReLU | + | CouplingLayer ActNorm Inv1x1Conv RevBlock NormFlow | + | train!() compile() verify() from_pytorch() | + +-----------------------------------------------------------------+ + | | | | + v v v v + +----------+ +-----------+ +-----------+ +-----------+ + | DSL & | | Training | | Verifi- | | Integra- | + | Macros | | Loop | | cation | | tions | + |----------| |-----------| |-----------| |-----------| + | axiom_ | | optimiz- | | proper- | | hugging- | + | macro | | ers.jl | | ties.jl | | face.jl | + | ensure | | loss.jl | | checker | | pytorch | + | prove* | | train.jl | | certifi- | | ext | + | pipeline | | gradient* | | cates.jl | | | + +----------+ +-----------+ | serial- | +-----------+ + | ize.jl | + | proof_ | + | export | + +-----------+ + | + +-----------------------------+-----------------------------+ + | | | + v v v + +-----------+ +-----------+ +-----------+ + | SMTLib.jl | | Lean 4 | | Coq / | + | (bundled) | | Export* | | Isabelle* | + |-----------| +-----------+ +-----------+ + | z3, cvc5 | + | yices, | + | mathsat | + +-----------+ + + Backend Abstraction Layer (15 backends incl. SmartBackend) + +-----------------------------------------------------------------+ + | abstract.jl - AbstractBackend / set_backend! / compile() | + | SmartBackend (per-op dispatch) / MixedPrecision / self-healing | + +-----------------------------------------------------------------+ + | | | + v v v + +-----------+ +-----------+ +-----------+ + | Julia | | Zig | | GPU | + | Backend | | Backend | | Backends | + |-----------| |-----------| |-----------| + | (default) | | zig/ | | CUDA | + | reference | | axiom | | ROCm | + | impl | | .zig | | Metal | + | | | SIMD+MT | | | + +-----------+ +-----------+ +-----------+ + | + Coprocessor Backends (self-healing fallback) | + +-----------------------------------------------------------------+ + | TPU | NPU | DSP | PPU | Math | FPGA | VPU | QPU | Crypto | + |-----------------------------------------------------------------| + | Environment-based detection (AXIOM_*_AVAILABLE) | + | Strict mode: AXIOM_*_REQUIRED=1 prevents fallback | + | Self-healing: graceful degradation to JuliaBackend | + +-----------------------------------------------------------------+ + + * = disabled, stub, or placeholder +.... + +=== Completion Dashboard + +==== Core Framework + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|Type System (Tensor) |Done |`+██████████+` 100% +|Layer Definitions |Done |`+██████████+` 100% +|Activation Functions |Done |`+██████████+` 100% +|Optimizers (SGD/Adam) |Done |`+██████████+` 100% +|Loss Functions |Done |`+██████████+` 100% +|Training Loop |Done |`+██████████+` 90% +|Model Save/Load |Done |`+██████████+` 100% (binary) +|Autograd (Zygote) |Done |`+██████████+` 100% +|Data Utilities |Done |`+██████████+` 100% +|Model Containers |Done |`+██████████+` 100% +|=== + +==== Reversible Computing + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|CouplingLayer (affine) |Done |`+██████████+` 100% +|ActNorm (data-dep init) |Done |`+██████████+` 100% +|Invertible1x1Conv (LU) |Done |`+██████████+` 100% +|RevBlock (reversible) |Done |`+██████████+` 100% +|InvertibleSequential |Done |`+██████████+` 100% +|NormalizingFlow |Done |`+██████████+` 100% +|Custom Zygote adjoints |Done |`+██████████+` 100% +|Roundtrip verification |Done |`+██████████+` 100% +|=== + +==== DSL & Macros + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|@axiom macro |Done |`+██████████+` 100% +|@ensure macro |Done |`+██████████+` 100% +|@prove macro |Done |`+██████████+` 100% +|Pipeline DSL |Done |`+██████████+` 100% +|=== + +==== Verification System + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|Property Checking |Done |`+██████████+` 100% +|Proof Certificates |Done |`+██████████+` 100% (JSON+text) +|Serialization |Done |`+██████████+` 100% +|SMTLib.jl (bundled) |Done |`+████████░░+` 80% +|Lean 4 Export |Done |`+████████░░+` 80% (real tactics) +|Coq Export |Done |`+████████░░+` 80% (real tactics) +|Isabelle Export |Done |`+████████░░+` 80% (real tactics) +|Proof Import |Done |`+██████████+` 100% +|=== + +==== Backends - Julia (Reference) + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|matmul |Done |`+██████████+` 100% +|conv2d |Done |`+██████████+` 100% +|activations (all) |Done |`+██████████+` 100% +|batchnorm / layernorm |Done |`+██████████+` 100% +|pooling (max/avg/glob) |Done |`+██████████+` 100% +|dropout / flatten |Done |`+██████████+` 100% +|=== + +==== Backends - Zig (sole native backend, 320KB .so) + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|matmul (SIMD tiled) |Done |`+██████████+` 100% +|activations (15 funcs) |Done |`+██████████+` 100% +|conv2d + depthwise |Done |`+██████████+` 100% +|pooling (max/avg/glob) |Done |`+██████████+` 100% +|norm (batch/layer/rms) |Done |`+██████████+` 100% +|flash attention |Done |`+██████████+` 100% +|rotary embeddings |Done |`+██████████+` 100% +|Julia-side ccall wiring |Done |`+██████████+` 100% (17 ops) +|Compiled .so artifact |Done |`+██████████+` 100% (320KB) +|FFI exports (32 syms) |Done |`+██████████+` 100% +|SIMD GELU/sigmoid/tanh |Done |`+██████████+` 100% (3x speedup) +|Multi-threaded dispatch |Done |`+██████████+` 100% (4 threads) +|=== + +==== Backends - GPU Extensions + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|CUDA: matmul |Done |`+██████████+` 100% +|CUDA: relu |Done |`+██████████+` 100% +|CUDA: softmax |Done |`+██████████+` 100% +|CUDA: conv2d |Done |`+██████████+` 100% +|CUDA: batchnorm |Done |`+██████████+` 100% +|CUDA: pooling |Done |`+██████████+` 100% +|ROCm: matmul/relu/soft |Done |`+██████████+` 100% +|ROCm: conv2d/norm/pool |Done |`+██████████+` 100% +|Metal: matmul/relu/soft |Done |`+██████████+` 100% +|Metal: conv2d/norm/pool |Done |`+██████████+` 100% +|=== + +==== Backends - Coprocessor Dispatch + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|Backend type hierarchy |Done |`+██████████+` 100% +|Env-based detection |Done |`+██████████+` 100% +|Self-healing fallback |Done |`+██████████+` 100% +|Strict mode / required |Done |`+██████████+` 100% +|Runtime diagnostics |Done |`+██████████+` 100% +|Capability reporting |Done |`+██████████+` 100% +|TPU extension skeleton |Skel |`+██░░░░░░░░+` 20% +|NPU extension skeleton |Skel |`+██░░░░░░░░+` 20% +|DSP extension skeleton |Skel |`+██░░░░░░░░+` 20% +|PPU extension skeleton |Skel |`+██░░░░░░░░+` 20% +|Math extension skeleton |Skel |`+██░░░░░░░░+` 20% +|FPGA extension skeleton |Skel |`+██░░░░░░░░+` 20% +|VPU extension skeleton |Skel |`+██░░░░░░░░+` 20% +|QPU extension skeleton |Skel |`+██░░░░░░░░+` 20% +|Crypto ext. skeleton |Skel |`+██░░░░░░░░+` 20% +|=== + +==== Integrations + +[width="100%",cols="38%,12%,50%",options="header",] +|=== +|Component |Status |Progress +|PyTorch import/export |Done |`+██████████+` 90% + +|HuggingFace framework |Done |`+████████░░+` 80% + +|HF model converters |Done |`+████████░░+` 80% +(BERT/GPT2/ViT/ResNet/LLaMA/Whisper) + +|SafeTensors loader |Done |`+██████████+` 100% + +|Model Metadata |Done |`+████████░░+` 80% (bundle save/load) + +|Resource-aware dispatch |Done |`+██████████+` 100% +|=== + +==== Compile & Optimization + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|Backend dispatch |Done |`+██████████+` 100% +|SmartBackend (per-op) |Done |`+██████████+` 100% +|Mixed precision |Done |`+████████░░+` 80% (loss scaling) +|fold_batchnorm |Done |`+██████████+` 100% +|fold_constants |Done |`+██████████+` 100% +|dead code elimination |Done |`+██████████+` 100% +|aggressive opt pass |Done |`+██████████+` 100% +|=== + +==== Infrastructure + +[cols=",,",options="header",] +|=== +|Component |Status |Progress +|CI/CD (21 workflows) |Good |`+████████░░+` 80% +|Tests (283 passing) |Good |`+██████████+` 100% +|Benchmarks |Done |`+██████████+` 100% +|Documentation (wiki) |Done |`+██████████+` 100% +|RSR Compliance |Done |`+██████████+` 100% +|Bot directives (8) |Done |`+██████████+` 100% +|Contractiles (5) |Done |`+██████████+` 100% +|SCM files (5) |Done |`+██████████+` 100% +|=== + +=== Key Dependencies + +[cols=",,",options="header",] +|=== +|Dependency |Purpose |Required +|Julia >= 1.10 |Runtime |Yes +|LinearAlgebra |Matrix operations |Yes +|SHA |Proof certificate hashing |Yes +|JSON |Metadata serialization |Yes +|CUDA.jl |NVIDIA GPU acceleration |Optional +|AMDGPU.jl |AMD GPU acceleration |Optional +|Metal.jl |Apple GPU acceleration |Optional +|PyCall.jl |PyTorch interop |Optional +|Zig toolchain |Zig backend compilation |Optional +|Z3/CVC5 |SMT solver for @prove |Optional +|=== + +=== Overall: ~98% complete + +*Strongest areas:* Core layers, activations, reversible computing +(CouplingLayer/ActNorm/Inv1x1Conv/RevBlock/NormalizingFlow with custom +Zygote adjoints), Zig kernel implementations (sole native backend, 36 +exports, 395KB .so, SIMD + 4-thread dispatch), SmartBackend per-op +dispatch, SIMD-optimized Zig kernels (GELU 3x, RMSNorm 7x, sigmoid +2.9x), multi-threaded element-wise ops (>64K threshold), SMTLib, +coprocessor dispatch infrastructure (9 backends with setup guides and +hardware detection), compile optimizations (incl. mixed precision with +loss scaling), certificates, HuggingFace (7 architectures + +SafeTensors), RSR compliance (SPDX on all files), GPU extensions (full +coverage), autograd (Zygote), @prove (heuristic+SMT), proof export (real +tactics), backend-aware dispatch (LayerNorm/RMSNorm route through +backends), model save/load (binary + metadata bundle), external +benchmarks (Axiom vs Flux vs PyTorch), 283 tests passing *Weakest +areas:* Coprocessor skeletons (20% — need real hardware for end-to-end +integration) + +=== Ecosystem Context + +Axiom.jl is the flagship package in `+julia-ecosystem+` (part of +`+developer-ecosystem+` monorepo). 13 sibling COMPUTE packages share the +same backend abstraction: Cladistics.jl, BowtieRisk.jl, Cliometrics.jl, +KnotTheory.jl, HackenbushGames.jl, QuantumCircuit.jl, SMTLib.jl, +PolyglotFormalisms.jl, Causals.jl, SiliconCore.jl, LowLevel.jl, +ZeroProb.jl, ProvenCrypto.jl. diff --git a/packages/Axiom.jl/TOPOLOGY.md b/packages/Axiom.jl/TOPOLOGY.md deleted file mode 100644 index 7e00ab5ca..000000000 --- a/packages/Axiom.jl/TOPOLOGY.md +++ /dev/null @@ -1,238 +0,0 @@ - -# Axiom.jl - System Architecture - -``` - Axiom.jl - Provably Correct Machine Learning - ============================================ - - User API Layer - +-----------------------------------------------------------------+ - | @axiom @ensure @prove* Sequential/Chain/Pipeline | - | Dense Conv2d BatchNorm LayerNorm MaxPool Dropout ReLU | - | CouplingLayer ActNorm Inv1x1Conv RevBlock NormFlow | - | train!() compile() verify() from_pytorch() | - +-----------------------------------------------------------------+ - | | | | - v v v v - +----------+ +-----------+ +-----------+ +-----------+ - | DSL & | | Training | | Verifi- | | Integra- | - | Macros | | Loop | | cation | | tions | - |----------| |-----------| |-----------| |-----------| - | axiom_ | | optimiz- | | proper- | | hugging- | - | macro | | ers.jl | | ties.jl | | face.jl | - | ensure | | loss.jl | | checker | | pytorch | - | prove* | | train.jl | | certifi- | | ext | - | pipeline | | gradient* | | cates.jl | | | - +----------+ +-----------+ | serial- | +-----------+ - | ize.jl | - | proof_ | - | export | - +-----------+ - | - +-----------------------------+-----------------------------+ - | | | - v v v - +-----------+ +-----------+ +-----------+ - | SMTLib.jl | | Lean 4 | | Coq / | - | (bundled) | | Export* | | Isabelle* | - |-----------| +-----------+ +-----------+ - | z3, cvc5 | - | yices, | - | mathsat | - +-----------+ - - Backend Abstraction Layer (15 backends incl. SmartBackend) - +-----------------------------------------------------------------+ - | abstract.jl - AbstractBackend / set_backend! / compile() | - | SmartBackend (per-op dispatch) / MixedPrecision / self-healing | - +-----------------------------------------------------------------+ - | | | - v v v - +-----------+ +-----------+ +-----------+ - | Julia | | Zig | | GPU | - | Backend | | Backend | | Backends | - |-----------| |-----------| |-----------| - | (default) | | zig/ | | CUDA | - | reference | | axiom | | ROCm | - | impl | | .zig | | Metal | - | | | SIMD+MT | | | - +-----------+ +-----------+ +-----------+ - | - Coprocessor Backends (self-healing fallback) | - +-----------------------------------------------------------------+ - | TPU | NPU | DSP | PPU | Math | FPGA | VPU | QPU | Crypto | - |-----------------------------------------------------------------| - | Environment-based detection (AXIOM_*_AVAILABLE) | - | Strict mode: AXIOM_*_REQUIRED=1 prevents fallback | - | Self-healing: graceful degradation to JuliaBackend | - +-----------------------------------------------------------------+ - - * = disabled, stub, or placeholder -``` - -## Completion Dashboard - -### Core Framework -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| Type System (Tensor) | Done | `██████████` 100% | -| Layer Definitions | Done | `██████████` 100% | -| Activation Functions | Done | `██████████` 100% | -| Optimizers (SGD/Adam) | Done | `██████████` 100% | -| Loss Functions | Done | `██████████` 100% | -| Training Loop | Done | `██████████` 90% | -| Model Save/Load | Done | `██████████` 100% (binary) | -| Autograd (Zygote) | Done | `██████████` 100% | -| Data Utilities | Done | `██████████` 100% | -| Model Containers | Done | `██████████` 100% | - -### Reversible Computing -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| CouplingLayer (affine) | Done | `██████████` 100% | -| ActNorm (data-dep init)| Done | `██████████` 100% | -| Invertible1x1Conv (LU) | Done | `██████████` 100% | -| RevBlock (reversible) | Done | `██████████` 100% | -| InvertibleSequential | Done | `██████████` 100% | -| NormalizingFlow | Done | `██████████` 100% | -| Custom Zygote adjoints | Done | `██████████` 100% | -| Roundtrip verification | Done | `██████████` 100% | - -### DSL & Macros -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| @axiom macro | Done | `██████████` 100% | -| @ensure macro | Done | `██████████` 100% | -| @prove macro | Done | `██████████` 100% | -| Pipeline DSL | Done | `██████████` 100% | - -### Verification System -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| Property Checking | Done | `██████████` 100% | -| Proof Certificates | Done | `██████████` 100% (JSON+text) | -| Serialization | Done | `██████████` 100% | -| SMTLib.jl (bundled) | Done | `████████░░` 80% | -| Lean 4 Export | Done | `████████░░` 80% (real tactics) | -| Coq Export | Done | `████████░░` 80% (real tactics) | -| Isabelle Export | Done | `████████░░` 80% (real tactics) | -| Proof Import | Done | `██████████` 100% | - -### Backends - Julia (Reference) -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| matmul | Done | `██████████` 100% | -| conv2d | Done | `██████████` 100% | -| activations (all) | Done | `██████████` 100% | -| batchnorm / layernorm | Done | `██████████` 100% | -| pooling (max/avg/glob) | Done | `██████████` 100% | -| dropout / flatten | Done | `██████████` 100% | - -### Backends - Zig (sole native backend, 320KB .so) -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| matmul (SIMD tiled) | Done | `██████████` 100% | -| activations (15 funcs) | Done | `██████████` 100% | -| conv2d + depthwise | Done | `██████████` 100% | -| pooling (max/avg/glob) | Done | `██████████` 100% | -| norm (batch/layer/rms) | Done | `██████████` 100% | -| flash attention | Done | `██████████` 100% | -| rotary embeddings | Done | `██████████` 100% | -| Julia-side ccall wiring| Done | `██████████` 100% (17 ops) | -| Compiled .so artifact | Done | `██████████` 100% (320KB) | -| FFI exports (32 syms) | Done | `██████████` 100% | -| SIMD GELU/sigmoid/tanh | Done | `██████████` 100% (3x speedup) | -| Multi-threaded dispatch| Done | `██████████` 100% (4 threads) | - -### Backends - GPU Extensions -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| CUDA: matmul | Done | `██████████` 100% | -| CUDA: relu | Done | `██████████` 100% | -| CUDA: softmax | Done | `██████████` 100% | -| CUDA: conv2d | Done | `██████████` 100% | -| CUDA: batchnorm | Done | `██████████` 100% | -| CUDA: pooling | Done | `██████████` 100% | -| ROCm: matmul/relu/soft | Done | `██████████` 100% | -| ROCm: conv2d/norm/pool | Done | `██████████` 100% | -| Metal: matmul/relu/soft| Done | `██████████` 100% | -| Metal: conv2d/norm/pool| Done | `██████████` 100% | - -### Backends - Coprocessor Dispatch -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| Backend type hierarchy | Done | `██████████` 100% | -| Env-based detection | Done | `██████████` 100% | -| Self-healing fallback | Done | `██████████` 100% | -| Strict mode / required | Done | `██████████` 100% | -| Runtime diagnostics | Done | `██████████` 100% | -| Capability reporting | Done | `██████████` 100% | -| TPU extension skeleton | Skel | `██░░░░░░░░` 20% | -| NPU extension skeleton | Skel | `██░░░░░░░░` 20% | -| DSP extension skeleton | Skel | `██░░░░░░░░` 20% | -| PPU extension skeleton | Skel | `██░░░░░░░░` 20% | -| Math extension skeleton| Skel | `██░░░░░░░░` 20% | -| FPGA extension skeleton| Skel | `██░░░░░░░░` 20% | -| VPU extension skeleton | Skel | `██░░░░░░░░` 20% | -| QPU extension skeleton | Skel | `██░░░░░░░░` 20% | -| Crypto ext. skeleton | Skel | `██░░░░░░░░` 20% | - -### Integrations -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| PyTorch import/export | Done | `██████████` 90% | -| HuggingFace framework | Done | `████████░░` 80% | -| HF model converters | Done | `████████░░` 80% (BERT/GPT2/ViT/ResNet/LLaMA/Whisper) | -| SafeTensors loader | Done | `██████████` 100% | -| Model Metadata | Done | `████████░░` 80% (bundle save/load) | -| Resource-aware dispatch| Done | `██████████` 100% | - -### Compile & Optimization -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| Backend dispatch | Done | `██████████` 100% | -| SmartBackend (per-op) | Done | `██████████` 100% | -| Mixed precision | Done | `████████░░` 80% (loss scaling) | -| fold_batchnorm | Done | `██████████` 100% | -| fold_constants | Done | `██████████` 100% | -| dead code elimination | Done | `██████████` 100% | -| aggressive opt pass | Done | `██████████` 100% | - -### Infrastructure -| Component | Status | Progress | -|------------------------|--------|--------------------------------| -| CI/CD (21 workflows) | Good | `████████░░` 80% | -| Tests (283 passing) | Good | `██████████` 100% | -| Benchmarks | Done | `██████████` 100% | -| Documentation (wiki) | Done | `██████████` 100% | -| RSR Compliance | Done | `██████████` 100% | -| Bot directives (8) | Done | `██████████` 100% | -| Contractiles (5) | Done | `██████████` 100% | -| SCM files (5) | Done | `██████████` 100% | - -## Key Dependencies - -| Dependency | Purpose | Required | -|----------------|----------------------------|----------| -| Julia >= 1.10 | Runtime | Yes | -| LinearAlgebra | Matrix operations | Yes | -| SHA | Proof certificate hashing | Yes | -| JSON | Metadata serialization | Yes | -| CUDA.jl | NVIDIA GPU acceleration | Optional | -| AMDGPU.jl | AMD GPU acceleration | Optional | -| Metal.jl | Apple GPU acceleration | Optional | -| PyCall.jl | PyTorch interop | Optional | -| Zig toolchain | Zig backend compilation | Optional | -| Z3/CVC5 | SMT solver for @prove | Optional | - -## Overall: ~98% complete - -**Strongest areas:** Core layers, activations, reversible computing (CouplingLayer/ActNorm/Inv1x1Conv/RevBlock/NormalizingFlow with custom Zygote adjoints), Zig kernel implementations (sole native backend, 36 exports, 395KB .so, SIMD + 4-thread dispatch), SmartBackend per-op dispatch, SIMD-optimized Zig kernels (GELU 3x, RMSNorm 7x, sigmoid 2.9x), multi-threaded element-wise ops (>64K threshold), SMTLib, coprocessor dispatch infrastructure (9 backends with setup guides and hardware detection), compile optimizations (incl. mixed precision with loss scaling), certificates, HuggingFace (7 architectures + SafeTensors), RSR compliance (SPDX on all files), GPU extensions (full coverage), autograd (Zygote), @prove (heuristic+SMT), proof export (real tactics), backend-aware dispatch (LayerNorm/RMSNorm route through backends), model save/load (binary + metadata bundle), external benchmarks (Axiom vs Flux vs PyTorch), 283 tests passing -**Weakest areas:** Coprocessor skeletons (20% — need real hardware for end-to-end integration) - -## Ecosystem Context - -Axiom.jl is the flagship package in `julia-ecosystem` (part of `developer-ecosystem` monorepo). -13 sibling COMPUTE packages share the same backend abstraction: Cladistics.jl, BowtieRisk.jl, -Cliometrics.jl, KnotTheory.jl, HackenbushGames.jl, QuantumCircuit.jl, SMTLib.jl, -PolyglotFormalisms.jl, Causals.jl, SiliconCore.jl, LowLevel.jl, ZeroProb.jl, ProvenCrypto.jl. diff --git a/packages/Axiom.jl/benchmark/results_2026-02-20_framework-comparison.md b/packages/Axiom.jl/benchmark/results_2026-02-20_framework-comparison.adoc similarity index 62% rename from packages/Axiom.jl/benchmark/results_2026-02-20_framework-comparison.md rename to packages/Axiom.jl/benchmark/results_2026-02-20_framework-comparison.adoc index 187a0873f..2e755e88c 100644 --- a/packages/Axiom.jl/benchmark/results_2026-02-20_framework-comparison.md +++ b/packages/Axiom.jl/benchmark/results_2026-02-20_framework-comparison.adoc @@ -1,17 +1,18 @@ -# Axiom.jl External Framework Comparison — 2026-02-20 +== Axiom.jl External Framework Comparison — 2026-02-20 -## System -- **CPU**: Intel (i915 + Quadro M2000M laptop) -- **OS**: Fedora 43 Atomic (Linux 6.18.10) -- **Julia**: 1.12.5 -- **PyTorch**: 2.10.0+cpu (ATen/MKL) -- **Flux.jl**: 0.16+ (NNlib backend) -- **Axiom.jl**: 1.0.0 (SmartBackend: Zig 213KB + Julia/BLAS) -- **Method**: 50 iterations, 3 warmup, median timing, CPU-only +=== System -## Raw Timings (microseconds) +* *CPU*: Intel (i915 + Quadro M2000M laptop) +* *OS*: Fedora 43 Atomic (Linux 6.18.10) +* *Julia*: 1.12.5 +* *PyTorch*: 2.10.0+cpu (ATen/MKL) +* *Flux.jl*: 0.16+ (NNlib backend) +* *Axiom.jl*: 1.0.0 (SmartBackend: Zig 213KB + Julia/BLAS) +* *Method*: 50 iterations, 3 warmup, median timing, CPU-only -``` +=== Raw Timings (microseconds) + +.... ┌─────────────┬──────────────┬───────────────┬───────────────┬───────────────┬───────────────┐ │ Operation │ Size │ Axiom Smart │ Axiom Julia │ Flux.jl (μs) │ PyTorch (μs) │ ├─────────────┼──────────────┼───────────────┼───────────────┼───────────────┼───────────────┤ @@ -41,11 +42,11 @@ │ batchnorm │ 64×256 │ 84.5 │ 87.8 │ 8.1 │ 56.2 │ │ batchnorm │ 128×512 │ 357.9 │ 205.4 │ 28.2 │ 67.4 │ └─────────────┴──────────────┴───────────────┴───────────────┴───────────────┴───────────────┘ -``` +.... -## Speedup vs PyTorch (>1.0x = faster than PyTorch) +=== Speedup vs PyTorch (>1.0x = faster than PyTorch) -``` +.... ┌─────────────┬──────────────┬───────────────┬───────────────┬───────────────┐ │ Operation │ Size │ Axiom Smart │ Axiom Julia │ Flux.jl │ ├─────────────┼──────────────┼───────────────┼───────────────┼───────────────┤ @@ -75,81 +76,94 @@ │ batchnorm │ 64×256 │ 0.67x │ 0.64x │ 6.95x │ │ batchnorm │ 128×512 │ 0.19x │ 0.33x │ 2.39x │ └─────────────┴──────────────┴───────────────┴───────────────┴───────────────┘ -``` - -## Aggregate - -| Framework | Geometric Mean | Arithmetic Mean | Wins vs PyTorch | -|----------------|---------------|-----------------|-----------------| -| Axiom Smart | 0.73x | 3.57x | 11/25 | -| Axiom Julia | 0.52x | 2.12x | 11/25 (different ops) | -| Flux.jl | 0.82x | 4.57x | 11/25 | - -> All three Julia frameworks win small-batch operations (lower dispatch overhead than Python). -> PyTorch dominates medium-to-large element-wise operations (MKL VML + OpenMP threading). - -## Analysis - -### Where Axiom SmartBackend Wins vs PyTorch -- **Small inputs (1K elements)**: 1.3–30x faster — zero Python overhead, no tensor metadata -- **RMSNorm (all sizes)**: 2–30x faster — Zig SIMD inner loop has less dispatch overhead than PyTorch's nn.RMSNorm -- **LayerNorm (small)**: 3.3x faster — Zig SIMD at 32×128 -- **BatchNorm (small)**: 6.6x faster at 32×64 - -### Where PyTorch Wins -- **Sigmoid/GELU/Softmax at ≥100K**: 5–25x faster — PyTorch uses Intel MKL VML (Vector Math Library) which provides multi-threaded, AVX-512/AVX2 optimized transcendental functions (`exp`, `tanh`). Our Zig SIMD is single-threaded AVX-256. -- **Large LayerNorm** (64×768, 128×1024): 3–6x faster — same MKL advantage -- **Large softmax**: 25x faster at 128×50257 — MKL softmax kernel is heavily optimized - -### SmartBackend Impact -SmartBackend improves Axiom's geomean from **0.52x → 0.73x** vs PyTorch (40% improvement). -Key wins from Zig dispatch: -- GELU 1K: 16.3μs → 5.5μs (3x, routes to Zig SIMD) -- Sigmoid 1M: 11061μs → 5068μs (2.2x, routes to Zig SIMD) -- RMSNorm: 460μs → 72μs (6.4x, routes to Zig SIMD) -- LayerNorm: 397μs → 153μs (2.6x, routes to Zig) - -### Axiom vs Flux.jl -Axiom SmartBackend beats Flux on: -- **Sigmoid** (all sizes): Zig SIMD vs Flux broadcasting -- **GELU** (1K, 1M): Zig SIMD vectorization -- **LayerNorm** (64×768): Zig dispatch -- **Softmax** (small): Zig vectorized - -Flux beats Axiom on: -- **BatchNorm**: NNlib has highly optimized batched normalization -- **ReLU** (100K): NNlib fused kernel -- **RMSNorm**: Manual broadcast is surprisingly fast in Flux - -### Root Cause: Why PyTorch is Faster at Scale - -PyTorch's ATen C++ library uses: -1. **Intel MKL VML** — vectorized math functions (`vsSigmoid`, `vsTanh`, `vsExp`) with AVX-512, multi-threaded -2. **OpenMP threading** — automatic parallelism across CPU cores -3. **In-place operations** — fewer memory allocations -4. **Fused kernels** — compound operations like GELU don't create intermediates - -Our Zig kernels are: -1. Single-threaded (uses only one core) -2. AVX-256 only (8-wide `@Vector(8, f32)`) -3. Separate allocation per output - -### Recommendations for Axiom v1.0 - -1. **Threading**: Add `@threadlocal` or Zig thread pool for element-wise ops at ≥100K elements -2. **AVX-512**: Detect and use `@Vector(16, f32)` when available -3. **In-place variants**: Add `backend_sigmoid!()` etc. to avoid allocation -4. **Fused kernels**: Implement `gelu_and_multiply`, `layernorm_and_residual` -5. **Softmax**: The 128×50257 case needs multi-threaded reduction - -### Honest Assessment - -Axiom.jl at v1.0 is **competitive with PyTorch for small-to-medium workloads** and -**RMSNorm/LayerNorm are faster at all sizes**. For large element-wise operations, -PyTorch's MKL integration gives it a 5–25x advantage that can only be closed with -threading and wider SIMD. This is expected — PyTorch has had thousands of -engineer-years of optimization. - -**The differentiator is not raw speed — it's provable correctness.** -No other framework offers `@ensure`, `@prove`, and proof certificates alongside -competitive kernel performance. +.... + +=== Aggregate + +[width="100%",cols="25%,23%,26%,26%",options="header",] +|=== +|Framework |Geometric Mean |Arithmetic Mean |Wins vs PyTorch +|Axiom Smart |0.73x |3.57x |11/25 +|Axiom Julia |0.52x |2.12x |11/25 (different ops) +|Flux.jl |0.82x |4.57x |11/25 +|=== + +____ +All three Julia frameworks win small-batch operations (lower dispatch +overhead than Python). PyTorch dominates medium-to-large element-wise +operations (MKL VML + OpenMP threading). +____ + +=== Analysis + +==== Where Axiom SmartBackend Wins vs PyTorch + +* *Small inputs (1K elements)*: 1.3–30x faster — zero Python overhead, +no tensor metadata +* *RMSNorm (all sizes)*: 2–30x faster — Zig SIMD inner loop has less +dispatch overhead than PyTorch’s nn.RMSNorm +* *LayerNorm (small)*: 3.3x faster — Zig SIMD at 32×128 +* *BatchNorm (small)*: 6.6x faster at 32×64 + +==== Where PyTorch Wins + +* *Sigmoid/GELU/Softmax at ≥100K*: 5–25x faster — PyTorch uses Intel MKL +VML (Vector Math Library) which provides multi-threaded, AVX-512/AVX2 +optimized transcendental functions (`+exp+`, `+tanh+`). Our Zig SIMD is +single-threaded AVX-256. +* *Large LayerNorm* (64×768, 128×1024): 3–6x faster — same MKL advantage +* *Large softmax*: 25x faster at 128×50257 — MKL softmax kernel is +heavily optimized + +==== SmartBackend Impact + +SmartBackend improves Axiom’s geomean from *0.52x → 0.73x* vs PyTorch +(40% improvement). Key wins from Zig dispatch: - GELU 1K: 16.3μs → 5.5μs +(3x, routes to Zig SIMD) - Sigmoid 1M: 11061μs → 5068μs (2.2x, routes to +Zig SIMD) - RMSNorm: 460μs → 72μs (6.4x, routes to Zig SIMD) - +LayerNorm: 397μs → 153μs (2.6x, routes to Zig) + +==== Axiom vs Flux.jl + +Axiom SmartBackend beats Flux on: - *Sigmoid* (all sizes): Zig SIMD vs +Flux broadcasting - *GELU* (1K, 1M): Zig SIMD vectorization - +*LayerNorm* (64×768): Zig dispatch - *Softmax* (small): Zig vectorized + +Flux beats Axiom on: - *BatchNorm*: NNlib has highly optimized batched +normalization - *ReLU* (100K): NNlib fused kernel - *RMSNorm*: Manual +broadcast is surprisingly fast in Flux + +==== Root Cause: Why PyTorch is Faster at Scale + +PyTorch’s ATen C++ library uses: 1. *Intel MKL VML* — vectorized math +functions (`+vsSigmoid+`, `+vsTanh+`, `+vsExp+`) with AVX-512, +multi-threaded 2. *OpenMP threading* — automatic parallelism across CPU +cores 3. *In-place operations* — fewer memory allocations 4. *Fused +kernels* — compound operations like GELU don’t create intermediates + +Our Zig kernels are: 1. Single-threaded (uses only one core) 2. AVX-256 +only (8-wide `+@Vector(8, f32)+`) 3. Separate allocation per output + +==== Recommendations for Axiom v1.0 + +[arabic] +. *Threading*: Add `+@threadlocal+` or Zig thread pool for element-wise +ops at ≥100K elements +. *AVX-512*: Detect and use `+@Vector(16, f32)+` when available +. *In-place variants*: Add `+backend_sigmoid!()+` etc. to avoid +allocation +. *Fused kernels*: Implement `+gelu_and_multiply+`, +`+layernorm_and_residual+` +. *Softmax*: The 128×50257 case needs multi-threaded reduction + +==== Honest Assessment + +Axiom.jl at v1.0 is *competitive with PyTorch for small-to-medium +workloads* and *RMSNorm/LayerNorm are faster at all sizes*. For large +element-wise operations, PyTorch’s MKL integration gives it a 5–25x +advantage that can only be closed with threading and wider SIMD. This is +expected — PyTorch has had thousands of engineer-years of optimization. + +*The differentiator is not raw speed — it’s provable correctness.* No +other framework offers `+@ensure+`, `+@prove+`, and proof certificates +alongside competitive kernel performance. diff --git a/packages/Axiom.jl/benchmark/results_2026-02-20_julia-rust-zig.md b/packages/Axiom.jl/benchmark/results_2026-02-20_julia-rust-zig.adoc similarity index 62% rename from packages/Axiom.jl/benchmark/results_2026-02-20_julia-rust-zig.md rename to packages/Axiom.jl/benchmark/results_2026-02-20_julia-rust-zig.adoc index ac54a566f..6cac4ee55 100644 --- a/packages/Axiom.jl/benchmark/results_2026-02-20_julia-rust-zig.md +++ b/packages/Axiom.jl/benchmark/results_2026-02-20_julia-rust-zig.adoc @@ -1,22 +1,26 @@ -# Axiom.jl Benchmark Results — 2026-02-20 +== Axiom.jl Benchmark Results — 2026-02-20 -## System -- **CPU**: Intel (i915 + Quadro M2000M laptop) -- **OS**: Fedora 43 Atomic (Linux 6.18.10) -- **Julia**: 1.11+ -- **Zig**: 0.15.2 (ReleaseFast) -- **Rust**: nightly (release) -- **Method**: 50 iterations, 3 warmup, median timing +=== System -## Binary Sizes -| Backend | Size | -|---------|------| -| Rust | 1990 KB | -| Zig | 213 KB | +* *CPU*: Intel (i915 + Quadro M2000M laptop) +* *OS*: Fedora 43 Atomic (Linux 6.18.10) +* *Julia*: 1.11+ +* *Zig*: 0.15.2 (ReleaseFast) +* *Rust*: nightly (release) +* *Method*: 50 iterations, 3 warmup, median timing -## Results (Post-SIMD Optimization) +=== Binary Sizes -``` +[cols=",",options="header",] +|=== +|Backend |Size +|Rust |1990 KB +|Zig |213 KB +|=== + +=== Results (Post-SIMD Optimization) + +.... ┌─────────────┬──────────────┬───────────────┬───────────────┬───────────────┬─────────────┬─────────────┐ │ Operation │ Size │ Julia (μs) │ Rust (μs) │ Zig (μs) │ Rust vs Jul │ Zig vs Jul │ ├─────────────┼──────────────┼───────────────┼───────────────┼───────────────┼─────────────┼─────────────┤ @@ -46,55 +50,70 @@ │ batchnorm │ 64×256 │ 46.0 │ 117.7 │ 53.6 │ 0.39x │ 0.86x │ │ batchnorm │ 128×512 │ 197.1 │ 596.4 │ 346.5 │ 0.33x │ 0.57x │ └─────────────┴──────────────┴───────────────┴───────────────┴───────────────┴─────────────┴─────────────┘ -``` - -## Aggregate - -| Backend | Geometric Mean | Arithmetic Mean | -|---------|---------------|-----------------| -| Rust | 0.49x | 0.86x | -| Zig | 1.01x | 1.99x | - -> Values >1.0x mean native backend is faster than Julia. - -## Analysis - -### Zig Wins (dispatch-worthy) -- **RMSNorm**: 6.5–7.3x faster — SIMD-optimized inner loop dominates -- **GELU**: 3.0–3.5x faster — SIMD `@exp` vectorization (was 0.55x before SIMD!) -- **Sigmoid**: 1.1–2.9x faster — SIMD `@exp` path -- **LayerNorm**: 1.2–2.6x faster — consistent advantage at all sizes -- **Softmax (small/medium)**: 1.0–1.4x faster - -### Julia Wins (keep on BLAS) -- **MatMul**: 7–50x faster — Julia calls OpenBLAS/MKL; native backends use hand-written tiled matmul -- **BatchNorm**: 1.2–1.8x faster at large sizes — row-major conversion overhead in FFI path -- **ReLU**: near-parity but FFI overhead makes Julia preferable - -### GELU SIMD Optimization Impact -The biggest win of this session — GELU went from Julia's worst Zig dispatch to its best: - -| Size | Before SIMD | After SIMD | Improvement | -|------|------------|------------|-------------| -| 1K | 0.52x | 3.10x | **6.0x** | -| 100K | 0.57x | 3.45x | **6.1x** | -| 1M | 0.55x | 2.96x | **5.4x** | - -Root cause: scalar `math.tanh()` loop replaced with SIMD `@exp` vectorization -using identity `tanh(z) = 1 - 2/(exp(2z) + 1)`. - -### Zig vs Rust -Zig beats Rust on every single benchmark: -- 9.3x smaller binary (213KB vs 1990KB) -- Faster compilation (seconds vs minutes) -- First-class SIMD (no crate dependencies) -- RMSNorm: Zig 7.3x vs Rust 1.7x (Zig 4.3x faster than Rust) -- GELU: Zig 3.5x vs Rust 1.1x (Zig 3.2x faster than Rust) - -### SmartBackend Dispatch Table (implemented) -1. **MatMul**: Julia/BLAS — native backends cannot compete -2. **GELU**: Zig — 3.0–3.5x faster after SIMD optimization -3. **RMSNorm/LayerNorm/Sigmoid**: Zig by default -4. **Softmax**: Zig for small batches (<50K classes), Julia for large -5. **BatchNorm/ReLU**: Julia — FFI overhead negates kernel advantage -6. **Conv2d**: Julia — BLAS-based +.... + +=== Aggregate + +[cols=",,",options="header",] +|=== +|Backend |Geometric Mean |Arithmetic Mean +|Rust |0.49x |0.86x +|Zig |1.01x |1.99x +|=== + +____ +Values >1.0x mean native backend is faster than Julia. +____ + +=== Analysis + +==== Zig Wins (dispatch-worthy) + +* *RMSNorm*: 6.5–7.3x faster — SIMD-optimized inner loop dominates +* *GELU*: 3.0–3.5x faster — SIMD `+@exp+` vectorization (was 0.55x +before SIMD!) +* *Sigmoid*: 1.1–2.9x faster — SIMD `+@exp+` path +* *LayerNorm*: 1.2–2.6x faster — consistent advantage at all sizes +* *Softmax (small/medium)*: 1.0–1.4x faster + +==== Julia Wins (keep on BLAS) + +* *MatMul*: 7–50x faster — Julia calls OpenBLAS/MKL; native backends use +hand-written tiled matmul +* *BatchNorm*: 1.2–1.8x faster at large sizes — row-major conversion +overhead in FFI path +* *ReLU*: near-parity but FFI overhead makes Julia preferable + +==== GELU SIMD Optimization Impact + +The biggest win of this session — GELU went from Julia’s worst Zig +dispatch to its best: + +[cols=",,,",options="header",] +|=== +|Size |Before SIMD |After SIMD |Improvement +|1K |0.52x |3.10x |*6.0x* +|100K |0.57x |3.45x |*6.1x* +|1M |0.55x |2.96x |*5.4x* +|=== + +Root cause: scalar `+math.tanh()+` loop replaced with SIMD `+@exp+` +vectorization using identity `+tanh(z) = 1 - 2/(exp(2z) + 1)+`. + +==== Zig vs Rust + +Zig beats Rust on every single benchmark: - 9.3x smaller binary (213KB +vs 1990KB) - Faster compilation (seconds vs minutes) - First-class SIMD +(no crate dependencies) - RMSNorm: Zig 7.3x vs Rust 1.7x (Zig 4.3x +faster than Rust) - GELU: Zig 3.5x vs Rust 1.1x (Zig 3.2x faster than +Rust) + +==== SmartBackend Dispatch Table (implemented) + +[arabic] +. *MatMul*: Julia/BLAS — native backends cannot compete +. *GELU*: Zig — 3.0–3.5x faster after SIMD optimization +. *RMSNorm/LayerNorm/Sigmoid*: Zig by default +. *Softmax*: Zig for small batches (<50K classes), Julia for large +. *BatchNorm/ReLU*: Julia — FFI overhead negates kernel advantage +. *Conv2d*: Julia — BLAS-based diff --git a/packages/Axiom.jl/packages/SMTLib.jl/README.md b/packages/Axiom.jl/packages/SMTLib.jl/README.adoc similarity index 59% rename from packages/Axiom.jl/packages/SMTLib.jl/README.md rename to packages/Axiom.jl/packages/SMTLib.jl/README.adoc index 6a4e7d85c..ea1768f5e 100644 --- a/packages/Axiom.jl/packages/SMTLib.jl/README.md +++ b/packages/Axiom.jl/packages/SMTLib.jl/README.adoc @@ -1,24 +1,29 @@ -# SMTLib.jl +== SMTLib.jl A lightweight Julia interface to SMT solvers via SMT-LIB2 format. -> **Standalone Package**: This package is designed to be published independently. -> Currently bundled with [Axiom.jl](https://github.com/hyperpolymath/axiom.jl) at `packages/SMTLib.jl`. -> To publish separately, copy this directory to a new repository. +____ +*Standalone Package*: This package is designed to be published +independently. Currently bundled with +https://github.com/hyperpolymath/axiom.jl[Axiom.jl] at +`+packages/SMTLib.jl+`. To publish separately, copy this directory to a +new repository. +____ -## Features +=== Features -- **Auto-detection** of installed SMT solvers (Z3, CVC5, Yices, MathSAT) -- **Julia expression to SMT-LIB2** conversion -- **Multiple logics**: QF_LIA, QF_LRA, QF_NRA, QF_BV, arrays, and more -- **Model parsing** and counterexample extraction -- **Timeout support** -- **Incremental solving** with push/pop semantics -- **Zero dependencies** - pure Julia +* *Auto-detection* of installed SMT solvers (Z3, CVC5, Yices, MathSAT) +* *Julia expression to SMT-LIB2* conversion +* *Multiple logics*: QF_LIA, QF_LRA, QF_NRA, QF_BV, arrays, and more +* *Model parsing* and counterexample extraction +* *Timeout support* +* *Incremental solving* with push/pop semantics +* *Zero dependencies* - pure Julia -## Installation +=== Installation -```julia +[source,julia] +---- using Pkg # From Axiom.jl monorepo @@ -26,13 +31,14 @@ Pkg.develop(path="packages/SMTLib.jl") # Or from standalone repo (when published) # Pkg.add(url="https://github.com/hyperpolymath/SMTLib.jl") -``` +---- -### Prerequisites +==== Prerequisites Install at least one SMT solver: -```bash +[source,bash] +---- # Z3 (recommended) brew install z3 # macOS apt install z3 # Ubuntu/Debian @@ -41,11 +47,12 @@ pacman -S z3 # Arch # CVC5 brew install cvc5 apt install cvc5 -``` +---- -## Quick Start +=== Quick Start -```julia +[source,julia] +---- using SMTLib # Simple satisfiability check @@ -64,11 +71,12 @@ if result.status == :sat println("x = ", result.model[:x]) println("y = ", result.model[:y]) end -``` +---- -### Using the @smt Macro +==== Using the @smt Macro -```julia +[source,julia] +---- result = @smt logic=:QF_LIA begin x::Int y::Int @@ -79,57 +87,71 @@ end println(result.status) # :sat println(result.model) # Dict(:x => 5, :y => 5) -``` +---- -### Proving Properties +==== Proving Properties -```julia +[source,julia] +---- # Prove that x^2 >= 0 for all real x # (Returns true if proven) proven = prove(:(x * x >= 0), logic=:QF_NRA) -``` +---- -## Supported Logics +=== Supported Logics -| Logic | Description | -|-------|-------------| -| `QF_LIA` | Quantifier-free linear integer arithmetic | -| `QF_LRA` | Quantifier-free linear real arithmetic | -| `QF_NIA` | Quantifier-free nonlinear integer arithmetic | -| `QF_NRA` | Quantifier-free nonlinear real arithmetic | -| `QF_BV` | Quantifier-free bitvectors | -| `QF_AUFLIA` | Arrays, uninterpreted functions, linear integer arithmetic | -| `ALL` | All supported theories | +[width="100%",cols="35%,65%",options="header",] +|=== +|Logic |Description +|`+QF_LIA+` |Quantifier-free linear integer arithmetic -## API Reference +|`+QF_LRA+` |Quantifier-free linear real arithmetic -### Solver Discovery +|`+QF_NIA+` |Quantifier-free nonlinear integer arithmetic -```julia +|`+QF_NRA+` |Quantifier-free nonlinear real arithmetic + +|`+QF_BV+` |Quantifier-free bitvectors + +|`+QF_AUFLIA+` |Arrays, uninterpreted functions, linear integer +arithmetic + +|`+ALL+` |All supported theories +|=== + +=== API Reference + +==== Solver Discovery + +[source,julia] +---- available_solvers() # List all detected solvers find_solver() # Get first available solver find_solver(:z3) # Get specific solver -``` +---- -### Context Management +==== Context Management -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_LIA, timeout_ms=30000) declare(ctx, :x, Int) # Declare variable assert!(ctx, expr) # Add assertion check_sat(ctx) # Check satisfiability reset!(ctx) # Clear context -``` +---- -### SMT-LIB Conversion +==== SMT-LIB Conversion -```julia +[source,julia] +---- to_smtlib(:(x + y == 10)) # "(= (+ x y) 10)" -``` +---- -### Types +==== Types -```julia +[source,julia] +---- # Built-in types Int, Float64, Bool @@ -138,13 +160,14 @@ BitVec{32} # 32-bit bitvector # Arrays SMTArray{Int, Int} # Array from Int to Int -``` +---- -## Examples +=== Examples -### Sudoku Solver +==== Sudoku Solver -```julia +[source,julia] +---- function solve_sudoku(grid) ctx = SMTContext(logic=:QF_LIA) @@ -160,11 +183,12 @@ function solve_sudoku(grid) result = check_sat(ctx) # Extract solution from result.model end -``` +---- -### Verification +==== Verification -```julia +[source,julia] +---- # Verify array bounds check is sufficient ctx = SMTContext(logic=:QF_LIA) @@ -182,12 +206,13 @@ assert!(ctx, :(i < 0 || i >= n)) result = check_sat(ctx) @assert result.status == :unsat # Proven safe! -``` +---- -## License +=== License MIT License - see LICENSE file. -## Acknowledgments +=== Acknowledgments -Extracted from [Axiom.jl](https://github.com/hyperpolymath/axiom.jl), a provably correct ML framework. +Extracted from https://github.com/hyperpolymath/axiom.jl[Axiom.jl], a +provably correct ML framework. diff --git a/packages/Axiom.jl/templates/README.adoc b/packages/Axiom.jl/templates/README.adoc new file mode 100644 index 000000000..ae0f4ff7c --- /dev/null +++ b/packages/Axiom.jl/templates/README.adoc @@ -0,0 +1,211 @@ +== Axiom.jl Model Zoo Templates + +Verification-ready model templates with formal properties and metadata. + +=== Quick Start + +==== Computer Vision + +[source,julia] +---- +using Axiom + +# ResNet50 for image classification +model, metadata = resnet50_verified(pretrained=true) + +# Verify properties +@prove ∀x ∈ ImageNet. is_finite(model(x)) + +# Inference +predictions = model(load_image("cat.jpg")) +---- + +==== Natural Language Processing + +[source,julia] +---- +using Axiom + +# Transformer encoder +model, metadata = transformer_encoder_verified( + vocab_size=50000, + d_model=768, + n_heads=12 +) + +# Verify attention properties +@prove ∀x. sum(attention_weights(model, x), dims=2) ≈ 1.0 + +# Inference +embeddings = model(tokenize("Hello world")) +---- + +=== Available Templates + +==== Computer Vision + +[width="100%",cols="16%,13%,26%,45%",options="header",] +|=== +|Model |Task |Parameters |Verification Claims +|ResNet50 |Image Classification |25.6M |Lipschitz, finite outputs, +probability bounds + +|MobileNetV2 |Mobile CV |3.5M |Efficient inference, quantization-ready + +|EfficientNet-B0 |Compound Scaling |5.3M |Accuracy-efficiency tradeoffs + +|Vision Transformer (ViT) |Image Classification |86M |Attention +normalization, patch embedding +|=== + +==== Natural Language Processing + +[width="100%",cols="16%,13%,26%,45%",options="header",] +|=== +|Model |Task |Parameters |Verification Claims +|Transformer Encoder |Sequence Modeling |Custom |Attention normalized, +stable embeddings + +|BERT-Base |Masked LM |110M |Token prediction bounds, attention sparsity + +|GPT-2 Small |Autoregressive LM |117M |Causality preserved, generation +stability + +|T5-Small |Seq2Seq |60M |Encoder-decoder alignment +|=== + +=== Model Structure + +Each template provides: + +[arabic] +. *Verified Architecture* - Built with `+@axiom+` macro for shape +checking +. *Metadata* - Complete `+ModelMetadata+` with provenance +. *Verification Claims* - Formal properties verified with `+@prove+` +. *Pretrained Weights* - Optional pretrained checkpoints +. *Documentation* - Usage examples and property specifications + +=== Creating Custom Templates + +==== Basic Template Structure + +[source,julia] +---- +function my_model_verified(; pretrained=false, num_classes=10) + # Define architecture + model = @axiom begin + # ... layers ... + end + + # Load weights if pretrained + if pretrained + load_weights!(model, "path/to/weights.jld2") + end + + # Create metadata + metadata = create_metadata( + model, + name="MyModel", + architecture="Custom", + task="classification", + # ... other fields ... + ) + + # Add verification claims + verify_and_claim!( + metadata, + "Property name", + "Formal specification" + ) + + # Save metadata + save_metadata(metadata, "my_model_metadata.json") + + return model, metadata +end +---- + +==== Verification Best Practices + +[arabic] +. *Start with basic properties*: +* No NaN/Inf propagation +* Output bounds (for probabilities, etc.) +* Input-output relationship preservation +. *Add domain-specific properties*: +* CV: Lipschitz continuity, spatial invariance +* NLP: Attention normalization, causality +. *Test verification overhead*: +* Profile verification time +* Consider caching verified properties +* Use sampling for large input spaces +. *Document limitations*: +* Approximations made +* Assumptions about input distribution +* Verification scope (training vs inference) + +=== Extending Templates + +==== Adding New Architecture + +[arabic] +. Create file in `+templates/{cv,nlp}/my_architecture.jl+` +. Implement `+my_architecture_verified()+` function +. Add verification claims appropriate to architecture +. Create metadata with complete provenance +. Add tests in `+test/templates/+` +. Document in this README + +==== Adding Pretrained Weights + +Weights should be: - Stored in standard format (JLD2, BSON, or +HuggingFace compatible) - Include checksum (SHA256) - Provide download +script or registry link - Include training configuration and metrics + +==== Verification Properties + +Common properties to verify: + +*Stability:* - No NaN/Inf propagation - Bounded gradients (Lipschitz) - +Numerical precision limits + +*Correctness:* - Output shape matches specification - Probability +distributions (sum to 1, non-negative) - Attention weights normalized + +*Robustness:* - Bounded perturbation resistance - Adversarial input +handling - Out-of-distribution detection + +*Performance:* - Inference time bounds - Memory usage limits - Batch +processing guarantees + +=== Integration with HuggingFace + +Import pretrained models from HuggingFace Hub: + +[source,julia] +---- +using Axiom + +# Import with automatic verification +model, metadata = from_pretrained( + "bert-base-uncased", + verify=true, # Verify after import + architecture="transformer" +) + +# Verification results in metadata +for claim in metadata.verification_claims + println("$(claim.property): $(claim.verified ? "✓" : "✗")") +end +---- + +=== See Also + +* link:../src/model_metadata.jl[Model Metadata Schema] +* link:../src/integrations/huggingface.jl[HuggingFace Integration] +* link:../docs/wiki/Verification.md[Verification Guide] +* https://github.com/hyperpolymath/Axiom.jl/issues/15[Issue #15 - +Verified Model Zoo] +* https://github.com/hyperpolymath/Axiom.jl/issues/16[Issue #16 - Model +Metadata] diff --git a/packages/Axiom.jl/templates/README.md b/packages/Axiom.jl/templates/README.md deleted file mode 100644 index 8cb9e032e..000000000 --- a/packages/Axiom.jl/templates/README.md +++ /dev/null @@ -1,200 +0,0 @@ -# Axiom.jl Model Zoo Templates - -Verification-ready model templates with formal properties and metadata. - -## Quick Start - -### Computer Vision - -```julia -using Axiom - -# ResNet50 for image classification -model, metadata = resnet50_verified(pretrained=true) - -# Verify properties -@prove ∀x ∈ ImageNet. is_finite(model(x)) - -# Inference -predictions = model(load_image("cat.jpg")) -``` - -### Natural Language Processing - -```julia -using Axiom - -# Transformer encoder -model, metadata = transformer_encoder_verified( - vocab_size=50000, - d_model=768, - n_heads=12 -) - -# Verify attention properties -@prove ∀x. sum(attention_weights(model, x), dims=2) ≈ 1.0 - -# Inference -embeddings = model(tokenize("Hello world")) -``` - -## Available Templates - -### Computer Vision - -| Model | Task | Parameters | Verification Claims | -|-------|------|------------|---------------------| -| ResNet50 | Image Classification | 25.6M | Lipschitz, finite outputs, probability bounds | -| MobileNetV2 | Mobile CV | 3.5M | Efficient inference, quantization-ready | -| EfficientNet-B0 | Compound Scaling | 5.3M | Accuracy-efficiency tradeoffs | -| Vision Transformer (ViT) | Image Classification | 86M | Attention normalization, patch embedding | - -### Natural Language Processing - -| Model | Task | Parameters | Verification Claims | -|-------|------|------------|---------------------| -| Transformer Encoder | Sequence Modeling | Custom | Attention normalized, stable embeddings | -| BERT-Base | Masked LM | 110M | Token prediction bounds, attention sparsity | -| GPT-2 Small | Autoregressive LM | 117M | Causality preserved, generation stability | -| T5-Small | Seq2Seq | 60M | Encoder-decoder alignment | - -## Model Structure - -Each template provides: - -1. **Verified Architecture** - Built with `@axiom` macro for shape checking -2. **Metadata** - Complete `ModelMetadata` with provenance -3. **Verification Claims** - Formal properties verified with `@prove` -4. **Pretrained Weights** - Optional pretrained checkpoints -5. **Documentation** - Usage examples and property specifications - -## Creating Custom Templates - -### Basic Template Structure - -```julia -function my_model_verified(; pretrained=false, num_classes=10) - # Define architecture - model = @axiom begin - # ... layers ... - end - - # Load weights if pretrained - if pretrained - load_weights!(model, "path/to/weights.jld2") - end - - # Create metadata - metadata = create_metadata( - model, - name="MyModel", - architecture="Custom", - task="classification", - # ... other fields ... - ) - - # Add verification claims - verify_and_claim!( - metadata, - "Property name", - "Formal specification" - ) - - # Save metadata - save_metadata(metadata, "my_model_metadata.json") - - return model, metadata -end -``` - -### Verification Best Practices - -1. **Start with basic properties**: - - No NaN/Inf propagation - - Output bounds (for probabilities, etc.) - - Input-output relationship preservation - -2. **Add domain-specific properties**: - - CV: Lipschitz continuity, spatial invariance - - NLP: Attention normalization, causality - -3. **Test verification overhead**: - - Profile verification time - - Consider caching verified properties - - Use sampling for large input spaces - -4. **Document limitations**: - - Approximations made - - Assumptions about input distribution - - Verification scope (training vs inference) - -## Extending Templates - -### Adding New Architecture - -1. Create file in `templates/{cv,nlp}/my_architecture.jl` -2. Implement `my_architecture_verified()` function -3. Add verification claims appropriate to architecture -4. Create metadata with complete provenance -5. Add tests in `test/templates/` -6. Document in this README - -### Adding Pretrained Weights - -Weights should be: -- Stored in standard format (JLD2, BSON, or HuggingFace compatible) -- Include checksum (SHA256) -- Provide download script or registry link -- Include training configuration and metrics - -### Verification Properties - -Common properties to verify: - -**Stability:** -- No NaN/Inf propagation -- Bounded gradients (Lipschitz) -- Numerical precision limits - -**Correctness:** -- Output shape matches specification -- Probability distributions (sum to 1, non-negative) -- Attention weights normalized - -**Robustness:** -- Bounded perturbation resistance -- Adversarial input handling -- Out-of-distribution detection - -**Performance:** -- Inference time bounds -- Memory usage limits -- Batch processing guarantees - -## Integration with HuggingFace - -Import pretrained models from HuggingFace Hub: - -```julia -using Axiom - -# Import with automatic verification -model, metadata = from_pretrained( - "bert-base-uncased", - verify=true, # Verify after import - architecture="transformer" -) - -# Verification results in metadata -for claim in metadata.verification_claims - println("$(claim.property): $(claim.verified ? "✓" : "✗")") -end -``` - -## See Also - -- [Model Metadata Schema](../src/model_metadata.jl) -- [HuggingFace Integration](../src/integrations/huggingface.jl) -- [Verification Guide](../docs/wiki/Verification.md) -- [Issue #15 - Verified Model Zoo](https://github.com/hyperpolymath/Axiom.jl/issues/15) -- [Issue #16 - Model Metadata](https://github.com/hyperpolymath/Axiom.jl/issues/16) diff --git a/packages/BowtieRisk.jl/ABI-FFI-README.md b/packages/BowtieRisk.jl/ABI-FFI-README.adoc similarity index 75% rename from packages/BowtieRisk.jl/ABI-FFI-README.md rename to packages/BowtieRisk.jl/ABI-FFI-README.adoc index 22d559643..2affd3975 100644 --- a/packages/BowtieRisk.jl/ABI-FFI-README.md +++ b/packages/BowtieRisk.jl/ABI-FFI-README.adoc @@ -1,18 +1,20 @@ +== BowtieRisk ABI/FFI Documentation -# BowtieRisk ABI/FFI Documentation +=== Overview -## Overview +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +=== Architecture -## Architecture - -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -44,11 +46,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... bowtierisk/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -76,15 +78,17 @@ bowtierisk/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -96,13 +100,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -110,13 +115,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -124,13 +130,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -139,71 +146,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/bowtierisk.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -214,13 +228,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "bowtierisk.h" int main() { @@ -236,16 +251,19 @@ int main() { bowtierisk_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -lbowtierisk -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import BowtieRisk.ABI.Foreign main : IO () @@ -258,11 +276,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "bowtierisk")] extern "C" { fn bowtierisk_init() -> *mut std::ffi::c_void; @@ -281,11 +300,12 @@ fn main() { bowtierisk_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const libbowtierisk = "libbowtierisk" function init() @@ -311,27 +331,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -341,44 +364,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/bowtierisk.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/bowtierisk.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License SPDX-License-Identifier: CC-BY-SA-4.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/BowtieRisk.jl/CODE_OF_CONDUCT.adoc b/packages/BowtieRisk.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..1ef35ed77 --- /dev/null +++ b/packages/BowtieRisk.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,340 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +BowtieRisk.jl a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |jonathan.jewell@open.ac.uk |Detailed reports, sensitive +matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The Maintainer Team will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a Maintainer Team member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The Maintainer Team will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* jonathan.jewell@open.ac.uk with subject line "`Appeal: +[Original Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different Maintainer Team member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/BowtieRisk.jl/discussions[Discussion] +(for general questions) +* Email jonathan.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/BowtieRisk.jl/CODE_OF_CONDUCT.md b/packages/BowtieRisk.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 66932bad6..000000000 --- a/packages/BowtieRisk.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,308 +0,0 @@ -# Code of Conduct - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in BowtieRisk.jl a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | jonathan.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The Maintainer Team will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a Maintainer Team member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The Maintainer Team will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** jonathan.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different Maintainer Team member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/BowtieRisk.jl/discussions) (for general questions) -- Email jonathan.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/BowtieRisk.jl/CONTRIBUTING.adoc b/packages/BowtieRisk.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..7eac28aed --- /dev/null +++ b/packages/BowtieRisk.jl/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/BowtieRisk.jl.git cd +BowtieRisk.jl + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create BowtieRisk.jl-dev toolbox enter BowtieRisk.jl-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +BowtieRisk.jl/ ├── 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/BowtieRisk.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/BowtieRisk.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/BowtieRisk.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/BowtieRisk.jl/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/packages/BowtieRisk.jl/CONTRIBUTING.md b/packages/BowtieRisk.jl/CONTRIBUTING.md deleted file mode 100644 index 80ea07ad7..000000000 --- a/packages/BowtieRisk.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/BowtieRisk.jl.git -cd BowtieRisk.jl - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create BowtieRisk.jl-dev -toolbox enter BowtieRisk.jl-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -BowtieRisk.jl/ -├── 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/BowtieRisk.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/BowtieRisk.jl/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/BowtieRisk.jl/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/BowtieRisk.jl/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/packages/BowtieRisk.jl/README.md b/packages/BowtieRisk.jl/README.adoc similarity index 53% rename from packages/BowtieRisk.jl/README.md rename to packages/BowtieRisk.jl/README.adoc index 80a37e1d3..647f77bae 100644 --- a/packages/BowtieRisk.jl/README.md +++ b/packages/BowtieRisk.jl/README.adoc @@ -1,65 +1,75 @@ -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +PMPL-1.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] -# BowtieRisk.jl +== BowtieRisk.jl -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-72%25-yellow)](TOPOLOGY.md) +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-72%25-yellow[Completion +Status]] -BowtieRisk.jl provides a Julia framework for bowtie risk modeling with an -event-chain view, escalation factors, and basic dependency handling. It is -designed to support structured hazard analysis and the assignment of -probabilities similar to tools like RiskyProject. +BowtieRisk.jl provides a Julia framework for bowtie risk modeling with +an event-chain view, escalation factors, and basic dependency handling. +It is designed to support structured hazard analysis and the assignment +of probabilities similar to tools like RiskyProject. -This is a new project scaffold with a small, explicit core model. It focuses on -clear data structures, transparent assumptions, and simple calculations that can -be extended for domain-specific needs. +This is a new project scaffold with a small, explicit core model. It +focuses on clear data structures, transparent assumptions, and simple +calculations that can be extended for domain-specific needs. -## Installation +=== Installation -### From Julia REPL -```julia +==== From Julia REPL + +[source,julia] +---- using Pkg Pkg.add("BowtieRisk") -``` +---- + +==== From Git (Development) -### From Git (Development) -```julia +[source,julia] +---- using Pkg Pkg.add(url="https://github.com/hyperpolymath/BowtieRisk.jl") -``` - -## Core Concepts - -- **Hazard**: the source of potential harm. -- **Threats**: initiating causes that may trigger a top event. -- **Top Event**: the moment control is lost (center of the bowtie). -- **Consequences**: outcomes following the top event. -- **Barriers**: preventive (left side) or mitigative (right side) controls. -- **Escalation factors**: conditions that reduce barrier effectiveness. -- **Dependencies**: shared-cause failures across barrier groups. -- **Simulation**: Monte Carlo evaluation with barrier distributions. -- **Reporting**: Markdown and CSV outputs for sensitivity data. -- **Templates**: built-in starter models for common scenarios. -- **Schema**: JSON schema for UI integrations. -- **Event Chain**: ordered events with probabilities and barriers. - -## Probability Model (Baseline) - -This package assumes independent threats and independent barriers by default. -You can switch to a dependency-aware model for shared-cause failures. Under the -independent assumptions: - -- Threat residual = `p(threat) * Π(1 - barrier_effectiveness)` -- Top event probability = `1 - Π(1 - threat_residual)` -- Consequence probability = `p(top_event) * Π(1 - barrier_effectiveness)` -- Risk score = `probability * severity` - -These formulas are intentionally simple and transparent so they can be replaced -with richer methods later. - -## Quick Start - -```julia +---- + +=== Core Concepts + +* *Hazard*: the source of potential harm. +* *Threats*: initiating causes that may trigger a top event. +* *Top Event*: the moment control is lost (center of the bowtie). +* *Consequences*: outcomes following the top event. +* *Barriers*: preventive (left side) or mitigative (right side) +controls. +* *Escalation factors*: conditions that reduce barrier effectiveness. +* *Dependencies*: shared-cause failures across barrier groups. +* *Simulation*: Monte Carlo evaluation with barrier distributions. +* *Reporting*: Markdown and CSV outputs for sensitivity data. +* *Templates*: built-in starter models for common scenarios. +* *Schema*: JSON schema for UI integrations. +* *Event Chain*: ordered events with probabilities and barriers. + +=== Probability Model (Baseline) + +This package assumes independent threats and independent barriers by +default. You can switch to a dependency-aware model for shared-cause +failures. Under the independent assumptions: + +* Threat residual = `+p(threat) * Π(1 - barrier_effectiveness)+` +* Top event probability = `+1 - Π(1 - threat_residual)+` +* Consequence probability = +`+p(top_event) * Π(1 - barrier_effectiveness)+` +* Risk score = `+probability * severity+` + +These formulas are intentionally simple and transparent so they can be +replaced with richer methods later. + +=== Quick Start + +[source,julia] +---- using BowtieRisk hazard = Hazard(:LossOfContainment, "Loss of containment from vessel") @@ -96,28 +106,32 @@ model = BowtieModel( summary = evaluate(model) println(summary.top_event_probability) -``` +---- -## Diagramming Support +=== Diagramming Support -BowtieRisk.jl includes helpers that export Mermaid or GraphViz diagram specs. -These are design aids for arranging bowtie diagrams. +BowtieRisk.jl includes helpers that export Mermaid or GraphViz diagram +specs. These are design aids for arranging bowtie diagrams. -```julia +[source,julia] +---- spec = to_mermaid(model) println(spec) -``` +---- -```julia +[source,julia] +---- dot = to_graphviz(model) println(dot) -``` +---- -```julia +[source,julia] +---- write_model_json("bowtie.json", model) -``` +---- -```julia +[source,julia] +---- dist = Dict( :ReliefValve => BarrierDistribution(:beta, (2.0, 5.0, 0.0)), :GasDetection => BarrierDistribution(:triangular, (0.2, 0.5, 0.9)), @@ -128,23 +142,26 @@ tornado = sensitivity_tornado(model; delta=0.1) write_report_markdown("report.md", model; tornado_data=tornado) write_tornado_csv("tornado.csv", tornado) -``` +---- -```julia +[source,julia] +---- model = template_model(:process_safety) write_schema_json("bowtie.schema.json") -``` +---- -## Development +=== Development -```bash +[source,bash] +---- julia --project=. -e 'using Pkg; Pkg.instantiate()' julia --project=. -e 'using Pkg; Pkg.test()' -``` +---- -## API Snapshot +=== API Snapshot -```julia +[source,julia] +---- Hazard, Threat, TopEvent, Consequence, Barrier, EscalationFactor ProbabilityModel, ThreatPath, ConsequencePath, BowtieModel Event, EventChain, chain_probability @@ -153,4 +170,4 @@ evaluate, simulate, sensitivity_tornado to_mermaid, to_graphviz write_model_json, read_model_json report_markdown, write_report_markdown, write_tornado_csv -``` +---- diff --git a/packages/BowtieRisk.jl/ROADMAP.adoc b/packages/BowtieRisk.jl/ROADMAP.adoc new file mode 100644 index 000000000..ac4aa5f80 --- /dev/null +++ b/packages/BowtieRisk.jl/ROADMAP.adoc @@ -0,0 +1,160 @@ +== BowtieRisk.jl Development Roadmap + +=== Current State (v1.0) + +Production-ready bowtie risk modeling framework: - Threat/consequence +pathway modeling - Barrier effectiveness analysis - Monte Carlo +simulation with uncertainty propagation - Sensitivity analysis (tornado +diagrams) - Multiple output formats (Mermaid, Graphviz, JSON, Markdown) + +*Status:* Complete with 32 tests, security hardening, and comprehensive +documentation. + +''''' + +=== v1.0 → v1.2 Roadmap (Near-term) + +==== v1.1 - Usability & Visualization (3-6 months) + +*MUST:* - [ ] *Interactive web viewer* - Genie.jl/Franklin.jl app for +exploring bowtie models in browser - [ ] *Barrier degradation over time* +- Time-dependent barrier effectiveness (maintenance schedules, aging) - +[ ] *Multi-hazard models* - Support multiple hazards feeding into shared +barriers - [ ] *Automated report generation* - PDF/HTML reports with +executive summary, diagrams, recommendations + +*SHOULD:* - [ ] *Risk matrix integration* - Likelihood × Impact scoring +with color-coded matrices - [ ] *Barrier dependency modeling* - Common +cause failures, shared resources between barriers - [ ] *Cost-benefit +analysis* - ROI calculation for barrier investments - [ ] *Regulatory +compliance templates* - ISO 31000, NORSOK Z-013, IEC 61511 preset models + +*COULD:* - [ ] *3D bowtie visualization* - Makie.jl interactive 3D +rendering for complex multi-hazard models - [ ] *Mobile app export* - +Generate standalone risk assessment apps for field use - [ ] *Voice +annotations* - Audio notes on threats/barriers for team collaboration + +==== v1.2 - Advanced Analytics & Integration (6-12 months) + +*MUST:* - [ ] *Dynamic risk assessment* - Real-time risk updates based +on sensor data/operational state - [ ] *Probabilistic safety goals* - +Target likelihood levels with optimization for barrier placement - [ ] +*Fault tree integration* - Import FTA models as threat pathways - [ ] +*Event tree integration* - Import ETA models as consequence pathways + +*SHOULD:* - [ ] *Machine learning barrier prediction* - Learn barrier +effectiveness from historical incident data - [ ] *Integration with +Causals.jl* - Causal inference for root cause analysis - [ ] +*Integration with Exnovation.jl* - Risk-driven exnovation prioritization +- [ ] *Multi-objective optimization* - Pareto-optimal barrier +configurations (cost vs. risk reduction) + +*COULD:* - [ ] *Digital twin integration* - Connect to industrial IoT +for live barrier health monitoring - [ ] *Scenario planning* - +"`What-if`" analysis with automated scenario generation - [ ] +*Collaborative modeling* - Multi-user editing with conflict resolution + +''''' + +=== v1.3+ Roadmap (Speculative) + +==== Research Frontiers + +*AI-Enhanced Risk Assessment:* - Generative AI for threat scenario +brainstorming (LLM integration) - Computer vision for barrier inspection +(defect detection from drone imagery) - Predictive maintenance using +time-series forecasting (barrier failure prediction) - Natural language +query interface ("`What’s our highest risk pathway?`") + +*Quantum Risk Modeling:* - Quantum Monte Carlo for +ultra-high-dimensional uncertainty quantification - Quantum optimization +for barrier portfolio selection - Quantum machine learning for anomaly +detection in barrier performance + +*Formal Verification:* - Proof export to Isabelle/HOL for safety case +certification - Verified risk calculations (guaranteed bounds on top +event probability) - Integration with Axiom.jl for theorem-proven safety +properties + +*Industry 4.0 Integration:* - Blockchain-based barrier audit trails +(immutable compliance records) - AR/VR bowtie walkthroughs (immersive +training environments) - Autonomous barrier testing (robotic inspection +of physical safeguards) + +==== Ecosystem Integration + +* *JuMP.jl:* Optimization for barrier resource allocation +* *DifferentialEquations.jl:* Continuous-time risk dynamics (aging, +degradation) +* *Agents.jl:* Agent-based modeling of human factors in barrier +performance +* *DataFrames.jl/Tidier.jl:* Advanced data wrangling for incident +databases + +==== Ambitious Features + +* *Risk foundation model* - Pre-trained on 100K+ industrial incident +reports +* *Autonomous risk assessor* - AI agent that conducts full bowtie +analysis from process description +* *Global risk network* - Federated learning across organizations for +industry-wide risk intelligence +* *Regulatory autopilot* - Automatic compliance checking against +evolving standards + +''''' + +=== Future Horizons (v2.0+) + +==== Immersive & Holographic Risk + +* [ ] *Holographic Control Room*: Beyond 3D, integrate with WebXR/Unity +for real-time holographic "`Risk Dashboards`" in industrial control +rooms. +* [ ] *Digital Twin Walkthroughs*: AR-guided barrier inspections where +the bowtie model is overlaid on physical assets (e.g., seeing "`Barrier +Effectiveness`" on a real valve via AR glasses). + +==== Human & Cognitive Factor Modeling + +* [ ] *Cognitive Barrier Simulation*: Integrate with cognitive +architectures (e.g., ACT-R) to model human error probability under +high-stress/emergency conditions. +* [ ] *Social Barrier Dynamics*: Model how organizational culture and +communication patterns (via `+Agents.jl+`) act as "`soft`" preventive +barriers. + +==== Specialized Risk Domains + +* [ ] *Bio-Security & Synthetic Risk*: Tailored bowtie templates for +high-containment labs, modeling bio-decay and genetic containment as +specific barriers. +* [ ] *Cyber-Physical Attack Pathways*: Integrated modeling of +cyber-attacks as threats that degrade physical safety barriers (e.g., +Stuxnet-style scenarios). + +==== Automated Liability & Insurance + +* [ ] *Liability Attribution Engine*: Mapping barrier failures to legal +liability frameworks and insurance policy clauses automatically. +* [ ] *Smart Contract Insurance Bridge*: Use blockchain-based +"`Axiomatic Oracles`" to trigger insurance payouts automatically when a +verified barrier failure occurs. + +''''' + +=== Migration Path + +*v1.0 → v1.1:* Backward compatible (new features, optional parameters) +*v1.1 → v1.2:* Mostly compatible (FTA/ETA integration may require model +schema updates) *v1.2 → v1.3+:* Breaking changes likely (AI features may +require new data structures) + +=== Community Goals + +* *5 industry case studies* published by v1.2 +* *Integration with major RAMS tools* (CARA, PHA-Pro) by v1.2 +* *Presentation at ESREL conference* (European Safety and Reliability) +by v1.2 +* *Partnership with process safety consultancy* for real-world +validation diff --git a/packages/BowtieRisk.jl/ROADMAP.md b/packages/BowtieRisk.jl/ROADMAP.md deleted file mode 100644 index 25ef39720..000000000 --- a/packages/BowtieRisk.jl/ROADMAP.md +++ /dev/null @@ -1,130 +0,0 @@ -# BowtieRisk.jl Development Roadmap - -## Current State (v1.0) - -Production-ready bowtie risk modeling framework: -- Threat/consequence pathway modeling -- Barrier effectiveness analysis -- Monte Carlo simulation with uncertainty propagation -- Sensitivity analysis (tornado diagrams) -- Multiple output formats (Mermaid, Graphviz, JSON, Markdown) - -**Status:** Complete with 32 tests, security hardening, and comprehensive documentation. - ---- - -## v1.0 → v1.2 Roadmap (Near-term) - -### v1.1 - Usability & Visualization (3-6 months) - -**MUST:** -- [ ] **Interactive web viewer** - Genie.jl/Franklin.jl app for exploring bowtie models in browser -- [ ] **Barrier degradation over time** - Time-dependent barrier effectiveness (maintenance schedules, aging) -- [ ] **Multi-hazard models** - Support multiple hazards feeding into shared barriers -- [ ] **Automated report generation** - PDF/HTML reports with executive summary, diagrams, recommendations - -**SHOULD:** -- [ ] **Risk matrix integration** - Likelihood × Impact scoring with color-coded matrices -- [ ] **Barrier dependency modeling** - Common cause failures, shared resources between barriers -- [ ] **Cost-benefit analysis** - ROI calculation for barrier investments -- [ ] **Regulatory compliance templates** - ISO 31000, NORSOK Z-013, IEC 61511 preset models - -**COULD:** -- [ ] **3D bowtie visualization** - Makie.jl interactive 3D rendering for complex multi-hazard models -- [ ] **Mobile app export** - Generate standalone risk assessment apps for field use -- [ ] **Voice annotations** - Audio notes on threats/barriers for team collaboration - -### v1.2 - Advanced Analytics & Integration (6-12 months) - -**MUST:** -- [ ] **Dynamic risk assessment** - Real-time risk updates based on sensor data/operational state -- [ ] **Probabilistic safety goals** - Target likelihood levels with optimization for barrier placement -- [ ] **Fault tree integration** - Import FTA models as threat pathways -- [ ] **Event tree integration** - Import ETA models as consequence pathways - -**SHOULD:** -- [ ] **Machine learning barrier prediction** - Learn barrier effectiveness from historical incident data -- [ ] **Integration with Causals.jl** - Causal inference for root cause analysis -- [ ] **Integration with Exnovation.jl** - Risk-driven exnovation prioritization -- [ ] **Multi-objective optimization** - Pareto-optimal barrier configurations (cost vs. risk reduction) - -**COULD:** -- [ ] **Digital twin integration** - Connect to industrial IoT for live barrier health monitoring -- [ ] **Scenario planning** - "What-if" analysis with automated scenario generation -- [ ] **Collaborative modeling** - Multi-user editing with conflict resolution - ---- - -## v1.3+ Roadmap (Speculative) - -### Research Frontiers - -**AI-Enhanced Risk Assessment:** -- Generative AI for threat scenario brainstorming (LLM integration) -- Computer vision for barrier inspection (defect detection from drone imagery) -- Predictive maintenance using time-series forecasting (barrier failure prediction) -- Natural language query interface ("What's our highest risk pathway?") - -**Quantum Risk Modeling:** -- Quantum Monte Carlo for ultra-high-dimensional uncertainty quantification -- Quantum optimization for barrier portfolio selection -- Quantum machine learning for anomaly detection in barrier performance - -**Formal Verification:** -- Proof export to Isabelle/HOL for safety case certification -- Verified risk calculations (guaranteed bounds on top event probability) -- Integration with Axiom.jl for theorem-proven safety properties - -**Industry 4.0 Integration:** -- Blockchain-based barrier audit trails (immutable compliance records) -- AR/VR bowtie walkthroughs (immersive training environments) -- Autonomous barrier testing (robotic inspection of physical safeguards) - -### Ecosystem Integration - -- **JuMP.jl:** Optimization for barrier resource allocation -- **DifferentialEquations.jl:** Continuous-time risk dynamics (aging, degradation) -- **Agents.jl:** Agent-based modeling of human factors in barrier performance -- **DataFrames.jl/Tidier.jl:** Advanced data wrangling for incident databases - -### Ambitious Features - -- **Risk foundation model** - Pre-trained on 100K+ industrial incident reports -- **Autonomous risk assessor** - AI agent that conducts full bowtie analysis from process description -- **Global risk network** - Federated learning across organizations for industry-wide risk intelligence -- **Regulatory autopilot** - Automatic compliance checking against evolving standards - ---- - -## Future Horizons (v2.0+) - -### Immersive & Holographic Risk -- [ ] **Holographic Control Room**: Beyond 3D, integrate with WebXR/Unity for real-time holographic "Risk Dashboards" in industrial control rooms. -- [ ] **Digital Twin Walkthroughs**: AR-guided barrier inspections where the bowtie model is overlaid on physical assets (e.g., seeing "Barrier Effectiveness" on a real valve via AR glasses). - -### Human & Cognitive Factor Modeling -- [ ] **Cognitive Barrier Simulation**: Integrate with cognitive architectures (e.g., ACT-R) to model human error probability under high-stress/emergency conditions. -- [ ] **Social Barrier Dynamics**: Model how organizational culture and communication patterns (via `Agents.jl`) act as "soft" preventive barriers. - -### Specialized Risk Domains -- [ ] **Bio-Security & Synthetic Risk**: Tailored bowtie templates for high-containment labs, modeling bio-decay and genetic containment as specific barriers. -- [ ] **Cyber-Physical Attack Pathways**: Integrated modeling of cyber-attacks as threats that degrade physical safety barriers (e.g., Stuxnet-style scenarios). - -### Automated Liability & Insurance -- [ ] **Liability Attribution Engine**: Mapping barrier failures to legal liability frameworks and insurance policy clauses automatically. -- [ ] **Smart Contract Insurance Bridge**: Use blockchain-based "Axiomatic Oracles" to trigger insurance payouts automatically when a verified barrier failure occurs. - ---- - -## Migration Path - -**v1.0 → v1.1:** Backward compatible (new features, optional parameters) -**v1.1 → v1.2:** Mostly compatible (FTA/ETA integration may require model schema updates) -**v1.2 → v1.3+:** Breaking changes likely (AI features may require new data structures) - -## Community Goals - -- **5 industry case studies** published by v1.2 -- **Integration with major RAMS tools** (CARA, PHA-Pro) by v1.2 -- **Presentation at ESREL conference** (European Safety and Reliability) by v1.2 -- **Partnership with process safety consultancy** for real-world validation diff --git a/packages/BowtieRisk.jl/SECURITY.adoc b/packages/BowtieRisk.jl/SECURITY.adoc new file mode 100644 index 000000000..1e0841adb --- /dev/null +++ b/packages/BowtieRisk.jl/SECURITY.adoc @@ -0,0 +1,372 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/BowtieRisk.jl/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |jonathan.jewell@open.ac.uk +|*PGP Key* |https://keybase.io/hyperpolymath[Download Public Key] +|*Fingerprint* |`+Not yet configured+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://keybase.io/hyperpolymath | gpg --import + +# Verify fingerprint +gpg --fingerprint jonathan.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient jonathan.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/BowtieRisk.jl+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/BowtieRisk.jl/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions diff --git a/packages/BowtieRisk.jl/SECURITY.md b/packages/BowtieRisk.jl/SECURITY.md deleted file mode 100644 index dd9162689..000000000 --- a/packages/BowtieRisk.jl/SECURITY.md +++ /dev/null @@ -1,320 +0,0 @@ -# Security Policy - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/BowtieRisk.jl/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | jonathan.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://keybase.io/hyperpolymath) | -| **Fingerprint** | `Not yet configured` | - -```bash -# Import our PGP key -curl -sSL https://keybase.io/hyperpolymath | gpg --import - -# Verify fingerprint -gpg --fingerprint jonathan.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient jonathan.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/BowtieRisk.jl`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/BowtieRisk.jl/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - diff --git a/packages/BowtieRisk.jl/SONNET-TASKS.adoc b/packages/BowtieRisk.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..12726753b --- /dev/null +++ b/packages/BowtieRisk.jl/SONNET-TASKS.adoc @@ -0,0 +1,472 @@ +== SONNET-TASKS.md — BowtieRisk.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 72% +____ + +The Julia core (`+src/BowtieRisk.jl+`) is genuinely functional – types, +evaluate, simulate, sensitivity_tornado, serialization, diagramming, +templates, and CSV import all work and have real implementations with +real tests. However, there are significant problems elsewhere: the RSR +template files (ABI/FFI, contractiles, SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, CITATIONS.adoc, examples, docs, ROADMAP.adoc) were +never customized from the template and still contain `+{{PROJECT}}+`, +`+{{project}}+`, `+{{OWNER}}+`, `+{{REPO}}+`, `+{{FORGE}}+` +placeholders. Several files use the banned AGPL-3.0 license header +instead of MPL-2.0. The `+.machine_readable/+` directory with SCM files +is entirely missing. The Documenter.jl docs reference a non-existent +`+api.md+`. The test suite has dead code (testing for templates and +fields that do not exist). The examples directory contains ReScript +SafeDOM code that has nothing to do with BowtieRisk.jl. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update STATE.scm with honest completion percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/BowtieRisk.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix AGPL-3.0 license headers to MPL-2.0 (CRITICAL) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/examples/SafeDOMExample.res+` +(line 1) - `+/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/build.zig+` (line 2) - +`+/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/src/main.zig+` (line 6) - +`+/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/test/integration_test.zig+` (line +2) - `+/var$REPOS_DIR/BowtieRisk.jl/docs/CITATIONS.adoc+` (line 13) + +*Problem:* These files use `+SPDX-License-Identifier: CC-BY-SA-4.0+` or +`+license = {AGPL-3.0-or-later}+`. Per CLAUDE.md license policy, +AGPL-3.0 is NEVER allowed. All hyperpolymath original code must use +MPL-2.0. + +*What to do:* 1. In each file listed, replace `+AGPL-3.0-or-later+` with +`+MPL-2.0+`. 2. In `+docs/CITATIONS.adoc+` line 13, change +`+license = {AGPL-3.0-or-later}+` to `+license = {MPL-2.0}+`. 3. Also +update the citation to reference `+BowtieRisk.jl+` instead of +`+RSR-template-repo+` (lines 8-15) – fix `+author+`, `+title+`, and +`+url+` fields. + +*Verification:* + +[source,bash] +---- +grep -rn "AGPL" /var$REPOS_DIR/BowtieRisk.jl/ | grep -v ".git/" | grep -v "SONNET-TASKS" +# Expected: zero lines of output +---- + +''''' + +=== TASK 2: Replace all RSR template placeholders (CRITICAL) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/CONTRIBUTING.md+` (lines 2, 3, +9, 10, 20, 89-92) - `+/var$REPOS_DIR/BowtieRisk.jl/CODE_OF_CONDUCT.md+` +(lines 9, 10, 313) - `+/var$REPOS_DIR/BowtieRisk.jl/SECURITY.md+` (lines +9, 10, 43, 206, 325, 374, 386, 387) - +`+/var$REPOS_DIR/BowtieRisk.jl/ABI-FFI-README.md+` (lines 3, 29, 42, 53, +70, 74, 202, 225, 228, 231, 233, 237, 244, 250, 267, 269-271, 276, 279, +282, 290, 293, 299, 304, 358) - +`+/var$REPOS_DIR/BowtieRisk.jl/src/abi/Types.idr+` (lines 6, 11) - +`+/var$REPOS_DIR/BowtieRisk.jl/src/abi/Layout.idr+` (lines 8, 10) - +`+/var$REPOS_DIR/BowtieRisk.jl/src/abi/Foreign.idr+` (lines 9, 11, 12, +23, 35, 49, 72, 77, 98, 125, 152, 164, 185, 211) - +`+/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/build.zig+` (lines 1, 12, 23, 35, +36, 82) - `+/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/src/main.zig+` (lines +1, 12, 54, 73, 89, 113, 135, 148, 184, 198, 203, 215, 246, 256, 257, +259, 263, 266, 271) - +`+/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/test/integration_test.zig+` +(lines 1, 10-17, 24-25, 31-32, 34, 39, 48-49, 51, 56, 65-66, 68-69, 75, +84, 86, 96-97, 99, 110, 117, 129-130, 132-133, 138-139, 143, 145-146, +150, 158-159, 168) + +*Problem:* Dozens of files still contain `+{{PROJECT}}+`, +`+{{project}}+`, `+{{OWNER}}+`, `+{{REPO}}+`, `+{{FORGE}}+` template +placeholders from the RSR template repo. + +*What to do:* 1. Replace `+{{PROJECT}}+` with `+BowtieRisk+` (used in +Idris module names, Zig comments) 2. Replace `+{{project}}+` with +`+bowtierisk+` (used in C function names, library names) 3. Replace +`+{{OWNER}}+` with `+hyperpolymath+` 4. Replace `+{{REPO}}+` with +`+BowtieRisk.jl+` 5. Replace `+{{FORGE}}+` with `+github.com+` 6. +Replace `+{{SECURITY_EMAIL}}+` with `+jonathan.jewell@open.ac.uk+` (in +SECURITY.md) 7. Do a global search to confirm zero remaining `+{{+` +patterns. + +*Verification:* + +[source,bash] +---- +grep -rn '{{' /var$REPOS_DIR/BowtieRisk.jl/ --include="*.md" --include="*.adoc" --include="*.idr" --include="*.zig" --include="*.res" --include="*.json" | grep -v ".git/" | grep -v "SONNET-TASKS" +# Expected: zero lines of output +---- + +''''' + +=== TASK 3: Remove irrelevant SafeDOM example, add actual Julia example (HIGH) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/examples/SafeDOMExample.res+` +(DELETE) - +`+/var$REPOS_DIR/BowtieRisk.jl/examples/web-project-deno.json+` (DELETE) +- `+/var$REPOS_DIR/BowtieRisk.jl/examples/basic_bowtie.jl+` (CREATE) + +*Problem:* The `+examples/+` directory contains a ReScript SafeDOM +example and a Deno config file. Neither has anything to do with +BowtieRisk.jl. These are template leftovers. + +*What to do:* 1. Delete `+examples/SafeDOMExample.res+` and +`+examples/web-project-deno.json+`. 2. Create +`+examples/basic_bowtie.jl+` with a working example that: - Builds a +simple bowtie model (use the process_safety template or construct +manually) - Calls `+evaluate()+` and prints the summary - Runs +`+simulate()+` with Beta and Triangular distributions - Generates a +tornado chart - Writes a markdown report - Exports Mermaid and GraphViz +diagrams - Shows JSON round-trip (write_model_json / read_model_json) 3. +Add SPDX header `+# SPDX-License-Identifier: CC-BY-SA-4.0+` at top. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/BowtieRisk.jl") +include("examples/basic_bowtie.jl") +# Expected: runs without error, prints summary data, creates temporary output files +---- + +''''' + +=== TASK 4: Create missing .machine_readable/ directory with SCM files (HIGH) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/.machine_readable/STATE.scm+` +(CREATE) - `+/var$REPOS_DIR/BowtieRisk.jl/.machine_readable/META.scm+` +(CREATE) - +`+/var$REPOS_DIR/BowtieRisk.jl/.machine_readable/ECOSYSTEM.scm+` +(CREATE) + +*Problem:* The `+.machine_readable/+` directory is entirely missing. Per +CLAUDE.md checkpoint file protocol, every repo MUST have STATE.scm, +META.scm, and ECOSYSTEM.scm in `+.machine_readable/+`. They must NEVER +be in the repository root. + +*What to do:* 1. Create directory `+.machine_readable/+`. 2. Create +`+STATE.scm+` with: - metadata section (name: BowtieRisk.jl, version: +1.0.0, language: Julia) - current-position section (phase: production, +completion: 72%) - blockers: template placeholders, missing docs, +missing examples - critical-next-actions: complete SONNET-TASKS 3. +Create `+META.scm+` with: - architecture-decisions: Julia structs are +immutable for safety, JSON3 for serialization, Monte Carlo via +Distributions.jl - development-practices: test-driven, MPL-2.0 license +4. Create `+ECOSYSTEM.scm+` with: - type: julia-package - purpose: +bowtie risk modeling framework - related-projects: Distributions.jl, +JSON3.jl - position-in-ecosystem: standalone risk analysis tool 5. Use +Guile Scheme s-expression format consistent with other repos. + +*Verification:* + +[source,bash] +---- +test -f /var$REPOS_DIR/BowtieRisk.jl/.machine_readable/STATE.scm && \ +test -f /var$REPOS_DIR/BowtieRisk.jl/.machine_readable/META.scm && \ +test -f /var$REPOS_DIR/BowtieRisk.jl/.machine_readable/ECOSYSTEM.scm && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 5: Fix Documenter.jl – create missing api.md page (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/docs/src/api.md+` (CREATE) - +`+/var$REPOS_DIR/BowtieRisk.jl/docs/src/index.md+` (line 17: "`Examples +coming soon`") - `+/var$REPOS_DIR/BowtieRisk.jl/docs/make.jl+` (already +references `+api.md+` at line 12) + +*Problem:* `+docs/make.jl+` at line 12 declares +`+pages = ["Home" => "index.md", "API" => "api.md"]+` but +`+docs/src/api.md+` does not exist. The docs build will fail. Also, +`+index.md+` line 17 says "`Examples coming soon`" which is a +placeholder. + +*What to do:* 1. Create `+docs/src/api.md+` with Documenter.jl `+@docs+` +blocks for all exported symbols: - Hazard, Threat, TopEvent, +Consequence, Barrier, EscalationFactor - ProbabilityModel, ThreatPath, +ConsequencePath, BowtieModel - BarrierDistribution, SimulationResult - +Event, EventChain, chain_probability - evaluate, to_mermaid, to_graphviz +- simulate, sensitivity_tornado - report_markdown, +write_report_markdown, write_tornado_csv - write_model_json, +read_model_json - list_templates, template_model - write_schema_json, +model_schema - load_simple_csv 2. In `+docs/src/index.md+`, replace "`# +Examples coming soon`" with an actual brief example (copy from README.md +Quick Start section, abbreviated). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/BowtieRisk.jl") +using Pkg; Pkg.activate("docs") +Pkg.develop(path=".") +Pkg.add("Documenter") +include("docs/make.jl") +# Expected: docs build succeeds without warnings about missing pages +---- + +''''' + +=== TASK 6: Fix test suite dead code and add missing template tests (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/test/runtests.jl+` (lines 118, +157-167) + +*Problem:* - Line 118: +`+@test hasproperty(sim, :top_event_std) || true+` – +`+SimulationResult+` does NOT have a `+top_event_std+` field (line +141-145 of BowtieRisk.jl). `+hasproperty+` will return `+false+`, but +`+|| true+` makes the test always pass. This is dead code that hides a +missing feature. - Lines 157-167: The loop tests templates +`+:cybersecurity+` and `+:operational+`, but `+template_model+` only +supports `+:process_safety+` and `+:cyber_incident+`. The `+try/catch+` +silently swallows the errors with `+@test true+`. This masks the fact +that the test is referencing wrong template names. + +*What to do:* 1. Line 118: Either implement `+top_event_std+` in +`+SimulationResult+` (add standard deviation calculation in +`+simulate+`) OR remove the dead test. Recommendation: add +`+top_event_std::Float64+` to `+SimulationResult+` (line 141) and +compute it in `+simulate+` (line 304). - Add field: +`+top_event_std::Float64+` to `+SimulationResult+` - Compute: +`+top_std = sqrt(sum((v - top_mean)^2 for v in top_vals) / length(top_vals))+` +in `+simulate+` - Update the constructor call at line 304 to include the +std value - Fix test line 118 to: `+@test sim.top_event_std >= 0.0+` 2. +Lines 157-167: Fix template names to match actual implementations: - +Replace `+:cybersecurity+` with `+:cyber_incident+` - Replace +`+:operational+` with… there is no third template. Remove +`+:operational+` from the loop or implement an `+:operational+` template +in `+template_model+`. - Remove the `+try/catch+` – templates that exist +should not throw. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/BowtieRisk.jl") +using Pkg; Pkg.test() +# Expected: all tests pass, no silently caught errors +---- + +''''' + +=== TASK 7: Customize ROADMAP.adoc from template boilerplate (LOW) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/ROADMAP.adoc+` + +*Problem:* `+ROADMAP.adoc+` still contains the RSR template boilerplate +("`YOUR Template Repo Roadmap`", "`Initial development phase`", generic +milestones). Meanwhile `+ROADMAP.md+` has real BowtieRisk.jl-specific +content. Having two conflicting ROADMAP files is confusing. + +*What to do:* 1. Delete `+ROADMAP.adoc+` entirely. The `+ROADMAP.md+` +already has comprehensive, project-specific roadmap content. 2. +Alternatively, if both formats are needed: replace the content of +`+ROADMAP.adoc+` with an AsciiDoc version of `+ROADMAP.md+` content and +delete `+ROADMAP.md+`. Pick ONE format. + +*Verification:* + +[source,bash] +---- +ls /var$REPOS_DIR/BowtieRisk.jl/ROADMAP* +# Expected: exactly one ROADMAP file (either .md or .adoc, not both) +---- + +''''' + +=== TASK 8: Customize CITATIONS.adoc for BowtieRisk.jl (LOW) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/docs/CITATIONS.adoc+` + +*Problem:* Lines 8-15 still reference `+rsr-template-repo+` and +`+Polymath, Hyper+` as author. This is the template boilerplate. + +*What to do:* 1. Replace `+rsr-template-repo_2025+` with +`+bowtierisk_jl_2025+` (BibTeX key) 2. Replace +`+author = {Polymath, Hyper}+` with `+author = {Jewell, Jonathan D.A.}+` +3. Replace `+title = {RSR-template-repo}+` with +`+title = {BowtieRisk.jl}+` 4. Replace year `+2025+` with `+2026+` 5. +Replace all `+url+` values from +`+https://github.com/hyperpolymath/RSR-template-repo+` to +`+https://github.com/hyperpolymath/BowtieRisk.jl+` 6. Update Harvard, +OSCOLA, MLA, APA 7 sections similarly. + +*Verification:* + +[source,bash] +---- +grep -c "RSR-template-repo\|Polymath, Hyper\|Polymath, H\.\|Hyper Polymath" /var$REPOS_DIR/BowtieRisk.jl/docs/CITATIONS.adoc +# Expected: 0 +---- + +''''' + +=== TASK 9: Customize README.adoc from template boilerplate (LOW) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/README.adoc+` + +*Problem:* `+README.adoc+` still says "`This is your repo - don’t forget +to rename me!`" (line 3) and contains RSR template instructions about +SafeDOM, ReScript, Idris2, etc. None of this is relevant to +BowtieRisk.jl. Meanwhile `+README.md+` has the real project README. + +*What to do:* 1. Delete `+README.adoc+` entirely. `+README.md+` already +exists with complete, correct content. 2. GitHub will display +`+README.md+` by default. + +*Verification:* + +[source,bash] +---- +test ! -f /var$REPOS_DIR/BowtieRisk.jl/README.adoc && test -f /var$REPOS_DIR/BowtieRisk.jl/README.md && echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 10: Add consequence-side sensitivity to sensitivity_tornado (LOW) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/src/BowtieRisk.jl+` (lines +310-336) + +*Problem:* `+sensitivity_tornado+` only perturbs barriers on +`+model.threat_paths+` (lines 314-331). It completely ignores barriers +on `+model.consequence_paths+`. This means mitigative barriers are +invisible to the sensitivity analysis, which defeats the purpose of a +bowtie (which has barriers on both sides). + +*What to do:* 1. After the existing threat_paths loop (line 332), add a +second loop over `+model.consequence_paths+`: +`+julia for (pidx, path) in enumerate(model.consequence_paths) for (bidx, barrier) in enumerate(path.barriers) lower = clamp(barrier.effectiveness - delta, 0.0, 1.0) upper = clamp(barrier.effectiveness + delta, 0.0, 1.0) low_barrier = Barrier(barrier.name, lower, barrier.kind, barrier.description, barrier.degradation, barrier.dependency) high_barrier = Barrier(barrier.name, upper, barrier.kind, barrier.description, barrier.degradation, barrier.dependency) low_cons = deepcopy(model.consequence_paths) high_cons = deepcopy(model.consequence_paths) low_cons[pidx].barriers[bidx] = low_barrier high_cons[pidx].barriers[bidx] = high_barrier low_model = BowtieModel(model.hazard, model.top_event, model.threat_paths, low_cons, model.probability_model) high_model = BowtieModel(model.hazard, model.top_event, model.threat_paths, high_cons, model.probability_model) push!(results, (barrier.name, evaluate(low_model).top_event_probability, evaluate(high_model).top_event_probability)) end end+` +2. Note: The consequence-side barriers do NOT affect +`+top_event_probability+` – they affect `+consequence_probabilities+`. +Consider whether the tornado should return consequence-level sensitivity +instead. If so, change the pushed tuple to include consequence impact, +or add a separate function `+sensitivity_tornado_consequences+`. 3. At +minimum, add a test that verifies mitigative barriers appear in tornado +output when there are consequence-path barriers. + +*Verification:* + +[source,julia] +---- +using BowtieRisk +model = template_model(:process_safety) +tornado = sensitivity_tornado(model; delta=0.1) +barrier_names = [t[1] for t in tornado] +@assert :GasDetection in barrier_names "Mitigative barrier GasDetection should appear in tornado" +---- + +''''' + +=== TASK 11: Add missing `+api.md+` Documenter pages reference for BowtieSummary (LOW) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/src/BowtieRisk.jl+` (lines +7-17 exports, line 244) + +*Problem:* `+BowtieSummary+` (line 244) is a return type from +`+evaluate()+` but is NOT exported. Users calling `+evaluate(model)+` +get back a `+BowtieSummary+` struct and must access +`+.top_event_probability+`, `+.threat_residuals+`, +`+.consequence_probabilities+`, `+.consequence_risks+` – but they cannot +reference the type by name without `+BowtieRisk.BowtieSummary+`. + +*What to do:* 1. Add `+BowtieSummary+` to the export list at line 8 or +9. 2. If you created `+api.md+` in Task 5, add a `+@docs BowtieSummary+` +entry. + +*Verification:* + +[source,julia] +---- +using BowtieRisk +summary = evaluate(template_model(:process_safety)) +@assert summary isa BowtieSummary "BowtieSummary should be exported and accessible" +---- + +''''' + +=== TASK 12: Model schema is too shallow – add property definitions (LOW) + +*Files:* - `+/var$REPOS_DIR/BowtieRisk.jl/src/BowtieRisk.jl+` (lines +432-446) + +*Problem:* `+model_schema()+` returns a JSON schema where every property +is just `+Dict("type" => "object")+` or `+Dict("type" => "array")+`. +This is not useful for validation – it would accept any JSON object as a +valid bowtie model. The schema should define nested properties for +hazard, threat_paths, consequence_paths, etc. + +*What to do:* 1. Expand the schema to define nested properties. For +example: - `+hazard+` should have +`+properties: { name: { type: "string" }, description: { type: "string" } }+` +- `+threat_paths+` items should have `+threat+`, `+barriers+`, +`+escalation_factors+` - `+barriers+` items should have `+name+`, +`+effectiveness+`, `+kind+`, `+description+`, `+degradation+`, +`+dependency+` 2. This should match what `+write_model_json+` actually +produces (lines 566-614). 3. Add `+"additionalProperties" => false+` +where appropriate. + +*Verification:* + +[source,julia] +---- +using BowtieRisk, JSON3 +schema = model_schema() +# Check hazard has nested properties +@assert haskey(schema["properties"]["hazard"], "properties") "hazard schema should have nested properties" +@assert haskey(schema["properties"]["hazard"]["properties"], "name") "hazard should require name" +---- + +''''' + +=== FINAL VERIFICATION + +After completing all tasks, run: + +[source,bash] +---- +cd /var$REPOS_DIR/BowtieRisk.jl + +# 1. All tests pass +julia --project=. -e 'using Pkg; Pkg.test()' + +# 2. No template placeholders remain +grep -rn '{{' . --include="*.md" --include="*.adoc" --include="*.idr" --include="*.zig" --include="*.res" --include="*.json" --include="*.jl" | grep -v ".git/" | grep -v "SONNET-TASKS" + +# 3. No AGPL references remain +grep -rn "AGPL" . | grep -v ".git/" | grep -v "SONNET-TASKS" + +# 4. SCM files exist +ls -la .machine_readable/STATE.scm .machine_readable/META.scm .machine_readable/ECOSYSTEM.scm + +# 5. No duplicate README/ROADMAP +ls README* ROADMAP* + +# 6. Example runs +julia --project=. examples/basic_bowtie.jl + +# 7. BowtieSummary is exported +julia --project=. -e 'using BowtieRisk; s = evaluate(template_model(:process_safety)); @assert s isa BowtieSummary' + +# 8. Docs build (optional, requires Documenter.jl) +# julia --project=docs docs/make.jl +---- + +All 8 checks must pass. If any fail, trace back to the relevant task and +fix. diff --git a/packages/BowtieRisk.jl/SONNET-TASKS.md b/packages/BowtieRisk.jl/SONNET-TASKS.md deleted file mode 100644 index 08d844b71..000000000 --- a/packages/BowtieRisk.jl/SONNET-TASKS.md +++ /dev/null @@ -1,399 +0,0 @@ -# SONNET-TASKS.md — BowtieRisk.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 72% - -The Julia core (`src/BowtieRisk.jl`) is genuinely functional -- types, evaluate, simulate, -sensitivity_tornado, serialization, diagramming, templates, and CSV import all work and have -real implementations with real tests. However, there are significant problems elsewhere: -the RSR template files (ABI/FFI, contractiles, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, -CITATIONS.adoc, examples, docs, ROADMAP.adoc) were never customized from the template and -still contain `{{PROJECT}}`, `{{project}}`, `{{OWNER}}`, `{{REPO}}`, `{{FORGE}}` placeholders. -Several files use the banned AGPL-3.0 license header instead of MPL-2.0. The -`.machine_readable/` directory with SCM files is entirely missing. The Documenter.jl docs -reference a non-existent `api.md`. The test suite has dead code (testing for templates and -fields that do not exist). The examples directory contains ReScript SafeDOM code that has -nothing to do with BowtieRisk.jl. - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update STATE.scm with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/BowtieRisk.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix AGPL-3.0 license headers to MPL-2.0 (CRITICAL) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/examples/SafeDOMExample.res` (line 1) -- `/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/build.zig` (line 2) -- `/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/src/main.zig` (line 6) -- `/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/test/integration_test.zig` (line 2) -- `/var$REPOS_DIR/BowtieRisk.jl/docs/CITATIONS.adoc` (line 13) - -**Problem:** These files use `SPDX-License-Identifier: CC-BY-SA-4.0` or `license = {AGPL-3.0-or-later}`. Per CLAUDE.md license policy, AGPL-3.0 is NEVER allowed. All hyperpolymath original code must use MPL-2.0. - -**What to do:** -1. In each file listed, replace `AGPL-3.0-or-later` with `MPL-2.0`. -2. In `docs/CITATIONS.adoc` line 13, change `license = {AGPL-3.0-or-later}` to `license = {MPL-2.0}`. -3. Also update the citation to reference `BowtieRisk.jl` instead of `RSR-template-repo` (lines 8-15) -- fix `author`, `title`, and `url` fields. - -**Verification:** -```bash -grep -rn "AGPL" /var$REPOS_DIR/BowtieRisk.jl/ | grep -v ".git/" | grep -v "SONNET-TASKS" -# Expected: zero lines of output -``` - ---- - -## TASK 2: Replace all RSR template placeholders (CRITICAL) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/CONTRIBUTING.md` (lines 2, 3, 9, 10, 20, 89-92) -- `/var$REPOS_DIR/BowtieRisk.jl/CODE_OF_CONDUCT.md` (lines 9, 10, 313) -- `/var$REPOS_DIR/BowtieRisk.jl/SECURITY.md` (lines 9, 10, 43, 206, 325, 374, 386, 387) -- `/var$REPOS_DIR/BowtieRisk.jl/ABI-FFI-README.md` (lines 3, 29, 42, 53, 70, 74, 202, 225, 228, 231, 233, 237, 244, 250, 267, 269-271, 276, 279, 282, 290, 293, 299, 304, 358) -- `/var$REPOS_DIR/BowtieRisk.jl/src/abi/Types.idr` (lines 6, 11) -- `/var$REPOS_DIR/BowtieRisk.jl/src/abi/Layout.idr` (lines 8, 10) -- `/var$REPOS_DIR/BowtieRisk.jl/src/abi/Foreign.idr` (lines 9, 11, 12, 23, 35, 49, 72, 77, 98, 125, 152, 164, 185, 211) -- `/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/build.zig` (lines 1, 12, 23, 35, 36, 82) -- `/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/src/main.zig` (lines 1, 12, 54, 73, 89, 113, 135, 148, 184, 198, 203, 215, 246, 256, 257, 259, 263, 266, 271) -- `/var$REPOS_DIR/BowtieRisk.jl/ffi/zig/test/integration_test.zig` (lines 1, 10-17, 24-25, 31-32, 34, 39, 48-49, 51, 56, 65-66, 68-69, 75, 84, 86, 96-97, 99, 110, 117, 129-130, 132-133, 138-139, 143, 145-146, 150, 158-159, 168) - -**Problem:** Dozens of files still contain `{{PROJECT}}`, `{{project}}`, `{{OWNER}}`, `{{REPO}}`, `{{FORGE}}` template placeholders from the RSR template repo. - -**What to do:** -1. Replace `{{PROJECT}}` with `BowtieRisk` (used in Idris module names, Zig comments) -2. Replace `{{project}}` with `bowtierisk` (used in C function names, library names) -3. Replace `{{OWNER}}` with `hyperpolymath` -4. Replace `{{REPO}}` with `BowtieRisk.jl` -5. Replace `{{FORGE}}` with `github.com` -6. Replace `{{SECURITY_EMAIL}}` with `jonathan.jewell@open.ac.uk` (in SECURITY.md) -7. Do a global search to confirm zero remaining `{{` patterns. - -**Verification:** -```bash -grep -rn '{{' /var$REPOS_DIR/BowtieRisk.jl/ --include="*.md" --include="*.adoc" --include="*.idr" --include="*.zig" --include="*.res" --include="*.json" | grep -v ".git/" | grep -v "SONNET-TASKS" -# Expected: zero lines of output -``` - ---- - -## TASK 3: Remove irrelevant SafeDOM example, add actual Julia example (HIGH) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/examples/SafeDOMExample.res` (DELETE) -- `/var$REPOS_DIR/BowtieRisk.jl/examples/web-project-deno.json` (DELETE) -- `/var$REPOS_DIR/BowtieRisk.jl/examples/basic_bowtie.jl` (CREATE) - -**Problem:** The `examples/` directory contains a ReScript SafeDOM example and a Deno config file. Neither has anything to do with BowtieRisk.jl. These are template leftovers. - -**What to do:** -1. Delete `examples/SafeDOMExample.res` and `examples/web-project-deno.json`. -2. Create `examples/basic_bowtie.jl` with a working example that: - - Builds a simple bowtie model (use the process_safety template or construct manually) - - Calls `evaluate()` and prints the summary - - Runs `simulate()` with Beta and Triangular distributions - - Generates a tornado chart - - Writes a markdown report - - Exports Mermaid and GraphViz diagrams - - Shows JSON round-trip (write_model_json / read_model_json) -3. Add SPDX header `# SPDX-License-Identifier: CC-BY-SA-4.0` at top. - -**Verification:** -```julia -cd("/var$REPOS_DIR/BowtieRisk.jl") -include("examples/basic_bowtie.jl") -# Expected: runs without error, prints summary data, creates temporary output files -``` - ---- - -## TASK 4: Create missing .machine_readable/ directory with SCM files (HIGH) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/.machine_readable/STATE.scm` (CREATE) -- `/var$REPOS_DIR/BowtieRisk.jl/.machine_readable/META.scm` (CREATE) -- `/var$REPOS_DIR/BowtieRisk.jl/.machine_readable/ECOSYSTEM.scm` (CREATE) - -**Problem:** The `.machine_readable/` directory is entirely missing. Per CLAUDE.md checkpoint file protocol, every repo MUST have STATE.scm, META.scm, and ECOSYSTEM.scm in `.machine_readable/`. They must NEVER be in the repository root. - -**What to do:** -1. Create directory `.machine_readable/`. -2. Create `STATE.scm` with: - - metadata section (name: BowtieRisk.jl, version: 1.0.0, language: Julia) - - current-position section (phase: production, completion: 72%) - - blockers: template placeholders, missing docs, missing examples - - critical-next-actions: complete SONNET-TASKS -3. Create `META.scm` with: - - architecture-decisions: Julia structs are immutable for safety, JSON3 for serialization, Monte Carlo via Distributions.jl - - development-practices: test-driven, MPL-2.0 license -4. Create `ECOSYSTEM.scm` with: - - type: julia-package - - purpose: bowtie risk modeling framework - - related-projects: Distributions.jl, JSON3.jl - - position-in-ecosystem: standalone risk analysis tool -5. Use Guile Scheme s-expression format consistent with other repos. - -**Verification:** -```bash -test -f /var$REPOS_DIR/BowtieRisk.jl/.machine_readable/STATE.scm && \ -test -f /var$REPOS_DIR/BowtieRisk.jl/.machine_readable/META.scm && \ -test -f /var$REPOS_DIR/BowtieRisk.jl/.machine_readable/ECOSYSTEM.scm && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 5: Fix Documenter.jl -- create missing api.md page (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/docs/src/api.md` (CREATE) -- `/var$REPOS_DIR/BowtieRisk.jl/docs/src/index.md` (line 17: "Examples coming soon") -- `/var$REPOS_DIR/BowtieRisk.jl/docs/make.jl` (already references `api.md` at line 12) - -**Problem:** `docs/make.jl` at line 12 declares `pages = ["Home" => "index.md", "API" => "api.md"]` but `docs/src/api.md` does not exist. The docs build will fail. Also, `index.md` line 17 says "Examples coming soon" which is a placeholder. - -**What to do:** -1. Create `docs/src/api.md` with Documenter.jl `@docs` blocks for all exported symbols: - - Hazard, Threat, TopEvent, Consequence, Barrier, EscalationFactor - - ProbabilityModel, ThreatPath, ConsequencePath, BowtieModel - - BarrierDistribution, SimulationResult - - Event, EventChain, chain_probability - - evaluate, to_mermaid, to_graphviz - - simulate, sensitivity_tornado - - report_markdown, write_report_markdown, write_tornado_csv - - write_model_json, read_model_json - - list_templates, template_model - - write_schema_json, model_schema - - load_simple_csv -2. In `docs/src/index.md`, replace "# Examples coming soon" with an actual brief example (copy from README.md Quick Start section, abbreviated). - -**Verification:** -```julia -cd("/var$REPOS_DIR/BowtieRisk.jl") -using Pkg; Pkg.activate("docs") -Pkg.develop(path=".") -Pkg.add("Documenter") -include("docs/make.jl") -# Expected: docs build succeeds without warnings about missing pages -``` - ---- - -## TASK 6: Fix test suite dead code and add missing template tests (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/test/runtests.jl` (lines 118, 157-167) - -**Problem:** -- Line 118: `@test hasproperty(sim, :top_event_std) || true` -- `SimulationResult` does NOT have a `top_event_std` field (line 141-145 of BowtieRisk.jl). `hasproperty` will return `false`, but `|| true` makes the test always pass. This is dead code that hides a missing feature. -- Lines 157-167: The loop tests templates `:cybersecurity` and `:operational`, but `template_model` only supports `:process_safety` and `:cyber_incident`. The `try/catch` silently swallows the errors with `@test true`. This masks the fact that the test is referencing wrong template names. - -**What to do:** -1. Line 118: Either implement `top_event_std` in `SimulationResult` (add standard deviation calculation in `simulate`) OR remove the dead test. Recommendation: add `top_event_std::Float64` to `SimulationResult` (line 141) and compute it in `simulate` (line 304). - - Add field: `top_event_std::Float64` to `SimulationResult` - - Compute: `top_std = sqrt(sum((v - top_mean)^2 for v in top_vals) / length(top_vals))` in `simulate` - - Update the constructor call at line 304 to include the std value - - Fix test line 118 to: `@test sim.top_event_std >= 0.0` -2. Lines 157-167: Fix template names to match actual implementations: - - Replace `:cybersecurity` with `:cyber_incident` - - Replace `:operational` with... there is no third template. Remove `:operational` from the loop or implement an `:operational` template in `template_model`. - - Remove the `try/catch` -- templates that exist should not throw. - -**Verification:** -```julia -cd("/var$REPOS_DIR/BowtieRisk.jl") -using Pkg; Pkg.test() -# Expected: all tests pass, no silently caught errors -``` - ---- - -## TASK 7: Customize ROADMAP.adoc from template boilerplate (LOW) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/ROADMAP.adoc` - -**Problem:** `ROADMAP.adoc` still contains the RSR template boilerplate ("YOUR Template Repo Roadmap", "Initial development phase", generic milestones). Meanwhile `ROADMAP.md` has real BowtieRisk.jl-specific content. Having two conflicting ROADMAP files is confusing. - -**What to do:** -1. Delete `ROADMAP.adoc` entirely. The `ROADMAP.md` already has comprehensive, project-specific roadmap content. -2. Alternatively, if both formats are needed: replace the content of `ROADMAP.adoc` with an AsciiDoc version of `ROADMAP.md` content and delete `ROADMAP.md`. Pick ONE format. - -**Verification:** -```bash -ls /var$REPOS_DIR/BowtieRisk.jl/ROADMAP* -# Expected: exactly one ROADMAP file (either .md or .adoc, not both) -``` - ---- - -## TASK 8: Customize CITATIONS.adoc for BowtieRisk.jl (LOW) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/docs/CITATIONS.adoc` - -**Problem:** Lines 8-15 still reference `rsr-template-repo` and `Polymath, Hyper` as author. This is the template boilerplate. - -**What to do:** -1. Replace `rsr-template-repo_2025` with `bowtierisk_jl_2025` (BibTeX key) -2. Replace `author = {Polymath, Hyper}` with `author = {Jewell, Jonathan D.A.}` -3. Replace `title = {RSR-template-repo}` with `title = {BowtieRisk.jl}` -4. Replace year `2025` with `2026` -5. Replace all `url` values from `https://github.com/hyperpolymath/RSR-template-repo` to `https://github.com/hyperpolymath/BowtieRisk.jl` -6. Update Harvard, OSCOLA, MLA, APA 7 sections similarly. - -**Verification:** -```bash -grep -c "RSR-template-repo\|Polymath, Hyper\|Polymath, H\.\|Hyper Polymath" /var$REPOS_DIR/BowtieRisk.jl/docs/CITATIONS.adoc -# Expected: 0 -``` - ---- - -## TASK 9: Customize README.adoc from template boilerplate (LOW) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/README.adoc` - -**Problem:** `README.adoc` still says "This is your repo - don't forget to rename me!" (line 3) and contains RSR template instructions about SafeDOM, ReScript, Idris2, etc. None of this is relevant to BowtieRisk.jl. Meanwhile `README.md` has the real project README. - -**What to do:** -1. Delete `README.adoc` entirely. `README.md` already exists with complete, correct content. -2. GitHub will display `README.md` by default. - -**Verification:** -```bash -test ! -f /var$REPOS_DIR/BowtieRisk.jl/README.adoc && test -f /var$REPOS_DIR/BowtieRisk.jl/README.md && echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 10: Add consequence-side sensitivity to sensitivity_tornado (LOW) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/src/BowtieRisk.jl` (lines 310-336) - -**Problem:** `sensitivity_tornado` only perturbs barriers on `model.threat_paths` (lines 314-331). It completely ignores barriers on `model.consequence_paths`. This means mitigative barriers are invisible to the sensitivity analysis, which defeats the purpose of a bowtie (which has barriers on both sides). - -**What to do:** -1. After the existing threat_paths loop (line 332), add a second loop over `model.consequence_paths`: - ```julia - for (pidx, path) in enumerate(model.consequence_paths) - for (bidx, barrier) in enumerate(path.barriers) - lower = clamp(barrier.effectiveness - delta, 0.0, 1.0) - upper = clamp(barrier.effectiveness + delta, 0.0, 1.0) - low_barrier = Barrier(barrier.name, lower, barrier.kind, barrier.description, barrier.degradation, barrier.dependency) - high_barrier = Barrier(barrier.name, upper, barrier.kind, barrier.description, barrier.degradation, barrier.dependency) - low_cons = deepcopy(model.consequence_paths) - high_cons = deepcopy(model.consequence_paths) - low_cons[pidx].barriers[bidx] = low_barrier - high_cons[pidx].barriers[bidx] = high_barrier - low_model = BowtieModel(model.hazard, model.top_event, model.threat_paths, low_cons, model.probability_model) - high_model = BowtieModel(model.hazard, model.top_event, model.threat_paths, high_cons, model.probability_model) - push!(results, (barrier.name, evaluate(low_model).top_event_probability, evaluate(high_model).top_event_probability)) - end - end - ``` -2. Note: The consequence-side barriers do NOT affect `top_event_probability` -- they affect `consequence_probabilities`. Consider whether the tornado should return consequence-level sensitivity instead. If so, change the pushed tuple to include consequence impact, or add a separate function `sensitivity_tornado_consequences`. -3. At minimum, add a test that verifies mitigative barriers appear in tornado output when there are consequence-path barriers. - -**Verification:** -```julia -using BowtieRisk -model = template_model(:process_safety) -tornado = sensitivity_tornado(model; delta=0.1) -barrier_names = [t[1] for t in tornado] -@assert :GasDetection in barrier_names "Mitigative barrier GasDetection should appear in tornado" -``` - ---- - -## TASK 11: Add missing `api.md` Documenter pages reference for BowtieSummary (LOW) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/src/BowtieRisk.jl` (lines 7-17 exports, line 244) - -**Problem:** `BowtieSummary` (line 244) is a return type from `evaluate()` but is NOT exported. Users calling `evaluate(model)` get back a `BowtieSummary` struct and must access `.top_event_probability`, `.threat_residuals`, `.consequence_probabilities`, `.consequence_risks` -- but they cannot reference the type by name without `BowtieRisk.BowtieSummary`. - -**What to do:** -1. Add `BowtieSummary` to the export list at line 8 or 9. -2. If you created `api.md` in Task 5, add a `@docs BowtieSummary` entry. - -**Verification:** -```julia -using BowtieRisk -summary = evaluate(template_model(:process_safety)) -@assert summary isa BowtieSummary "BowtieSummary should be exported and accessible" -``` - ---- - -## TASK 12: Model schema is too shallow -- add property definitions (LOW) - -**Files:** -- `/var$REPOS_DIR/BowtieRisk.jl/src/BowtieRisk.jl` (lines 432-446) - -**Problem:** `model_schema()` returns a JSON schema where every property is just `Dict("type" => "object")` or `Dict("type" => "array")`. This is not useful for validation -- it would accept any JSON object as a valid bowtie model. The schema should define nested properties for hazard, threat_paths, consequence_paths, etc. - -**What to do:** -1. Expand the schema to define nested properties. For example: - - `hazard` should have `properties: { name: { type: "string" }, description: { type: "string" } }` - - `threat_paths` items should have `threat`, `barriers`, `escalation_factors` - - `barriers` items should have `name`, `effectiveness`, `kind`, `description`, `degradation`, `dependency` -2. This should match what `write_model_json` actually produces (lines 566-614). -3. Add `"additionalProperties" => false` where appropriate. - -**Verification:** -```julia -using BowtieRisk, JSON3 -schema = model_schema() -# Check hazard has nested properties -@assert haskey(schema["properties"]["hazard"], "properties") "hazard schema should have nested properties" -@assert haskey(schema["properties"]["hazard"]["properties"], "name") "hazard should require name" -``` - ---- - -## FINAL VERIFICATION - -After completing all tasks, run: - -```bash -cd /var$REPOS_DIR/BowtieRisk.jl - -# 1. All tests pass -julia --project=. -e 'using Pkg; Pkg.test()' - -# 2. No template placeholders remain -grep -rn '{{' . --include="*.md" --include="*.adoc" --include="*.idr" --include="*.zig" --include="*.res" --include="*.json" --include="*.jl" | grep -v ".git/" | grep -v "SONNET-TASKS" - -# 3. No AGPL references remain -grep -rn "AGPL" . | grep -v ".git/" | grep -v "SONNET-TASKS" - -# 4. SCM files exist -ls -la .machine_readable/STATE.scm .machine_readable/META.scm .machine_readable/ECOSYSTEM.scm - -# 5. No duplicate README/ROADMAP -ls README* ROADMAP* - -# 6. Example runs -julia --project=. examples/basic_bowtie.jl - -# 7. BowtieSummary is exported -julia --project=. -e 'using BowtieRisk; s = evaluate(template_model(:process_safety)); @assert s isa BowtieSummary' - -# 8. Docs build (optional, requires Documenter.jl) -# julia --project=docs docs/make.jl -``` - -All 8 checks must pass. If any fail, trace back to the relevant task and fix. diff --git a/packages/BowtieRisk.jl/TOPOLOGY.md b/packages/BowtieRisk.jl/TOPOLOGY.adoc similarity index 89% rename from packages/BowtieRisk.jl/TOPOLOGY.md rename to packages/BowtieRisk.jl/TOPOLOGY.adoc index f93beb056..d61cbfab7 100644 --- a/packages/BowtieRisk.jl/TOPOLOGY.md +++ b/packages/BowtieRisk.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== BowtieRisk.jl — Project Topology -# BowtieRisk.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE MODEL @@ -72,26 +68,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~72% Production Phase (Stabilizing) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Core Structures ──────► Model Evaluation ──────► Monte Carlo Sim │ Export Formats ◀──────── Reporting ◀─────────────────┘ │ Sensitivity Analysis -``` +.... -## 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/packages/BowtieRisk.jl/docs/src/api.md b/packages/BowtieRisk.jl/docs/src/api.adoc similarity index 50% rename from packages/BowtieRisk.jl/docs/src/api.md rename to packages/BowtieRisk.jl/docs/src/api.adoc index 70f128982..c682c6703 100644 --- a/packages/BowtieRisk.jl/docs/src/api.md +++ b/packages/BowtieRisk.jl/docs/src/api.adoc @@ -1,82 +1,92 @@ -# API Reference +== API Reference -## Core Data Structures +=== Core Data Structures -```@docs +[source,@docs] +---- Hazard Threat TopEvent Consequence Barrier EscalationFactor -``` +---- -## Model Components +=== Model Components -```@docs +[source,@docs] +---- ProbabilityModel ThreatPath ConsequencePath BowtieModel -``` +---- -## Simulation +=== Simulation -```@docs +[source,@docs] +---- BarrierDistribution SimulationResult simulate -``` +---- -## Evaluation +=== Evaluation -```@docs +[source,@docs] +---- BowtieSummary evaluate sensitivity_tornado -``` +---- -## Event Chains +=== Event Chains -```@docs +[source,@docs] +---- Event EventChain chain_probability -``` +---- -## Visualization +=== Visualization -```@docs +[source,@docs] +---- to_mermaid to_graphviz -``` +---- -## Reports +=== Reports -```@docs +[source,@docs] +---- report_markdown write_report_markdown write_tornado_csv -``` +---- -## Serialization +=== Serialization -```@docs +[source,@docs] +---- write_model_json read_model_json write_schema_json model_schema -``` +---- -## Templates +=== Templates -```@docs +[source,@docs] +---- list_templates template_model -``` +---- -## Data Import +=== Data Import -```@docs +[source,@docs] +---- load_simple_csv -``` +---- diff --git a/packages/BowtieRisk.jl/docs/src/index.md b/packages/BowtieRisk.jl/docs/src/index.adoc similarity index 74% rename from packages/BowtieRisk.jl/docs/src/index.md rename to packages/BowtieRisk.jl/docs/src/index.adoc index 6287128e4..68bc275aa 100644 --- a/packages/BowtieRisk.jl/docs/src/index.md +++ b/packages/BowtieRisk.jl/docs/src/index.adoc @@ -1,17 +1,19 @@ -# BowtieRisk.jl +== BowtieRisk.jl Documentation for BowtieRisk.jl -## Installation +=== Installation -```julia +[source,julia] +---- using Pkg Pkg.add(url="https://github.com/hyperpolymath/BowtieRisk.jl") -``` +---- -## Quick Start +=== Quick Start -```julia +[source,julia] +---- using BowtieRisk # Use a template model @@ -32,10 +34,10 @@ println("Mean: ", sim.top_event_mean) # Export to Mermaid diagram diagram = to_mermaid(model) println(diagram) -``` +---- -See `examples/basic_bowtie.jl` for a comprehensive example. +See `+examples/basic_bowtie.jl+` for a comprehensive example. -## API Reference +=== API Reference -See [API](api.md) for complete reference. +See link:api.md[API] for complete reference. diff --git a/packages/Cladistics.jl/ABI-FFI-README.md b/packages/Causals.jl/ABI-FFI-README.adoc similarity index 74% rename from packages/Cladistics.jl/ABI-FFI-README.md rename to packages/Causals.jl/ABI-FFI-README.adoc index 08d35da64..8e5244189 100644 --- a/packages/Cladistics.jl/ABI-FFI-README.md +++ b/packages/Causals.jl/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/Causals.jl/CODE_OF_CONDUCT.adoc b/packages/Causals.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/Causals.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Causals.jl/CODE_OF_CONDUCT.md b/packages/Causals.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/Causals.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Causals.jl/CONTRIBUTING.adoc b/packages/Causals.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/Causals.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Causals.jl/CONTRIBUTING.md b/packages/Causals.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/Causals.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Causals.jl/ROADMAP.adoc b/packages/Causals.jl/ROADMAP.adoc new file mode 100644 index 000000000..90e99921b --- /dev/null +++ b/packages/Causals.jl/ROADMAP.adoc @@ -0,0 +1,163 @@ +== Causals.jl Development Roadmap + +=== Current State (v0.2 Alpha) + +In-development implementation of 7 causal inference modules: - +*DempsterShafer*: Evidence combination (mostly complete) - +*BradfordHill*: Causal criteria assessment (complete) - *CausalDAG*: +Directed acyclic graphs (d-separation, backdoor, frontdoor criteria +working) - *Granger*: Time series causality (complete with proper +F-distribution) - *PropensityScore*: Observational study methods +(propensity scores, matching, IPW, stratification, doubly robust all +working) - *DoCalculus*: Interventional queries (do-intervention, effect +identification, confounding adjustment, do-calculus rules implemented) - +*Counterfactuals*: "`What if`" reasoning (counterfactual function with +structural equations working) + +*Status:* Alpha release with 105 passing tests, working examples, +comprehensive documentation. All core algorithms implemented and +verified. + +''''' + +=== v1.0 → v1.2 Roadmap (Near-term) + +==== v1.1 - Performance & Usability (3-6 months) + +*MUST:* - [ ] *Performance benchmarking suite* - Baseline all 7 methods +against synthetic datasets (10³, 10⁴, 10⁵ elements) - [ ] *Memoization +for Dempster-Shafer* - Cache intermediate combination results to avoid +recomputation - [ ] *Sparse matrix support in Causal DAGs* - Use +SparseArrays.jl for large conditional probability tables - [ ] *Progress +indicators* - Add @showprogress for long-running computations (>1s +expected runtime) - [ ] *Input validation helpers* - +`+validate_mass_function()+`, `+validate_cpt()+` convenience functions + +*SHOULD:* - [ ] *Parallel belief propagation* - Use Threads.@threads for +independent message passing in large graphs - [ ] *JSON export/import* - +Serialize causal models to JSON for interoperability - [ ] +*Visualization integration* - GraphMakie.jl support for rendering +Bayesian networks - [ ] *Uncertainty quantification* - Add confidence +intervals to all inference outputs + +*COULD:* - [ ] *Interactive tutorial notebook* - Pluto.jl walkthrough of +all 7 methods with live examples - [ ] *Domain-specific presets* - +Medical diagnosis, fault detection, risk assessment templates - [ ] +*Model comparison metrics* - AIC/BIC for Bayesian networks, conflict +metrics for Dempster-Shafer + +==== v1.2 - Advanced Methods & Integration (6-12 months) + +*MUST:* - [ ] *Causal discovery algorithms* - PC algorithm, Fast Causal +Inference for structure learning - [ ] *Intervention modeling* - +do-calculus support for causal effect estimation - [ ] *Missing data +handling* - EM algorithm for incomplete observations in Bayesian +networks - [ ] *Model validation suite* - Cross-validation, holdout +testing, bootstrap confidence intervals + +*SHOULD:* - [ ] *Temporal causal models* - Dynamic Bayesian networks for +time-series causality - [ ] *Counterfactual reasoning* - Pearl’s +structural causal model framework - [ ] *Sensitivity analysis* - +Robustness testing for prior distributions and model parameters - [ ] +*Integration with BowtieRisk.jl* - Bidirectional causal pathway analysis + +*COULD:* - [ ] *GPU acceleration* - CUDA.jl support for matrix +operations in large networks - [ ] *Federated learning* - +Privacy-preserving causal inference across distributed datasets - [ ] +*AutoML for structure learning* - Hyperparameter tuning for causal +discovery algorithms + +''''' + +=== v1.3+ Roadmap (Speculative) + +==== Research Frontiers + +*Causal AI & Machine Learning:* - Neural causal models (integration with +Flux.jl/Lux.jl) - Causal representation learning (disentangled +representations) - Causal reinforcement learning (counterfactual policy +evaluation) - Large-scale causal inference (billions of variables, +distributed computing) + +*Quantum Causal Models:* - Quantum Bayesian networks - Causal +indefiniteness (no fixed causal order) - Quantum interventions and +counterfactuals + +*Formal Verification:* - Proof export to Coq/Lean (causal reasoning +proofs) - Certified causal inference (verified correctness guarantees) - +Integration with Axiom.jl for theorem proving + +*Domain Expansions:* - Genomic causality (gene regulatory networks, +GWAS) - Climate modeling (attribution of extreme events) - Economic +causality (policy impact analysis) - Social network dynamics (influence +propagation) + +==== Ecosystem Integration + +* *Turing.jl:* Probabilistic programming interface for Bayesian causal +models +* *DifferentialEquations.jl:* Continuous-time causal dynamics +* *Graphs.jl:* Advanced graph algorithms for causal structure +* *MLJ.jl:* Causal feature selection and causal prediction + +==== Ambitious Features + +* *Causal foundation models* - Pre-trained causal reasoning on knowledge +graphs +* *Natural language causal extraction* - Parse causal claims from text +* *Interactive causal sandbox* - Visual programming for causal modeling +(Makie.jl + web UI) +* *Causal explanation engine* - Generate human-readable justifications +for inferences + +''''' + +=== Future Horizons (v2.0+) + +==== Synthetic Twin Universes (STU) + +* [ ] *High-Fidelity Counterfactual Simulation*: Create +causal-consistent "`Alternative History`" simulators using `+Agents.jl+` +to test the long-term impact of policy interventions before deployment. +* [ ] *Stochastic Causal Worlds*: Support for branching causal realities +where probabilities themselves are subject to interventional shifts. + +==== Causal Ethics & Moral Attribution + +* [ ] *Moral Responsibility Scoring*: Integrate with `+Axiology.jl+` to +formally attribute "`Blame`" or "`Credit`" based on causal necessity and +sufficiency in multi-agent systems. +* [ ] *Equitable Causal Chains*: Verify that causal paths from protected +attributes to outcomes do not violate specific fairness invariants +(linking to `+Axiology.jl+` fairness metrics). + +==== Neuro-Symbolic Causal Discovery + +* [ ] *Visual Causal Discovery*: Use deep learning (Flux.jl/Lux.jl) to +extract symbolic causal DAGs directly from raw video or sensor streams. +* [ ] *Latent Causal Search*: Discover "`hidden`" causal variables in +high-dimensional latent spaces of Generative AI models. + +==== Causal Legal & Forensic Oracles + +* [ ] *Automated "`But-For`" Briefs*: Generate human-readable forensic +reports that meet legal standards for "`Causation in Fact`" and +"`Proximate Cause`". +* [ ] *Blockchain Causal Audits*: Store causal intervention logs on an +immutable ledger for verifiable post-incident forensic analysis. + +''''' + +=== Migration Path + +*v1.0 → v1.1:* Backward compatible (performance improvements only) *v1.1 +→ v1.2:* Mostly compatible (new features, minor API additions) *v1.2 → +v1.3+:* Breaking changes possible (research features may require API +redesign) + +=== Community Goals + +* *10 citations* in academic papers by v1.2 +* *100 GitHub stars* by v1.2 +* *JuliaCon talk* submission for v1.2 release +* *Collaboration* with causal inference research groups (MIT, UCL, CMU) diff --git a/packages/Causals.jl/ROADMAP.md b/packages/Causals.jl/ROADMAP.md deleted file mode 100644 index da6d3ed43..000000000 --- a/packages/Causals.jl/ROADMAP.md +++ /dev/null @@ -1,134 +0,0 @@ -# Causals.jl Development Roadmap - -## Current State (v0.2 Alpha) - -In-development implementation of 7 causal inference modules: -- **DempsterShafer**: Evidence combination (mostly complete) -- **BradfordHill**: Causal criteria assessment (complete) -- **CausalDAG**: Directed acyclic graphs (d-separation, backdoor, frontdoor criteria working) -- **Granger**: Time series causality (complete with proper F-distribution) -- **PropensityScore**: Observational study methods (propensity scores, matching, IPW, stratification, doubly robust all working) -- **DoCalculus**: Interventional queries (do-intervention, effect identification, confounding adjustment, do-calculus rules implemented) -- **Counterfactuals**: "What if" reasoning (counterfactual function with structural equations working) - -**Status:** Alpha release with 105 passing tests, working examples, comprehensive documentation. All core algorithms implemented and verified. - ---- - -## v1.0 → v1.2 Roadmap (Near-term) - -### v1.1 - Performance & Usability (3-6 months) - -**MUST:** -- [ ] **Performance benchmarking suite** - Baseline all 7 methods against synthetic datasets (10³, 10⁴, 10⁵ elements) -- [ ] **Memoization for Dempster-Shafer** - Cache intermediate combination results to avoid recomputation -- [ ] **Sparse matrix support in Causal DAGs** - Use SparseArrays.jl for large conditional probability tables -- [ ] **Progress indicators** - Add @showprogress for long-running computations (>1s expected runtime) -- [ ] **Input validation helpers** - `validate_mass_function()`, `validate_cpt()` convenience functions - -**SHOULD:** -- [ ] **Parallel belief propagation** - Use Threads.@threads for independent message passing in large graphs -- [ ] **JSON export/import** - Serialize causal models to JSON for interoperability -- [ ] **Visualization integration** - GraphMakie.jl support for rendering Bayesian networks -- [ ] **Uncertainty quantification** - Add confidence intervals to all inference outputs - -**COULD:** -- [ ] **Interactive tutorial notebook** - Pluto.jl walkthrough of all 7 methods with live examples -- [ ] **Domain-specific presets** - Medical diagnosis, fault detection, risk assessment templates -- [ ] **Model comparison metrics** - AIC/BIC for Bayesian networks, conflict metrics for Dempster-Shafer - -### v1.2 - Advanced Methods & Integration (6-12 months) - -**MUST:** -- [ ] **Causal discovery algorithms** - PC algorithm, Fast Causal Inference for structure learning -- [ ] **Intervention modeling** - do-calculus support for causal effect estimation -- [ ] **Missing data handling** - EM algorithm for incomplete observations in Bayesian networks -- [ ] **Model validation suite** - Cross-validation, holdout testing, bootstrap confidence intervals - -**SHOULD:** -- [ ] **Temporal causal models** - Dynamic Bayesian networks for time-series causality -- [ ] **Counterfactual reasoning** - Pearl's structural causal model framework -- [ ] **Sensitivity analysis** - Robustness testing for prior distributions and model parameters -- [ ] **Integration with BowtieRisk.jl** - Bidirectional causal pathway analysis - -**COULD:** -- [ ] **GPU acceleration** - CUDA.jl support for matrix operations in large networks -- [ ] **Federated learning** - Privacy-preserving causal inference across distributed datasets -- [ ] **AutoML for structure learning** - Hyperparameter tuning for causal discovery algorithms - ---- - -## v1.3+ Roadmap (Speculative) - -### Research Frontiers - -**Causal AI & Machine Learning:** -- Neural causal models (integration with Flux.jl/Lux.jl) -- Causal representation learning (disentangled representations) -- Causal reinforcement learning (counterfactual policy evaluation) -- Large-scale causal inference (billions of variables, distributed computing) - -**Quantum Causal Models:** -- Quantum Bayesian networks -- Causal indefiniteness (no fixed causal order) -- Quantum interventions and counterfactuals - -**Formal Verification:** -- Proof export to Coq/Lean (causal reasoning proofs) -- Certified causal inference (verified correctness guarantees) -- Integration with Axiom.jl for theorem proving - -**Domain Expansions:** -- Genomic causality (gene regulatory networks, GWAS) -- Climate modeling (attribution of extreme events) -- Economic causality (policy impact analysis) -- Social network dynamics (influence propagation) - -### Ecosystem Integration - -- **Turing.jl:** Probabilistic programming interface for Bayesian causal models -- **DifferentialEquations.jl:** Continuous-time causal dynamics -- **Graphs.jl:** Advanced graph algorithms for causal structure -- **MLJ.jl:** Causal feature selection and causal prediction - -### Ambitious Features - -- **Causal foundation models** - Pre-trained causal reasoning on knowledge graphs -- **Natural language causal extraction** - Parse causal claims from text -- **Interactive causal sandbox** - Visual programming for causal modeling (Makie.jl + web UI) -- **Causal explanation engine** - Generate human-readable justifications for inferences - ---- - -## Future Horizons (v2.0+) - -### Synthetic Twin Universes (STU) -- [ ] **High-Fidelity Counterfactual Simulation**: Create causal-consistent "Alternative History" simulators using `Agents.jl` to test the long-term impact of policy interventions before deployment. -- [ ] **Stochastic Causal Worlds**: Support for branching causal realities where probabilities themselves are subject to interventional shifts. - -### Causal Ethics & Moral Attribution -- [ ] **Moral Responsibility Scoring**: Integrate with `Axiology.jl` to formally attribute "Blame" or "Credit" based on causal necessity and sufficiency in multi-agent systems. -- [ ] **Equitable Causal Chains**: Verify that causal paths from protected attributes to outcomes do not violate specific fairness invariants (linking to `Axiology.jl` fairness metrics). - -### Neuro-Symbolic Causal Discovery -- [ ] **Visual Causal Discovery**: Use deep learning (Flux.jl/Lux.jl) to extract symbolic causal DAGs directly from raw video or sensor streams. -- [ ] **Latent Causal Search**: Discover "hidden" causal variables in high-dimensional latent spaces of Generative AI models. - -### Causal Legal & Forensic Oracles -- [ ] **Automated "But-For" Briefs**: Generate human-readable forensic reports that meet legal standards for "Causation in Fact" and "Proximate Cause". -- [ ] **Blockchain Causal Audits**: Store causal intervention logs on an immutable ledger for verifiable post-incident forensic analysis. - ---- - -## Migration Path - -**v1.0 → v1.1:** Backward compatible (performance improvements only) -**v1.1 → v1.2:** Mostly compatible (new features, minor API additions) -**v1.2 → v1.3+:** Breaking changes possible (research features may require API redesign) - -## Community Goals - -- **10 citations** in academic papers by v1.2 -- **100 GitHub stars** by v1.2 -- **JuliaCon talk** submission for v1.2 release -- **Collaboration** with causal inference research groups (MIT, UCL, CMU) diff --git a/packages/Causals.jl/SECURITY.adoc b/packages/Causals.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/Causals.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Causals.jl/SECURITY.md b/packages/Causals.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/Causals.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Causals.jl/SONNET-TASKS.adoc b/packages/Causals.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..2f1677aad --- /dev/null +++ b/packages/Causals.jl/SONNET-TASKS.adoc @@ -0,0 +1,1058 @@ +== SONNET-TASKS.md — Causals.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 42% +____ + +The README claims "`production-ready`" and "`complete with comprehensive +test coverage.`" The ROADMAP.md claims v1.0 is done with "`7 causal +inference methods`" (some of which do not even exist in the codebase – +Bayesian Networks, Fuzzy Logic, Evidential Reasoning, Belief +Propagation, Conditional Probability, Probabilistic Logic are listed in +the ROADMAP but not implemented). The Project.toml says version +`+1.0.0+`. In reality: + +* 5 out of 7 source modules contain placeholder/stub code +* `+d_separation+` always returns `+true+` (hardcoded) +* `+frontdoor_criterion+` always returns `+true+` (hardcoded) +* `+confounding_adjustment+` always returns `+0.0+` (hardcoded) +* `+do_calculus_rules+` returns its input unchanged (no-op) +* `+counterfactual+` returns `+nothing+` (completely unimplemented) +* `+propensity_score+` ignores covariates entirely (returns constant) +* `+doubly_robust+` just calls IPW (defeats the purpose) +* `+granger_test+` uses a hardcoded critical F-value instead of the +Distributions.jl F-distribution that is already a dependency +* Both example files have severe API mismatches and will not run +* No tests exist for DoCalculus, Counterfactuals, matching, +stratification, or doubly_robust +* 6 of 7 docs pages referenced in `+docs/make.jl+` do not exist +* The ABI/FFI Idris2/Zig files are unmodified templates with +`+{{PROJECT}}+` placeholders +* The `+examples/+` directory contains two unrelated non-Julia files +(SafeDOMExample.res, web-project-deno.json) that should not be there + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update STATE.scm with honest completion percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/Causals.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix d_separation to use proper Bayes-Ball algorithm (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/CausalDAG.jl+` + +*Problem:* The `+d_separation+` function at lines 60-70 is a complete +stub. It always returns `+true+` regardless of input. The comment at +line 62 says "`Simplified implementation`" and line 69 says +`+true # Placeholder+`. This makes all downstream +d-separation-dependent code (backdoor criterion, frontdoor criterion, +do-calculus identification) unreliable. + +*What to do:* + +[arabic] +. Replace the body of `+d_separation+` (lines 60-70) with a proper +implementation using the Bayes-Ball algorithm (Shachter 1998) or the +reachability-based algorithm: +* Build the "`ancestral graph`" of X, Y, and Z +* Moralize the ancestral graph (add edges between parents of common +children) +* Remove edges involving Z nodes +* Check if X and Y are still connected in the resulting undirected graph +. The function signature stays the same: +`+d_separation(g::CausalGraph, X::Set{Symbol}, Y::Set{Symbol}, Z::Set{Symbol}) -> Bool+` +. Return `+true+` if X and Y are d-separated given Z, `+false+` +otherwise. +. Handle edge cases: empty Z set, X or Y being singletons, X == Y +(should return true trivially). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Causals.CausalDAG: add_edge! + +# Chain: X -> M -> Y -- X _|_ Y | M should be true +g1 = CausalGraph([:X, :M, :Y]) +add_edge!(g1, :X, :M) +add_edge!(g1, :M, :Y) +@assert d_separation(g1, Set([:X]), Set([:Y]), Set([:M])) == true "Chain: X _|_ Y | M" +@assert d_separation(g1, Set([:X]), Set([:Y]), Set{Symbol}()) == false "Chain: X NOT _|_ Y | {}" + +# Fork: X <- C -> Y -- X _|_ Y | C should be true +g2 = CausalGraph([:X, :C, :Y]) +add_edge!(g2, :C, :X) +add_edge!(g2, :C, :Y) +@assert d_separation(g2, Set([:X]), Set([:Y]), Set([:C])) == true "Fork: X _|_ Y | C" +@assert d_separation(g2, Set([:X]), Set([:Y]), Set{Symbol}()) == false "Fork: X NOT _|_ Y | {}" + +# Collider: X -> M <- Y -- X _|_ Y | {} should be true, X NOT _|_ Y | M +g3 = CausalGraph([:X, :M, :Y]) +add_edge!(g3, :X, :M) +add_edge!(g3, :Y, :M) +@assert d_separation(g3, Set([:X]), Set([:Y]), Set{Symbol}()) == true "Collider: X _|_ Y | {}" +@assert d_separation(g3, Set([:X]), Set([:Y]), Set([:M])) == false "Collider: X NOT _|_ Y | M" + +println("TASK 1 PASSED: d_separation works correctly") +---- + +''''' + +=== TASK 2: Fix frontdoor_criterion stub (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/CausalDAG.jl+` + +*Problem:* The `+frontdoor_criterion+` function at lines 188-194 always +returns `+true+`. The body is `+true+` with a comment saying +"`Simplified implementation`". The three conditions listed in the +docstring (lines 184-186) are never checked. + +*What to do:* + +[arabic] +. Replace the body of `+frontdoor_criterion+` (lines 188-194) with a +proper implementation that checks all three conditions: +* Condition 1: M intercepts all directed paths from X to Y (every +directed path from X to Y passes through some node in M) +* Condition 2: There are no unblocked backdoor paths from X to any node +in M (i.e., no unconfounded relationship X->M) +* Condition 3: All backdoor paths from M to Y are blocked by X +. For condition 1, enumerate directed paths from X to Y (DFS on the +directed graph) and verify each passes through at least one node in M. +. For condition 2, check `+backdoor_criterion(g, X, m, Set{Symbol}())+` +or equivalent for each m in M (after removing X from the graph +conceptually). +. For condition 3, check d-separation conditions with X as the +conditioning set. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Causals.CausalDAG: add_edge! + +# Classic frontdoor: X -> M -> Y, U -> X, U -> Y (U unobserved but in graph) +g = CausalGraph([:X, :M, :Y, :U]) +add_edge!(g, :X, :M) +add_edge!(g, :M, :Y) +add_edge!(g, :U, :X) +add_edge!(g, :U, :Y) +@assert frontdoor_criterion(g, :X, :Y, Set([:M])) == true "Frontdoor should hold for M" + +# Invalid frontdoor: M does not intercept all paths (direct X->Y edge exists) +g2 = CausalGraph([:X, :M, :Y, :U]) +add_edge!(g2, :X, :M) +add_edge!(g2, :M, :Y) +add_edge!(g2, :X, :Y) # Direct path bypasses M +add_edge!(g2, :U, :X) +add_edge!(g2, :U, :Y) +@assert frontdoor_criterion(g2, :X, :Y, Set([:M])) == false "Frontdoor should fail: direct X->Y bypasses M" + +println("TASK 2 PASSED: frontdoor_criterion works correctly") +---- + +''''' + +=== TASK 3: Implement proper p-value computation in granger_test using Distributions.jl (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/Granger.jl+` + +*Problem:* Lines 49-50 compute the p-value using a hardcoded critical +value `+critical_F = 3.0+` and return fake p-values (`+0.01+` or +`+0.1+`). The package already depends on `+Distributions.jl+` (listed in +Project.toml line 11) but it is not used in this module. + +*What to do:* + +[arabic] +. Add `+using Distributions+` at the top of the Granger module (after +line 11). +. Replace lines 49-52 with proper F-distribution computation: ++ +[source,julia] +---- +df1 = k # numerator degrees of freedom +df2 = n_obs - 2 * best_lag - 1 # denominator degrees of freedom +f_dist = FDist(df1, df2) +p_value = 1.0 - cdf(f_dist, F_stat) +causes = p_value < α +---- +. Remove the `+critical_F+` variable entirely. +. Ensure the `+α+` keyword argument is actually used (currently it is +accepted but ignored because the hardcoded critical value is used +instead). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals + +# Known causal relationship +n = 200 +x = randn(n) +y = zeros(n) +for t in 2:n + y[t] = 0.5 * y[t-1] + 0.8 * x[t-1] + 0.05 * randn() +end + +causes, F_stat, p_value, lag = granger_test(x, y, 5) +@assert p_value >= 0.0 && p_value <= 1.0 "p-value must be in [0,1], got $p_value" +@assert p_value < 0.05 "Strong causal signal should have p < 0.05, got $p_value" +@assert causes == true "Should detect Granger causality" + +# Independent series should not show causality +x_indep = randn(200) +y_indep = randn(200) +causes_indep, _, p_indep, _ = granger_test(x_indep, y_indep, 5) +@assert p_indep > 0.0 "Independent series p-value should not be zero" + +println("TASK 3 PASSED: granger_test uses proper F-distribution p-values") +---- + +''''' + +=== TASK 4: Implement real propensity_score using logistic regression (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/PropensityScore.jl+` + +*Problem:* The `+propensity_score+` function at lines 22-31 completely +ignores the `+covariates+` argument. It computes +`+p = sum(treatment) / n+` (the marginal treatment probability) and +returns `+fill(p, n)+` – a vector of identical values. This makes all +downstream methods (matching, IPW, stratification) meaningless because +every unit gets the same propensity score. + +*What to do:* + +[arabic] +. Implement logistic regression using iteratively reweighted least +squares (IRLS): +* Initialize coefficients beta to zeros +* Iterate: compute predictions p = logistic(X__beta), weights W = +diag(p.__(1-p)), update beta = beta + inv(X’__W__X) * X’ * (treatment - +p) +* Converge when max change in beta < 1e-8 or after 25 iterations +. Add an intercept column to covariates internally: +`+X = hcat(ones(n), covariates)+` +. Clip propensity scores to [0.01, 0.99] to avoid division by zero in +IPW. +. Return the fitted propensity scores. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Random; Random.seed!(42) + +n = 200 +x1 = randn(n) +x2 = randn(n) +# Treatment depends on covariates +logit = 0.5 .* x1 .+ 0.3 .* x2 .- 0.2 +p_true = 1.0 ./ (1.0 .+ exp.(-logit)) +treatment = rand(n) .< p_true + +ps = propensity_score(treatment, hcat(x1, x2)) +@assert length(ps) == n +@assert !all(ps .== ps[1]) "Propensity scores must vary across observations, not be constant" +@assert all(0.0 .<= ps .<= 1.0) "All scores must be in [0,1]" +@assert cor(ps, p_true) > 0.5 "Estimated scores should correlate with true propensity" + +println("TASK 4 PASSED: propensity_score uses actual logistic regression") +---- + +''''' + +=== TASK 5: Implement confounding_adjustment (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/DoCalculus.jl+` + +*Problem:* The `+confounding_adjustment+` function at lines 90-103 +always returns `+0.0+` (line 102 says `+0.0 # Placeholder+`). The +function is supposed to compute the backdoor-adjusted causal effect +E[Y|do(X=1)] - E[Y|do(X=0)] using stratification over confounders. + +*What to do:* + +[arabic] +. Replace the body of `+confounding_adjustment+` (lines 90-103) with a +real implementation: +* The `+data+` dictionary maps variable names to Float64 vectors. +* Binarize or stratify by the confounder values (use quantile-based +binning for continuous confounders). +* For each stratum z of confounders: compute E[Y|X=1,Z=z] and +E[Y|X=0,Z=z], weighted by P(Z=z). +* Return the weighted sum: sum_z (E[Y|X=1,Z=z] - E[Y|X=0,Z=z]) * P(Z=z). +. Handle cases where a stratum has no treated or no control units (skip +that stratum). +. Handle single vs multiple confounders by creating combined strata. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Random; Random.seed!(42) + +n = 500 +z = randn(n) +x = (z .+ randn(n)) .> 0 # Treatment depends on confounder +x_float = Float64.(x) +y = 2.0 .* x_float .+ 1.5 .* z .+ randn(n) # True causal effect of X is 2.0 + +data = Dict( + :X => x_float, + :Y => y, + :Z => z +) + +effect = confounding_adjustment(:X, :Y, Set([:Z]), data) +@assert abs(effect) > 0.0 "Effect must not be zero placeholder" +@assert abs(effect - 2.0) < 1.0 "Adjusted effect should be near 2.0, got $effect" + +println("TASK 5 PASSED: confounding_adjustment computes real adjusted effects") +---- + +''''' + +=== TASK 6: Implement do_calculus_rules (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/DoCalculus.jl+` + +*Problem:* The `+do_calculus_rules+` function at lines 78-82 is a no-op +that returns its input query unchanged. The docstring describes Pearl’s +three rules of do-calculus but none are implemented. + +*What to do:* + +[arabic] +. Define a proper query representation type. At minimum, a tagged union +or struct that can represent: +* `+P(Y | do(X), Z)+` – conditional with intervention +* `+P(Y | X, Z)+` – standard conditional +. Implement Rule 1 (insertion/deletion of observations): P(Y | do(X), Z, +W) = P(Y | do(X), Z) if Y _|_ W | X, Z in G_overbar_X +. Implement Rule 2 (action/observation exchange): P(Y | do(X), do(Z), W) += P(Y | do(X), Z, W) if Y _|_ Z | X, W in G_overbar_X_underbar_Z +. Implement Rule 3 (insertion/deletion of actions): P(Y | do(X), do(Z), +W) = P(Y | do(X), W) if Y _|_ Z | X, W in G_overbar_X_overbar_Z(W) +. If full implementation is too complex, implement at least Rules 1 and +2 with proper graph manipulation and d-separation checks (which will +work after Task 1). +. Update the function signature to accept a `+CausalGraph+` and return a +simplified query or `+:cannot_simplify+`. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Causals.CausalDAG: add_edge! +using Causals.DoCalculus + +# Build a simple graph +g = CausalGraph([:X, :Y, :Z]) +add_edge!(g, :X, :Y) +add_edge!(g, :Z, :X) +add_edge!(g, :Z, :Y) + +# At minimum, the function should not be a no-op +result = do_calculus_rules(g, (:Y, :do_X)) +@assert result !== (:Y, :do_X) || typeof(result) != typeof((:Y, :do_X)) "do_calculus_rules must not be a no-op" + +println("TASK 6 PASSED: do_calculus_rules implements at least basic simplification") +---- + +''''' + +=== TASK 7: Implement counterfactual function with structural equations (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/Counterfactuals.jl+` + +*Problem:* The `+counterfactual+` function at lines 37-54 returns +`+nothing+` (line 53). The three-step process described in the docstring +(Abduction, Action, Prediction) is outlined in comments but not +implemented. `+U+` is an empty Dict (line 45) and the function +terminates with `+nothing+`. + +*What to do:* + +[arabic] +. Extend the `+counterfactual+` function to accept structural equations. +Add an optional `+equations+` parameter of type +`+Dict{Symbol, Function}+` where each function takes a Dict of parent +values and noise and returns the variable’s value. +. Implement the three-step process: +* *Abduction*: Given observations and structural equations, infer noise +terms U by solving the equations backwards. +* *Action*: Apply the intervention (set X=x, remove incoming edges to X +in the graph). +* *Prediction*: Evaluate structural equations forward in topological +order using the inferred U values and the intervention. +. Return the counterfactual value of the outcome variable as a +`+Dict{Symbol, Any}+` mapping variable names to their counterfactual +values. +. If no equations are provided, return `+nothing+` with a warning +(preserve backward compatibility). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Causals.CausalDAG: add_edge! +using Causals.Counterfactuals + +# Simple SCM: X -> Y, Y = 2*X + noise +g = CausalGraph([:X, :Y]) +add_edge!(g, :X, :Y) + +# Structural equations: Y = 2X + U_Y +equations = Dict( + :X => (parents, noise) -> get(noise, :U_X, 0.0), + :Y => (parents, noise) -> 2.0 * parents[:X] + get(noise, :U_Y, 0.0) +) + +# Observed: X=3, Y=6.5 (so U_Y = 0.5) +observations = Dict(:X => 3.0, :Y => 6.5) + +result = counterfactual(g, :Y, :X => 5.0, observations; equations=equations) +@assert result !== nothing "counterfactual must not return nothing" +# Counterfactual Y when X=5: 2*5 + 0.5 = 10.5 +@assert abs(result - 10.5) < 0.01 "Counterfactual Y should be 10.5, got $result" + +println("TASK 7 PASSED: counterfactual computes actual counterfactual values") +---- + +''''' + +=== TASK 8: Implement doubly_robust estimator properly (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/PropensityScore.jl+` + +*Problem:* The `+doubly_robust+` function at lines 145-155 just calls +`+inverse_probability_weighting+` and returns its result. The comment on +line 151 says "`Simplified implementation`". This defeats the entire +purpose of the doubly robust estimator, which should be consistent if +EITHER the propensity model OR the outcome model is correct. + +*What to do:* + +[arabic] +. Replace the body of `+doubly_robust+` (lines 145-155) with the proper +Augmented IPW (AIPW) formula: ++ +.... +ATE = (1/n) * sum_i [ + (treatment_i * outcome_i / propensity_i) - ((treatment_i - propensity_i) / propensity_i) * outcome_model_1(x_i) + - ((1-treatment_i) * outcome_i / (1-propensity_i)) + ((treatment_i - propensity_i) / (1-propensity_i)) * outcome_model_0(x_i) +] +.... +. The `+outcome_model+` parameter should accept predicted outcomes for +both treated and control groups. Update the function signature if +needed: accept `+outcome_model_1+` and `+outcome_model_0+` vectors +(predicted outcomes under treatment and control), or a single function +that takes covariates and treatment indicator. +. Compute proper standard errors using the influence function. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Random; Random.seed!(42) + +n = 200 +treatment = rand(Bool, n) +outcome = Float64.(treatment) .* 2.0 .+ randn(n) +propensity = fill(0.5, n) + +# Simple outcome model: predict mean outcome per group +mean_treated = mean(outcome[treatment]) +mean_control = mean(outcome[.!treatment]) +outcome_model = (x) -> treatment .* mean_treated .+ (1 .- treatment) .* mean_control + +dr_ate = doubly_robust(treatment, outcome, propensity, outcome_model) +@assert !isnan(dr_ate) "DR estimate must not be NaN" +@assert abs(dr_ate - 2.0) < 1.5 "DR estimate should be near true effect 2.0, got $dr_ate" + +# Verify it gives different result than plain IPW +ipw_ate, _ = inverse_probability_weighting(treatment, outcome, propensity) +# They may be similar but should not be identical in general +println("DR ATE: $dr_ate, IPW ATE: $ipw_ate") + +println("TASK 8 PASSED: doubly_robust uses proper AIPW estimator") +---- + +''''' + +=== TASK 9: Fix identify_effect to try frontdoor criterion (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Causals.jl/src/DoCalculus.jl+` + +*Problem:* The `+identify_effect+` function at lines 41-51 only tries +the backdoor criterion and immediately gives up if it fails (line 49-50: +"`Simplified: return false if backdoor fails`"). The comment at lines +47-49 says it should try frontdoor but does not. + +*What to do:* + +[arabic] +. After the backdoor check fails, enumerate possible mediator sets M +(subsets of non-treatment, non-outcome nodes). +. For each candidate set M, call `+frontdoor_criterion(g, X, Y, M)+`. +. If any M satisfies the frontdoor criterion, return +`+(true, :frontdoor, M)+`. +. Only return `+(false, :unidentifiable, Set{Symbol}())+` if BOTH +backdoor and frontdoor criteria fail for all candidate +adjustment/mediator sets. +. For the backdoor case with empty Z: also try non-empty subsets of +valid adjustment sets (non-descendants of X). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +using Causals +using Causals.CausalDAG: add_edge! +using Causals.DoCalculus + +# Frontdoor-identifiable graph: X -> M -> Y, U -> X, U -> Y +g = CausalGraph([:X, :M, :Y, :U]) +add_edge!(g, :X, :M) +add_edge!(g, :M, :Y) +add_edge!(g, :U, :X) +add_edge!(g, :U, :Y) + +identifiable, method, set = identify_effect(g, :X, :Y) +@assert identifiable == true "Effect should be identifiable via frontdoor" +@assert method == :frontdoor "Should identify via frontdoor, got $method" +@assert :M in set "Mediator set should contain M" + +# Also test backdoor still works +g2 = CausalGraph([:X, :Y, :Z]) +add_edge!(g2, :X, :Y) +add_edge!(g2, :Z, :X) +add_edge!(g2, :Z, :Y) + +identifiable2, method2, set2 = identify_effect(g2, :X, :Y, Set([:Z])) +@assert identifiable2 == true "Effect should be identifiable via backdoor" +@assert method2 == :backdoor "Should identify via backdoor" + +println("TASK 9 PASSED: identify_effect tries frontdoor criterion") +---- + +''''' + +=== TASK 10: Fix example 01_basic_usage.jl API mismatches (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/examples/01_basic_usage.jl+` + +*Problem:* The example will not run because it uses APIs that do not +match the actual source code. Specific mismatches: + +* Line 30-31: `+MassAssignment(Dict(...))+` – constructor requires TWO +args: `+MassAssignment(frame, masses_dict)+`, not just a dict. +* Line 36-38: Same issue for `+evidence2+`. +* Line 51: `+pignistic_transform(combined, frame)+` – function only +takes 1 argument: `+pignistic_transform(m::MassAssignment)+`. +* Line 75-79: `+assess_causality(assessment)+` returns a tuple +`+(verdict, confidence)+`, not a scalar. The code assigns it to +`+causality_score+` and calls it as if it is a number, then also calls +`+strength_of_evidence+` separately. +* Line 91: `+CausalGraph(DiGraph(4))+` – constructor takes +`+Vector{Symbol}+`, not a `+DiGraph+`. Should be +`+CausalGraph([:Education, :Income, :Health, :Exercise])+`. +* Lines 94-97: `+CausalDAG.add_edge!(cg, 1, 2)+` – uses integer indices, +but `+add_edge!+` takes `+Symbol+` arguments. +* Line 105: `+d_separation(cg, [1], [4], [2])+` – takes `+Set{Symbol}+`, +not `+Vector{Int}+`. +* Lines 112-113: `+ancestors(cg, 3)+` and `+descendants(cg, 1)+` – take +`+Symbol+`, not `+Int+`. +* Line 117: `+backdoor_criterion(cg, 2, 3, [1])+` – takes +`+Symbol, Symbol, Set{Symbol}+`, not integers and vector. + +*What to do:* + +[arabic] +. Fix all constructor calls to use `+MassAssignment(frame, masses)+` +(two arguments). +. Fix `+pignistic_transform+` call to pass only one argument. +. Fix `+assess_causality+` return value handling (it returns a tuple). +. Replace `+CausalGraph(DiGraph(4))+` with +`+CausalGraph([:Education, :Income, :Health, :Exercise])+`. +. Replace all integer-based API calls with Symbol-based calls. +. Replace `+d_separation(cg, [1], [4], [2])+` with +`+d_separation(cg, Set([:Education]), Set([:Exercise]), Set([:Income]))+`. +. Fix `+ancestors+`/`+descendants+` calls to use Symbols. +. Fix `+backdoor_criterion+` call to use Symbols and Set. +. Remove `+using Graphs+` import (no longer needed after fixing +CausalGraph constructor). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +include("/var$REPOS_DIR/Causals.jl/examples/01_basic_usage.jl") +println("TASK 10 PASSED: example 01 runs without errors") +---- + +''''' + +=== TASK 11: Fix example 02_advanced_analysis.jl API mismatches (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/examples/02_advanced_analysis.jl+` + +*Problem:* The example will not run because it uses APIs that do not +match the actual source code. Specific mismatches: + +* Line 47: `+granger_test(x, y; max_lag=5)+` uses keyword arg syntax. +The actual function has `+max_lag+` as a positional argument: +`+granger_test(x, y, 5)+`. +* Lines 48-50: `+result.f_stat+`, `+result.p_value+`, `+result.causes+` +– `+granger_test+` returns a tuple +`+(causes, F_stat, p_value, best_lag)+`, not a named struct. +* Line 54: `+optimal_lag(x, y; max_lag=8)+` uses keyword arg. Actual +signature: `+optimal_lag(x, y, 8)+`. +* Line 88: `+matching(treatment, propensity_scores)+` – missing +`+outcome+` argument. Actual signature: +`+matching(treatment, outcome, propensity; method=:nearest, caliper=0.1)+`, +returns `+(matches, ate, se)+`. +* Lines 93-94: Tries to index matches as `+pair[1]+`, `+pair[2]+` – but +matches are `+Tuple{Int,Int}+` which is indexed this way, so this may +work if matching returns pairs. +* Line 108: `+CausalGraph(DiGraph(3))+` – should be +`+CausalGraph([:Z, :X, :Y])+` with Symbols. +* Lines 109-111: `+CausalDAG.add_edge!(confounded_graph, 1, 2)+` – uses +integers, should use Symbols. +* Line 117: `+identify_effect(confounded_graph, 2, 3)+` – uses integers, +should use Symbols. +* Line 123: `+confounding_adjustment(confounded_graph, 2, 3)+` – +completely wrong signature. The actual function takes +`+(treatment::Symbol, outcome::Symbol, confounders::Set{Symbol}, data::Dict{...})+`, +not a graph with integers. +* Lines 135-158: The counterfactual section uses +`+counterfactual(structural_equations, observed_values, Dict(:X => 5.0))+` +– completely wrong API. Actual signature: +`+counterfactual(g::CausalGraph, outcome::Symbol, intervention::Pair{Symbol, Any}, observations::Dict{Symbol, Any})+`. + +*What to do:* + +[arabic] +. Fix `+granger_test+` call to use positional `+max_lag+` and +destructure the tuple return. +. Fix `+optimal_lag+` call to use positional argument. +. Fix `+matching+` call to include all required arguments: +`+matching(treatment, observed_outcomes, propensity_scores)+`. +. Fix `+CausalGraph+` constructor to use Symbols. +. Fix all `+add_edge!+` calls to use Symbols. +. Fix `+identify_effect+` call to use Symbols. +. Fix `+confounding_adjustment+` call to use the correct signature. +. Fix the counterfactual section to use the actual API. +. Remove `+using Graphs+` import (no longer needed). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +include("/var$REPOS_DIR/Causals.jl/examples/02_advanced_analysis.jl") +println("TASK 11 PASSED: example 02 runs without errors") +---- + +''''' + +=== TASK 12: Remove non-Julia junk files from examples/ (LOW) + +*Files:* `+/var$REPOS_DIR/Causals.jl/examples/SafeDOMExample.res+`, +`+/var$REPOS_DIR/Causals.jl/examples/web-project-deno.json+` + +*Problem:* The `+examples/+` directory contains two files that have +nothing to do with Causals.jl: - `+SafeDOMExample.res+` – a ReScript DOM +mounting example (from a different project entirely) - +`+web-project-deno.json+` – a Deno project config for ReScript web +projects + +These are RSR template leftovers that were never cleaned up. + +*What to do:* + +[arabic] +. Delete `+/var$REPOS_DIR/Causals.jl/examples/SafeDOMExample.res+` +. Delete `+/var$REPOS_DIR/Causals.jl/examples/web-project-deno.json+` +. Verify only `+01_basic_usage.jl+` and `+02_advanced_analysis.jl+` +remain in `+examples/+`. + +*Verification:* + +[source,julia] +---- +files = readdir("/var$REPOS_DIR/Causals.jl/examples/") +@assert files == ["01_basic_usage.jl", "02_advanced_analysis.jl"] "examples/ should only contain Julia files, got $files" +println("TASK 12 PASSED: examples directory is clean") +---- + +''''' + +=== TASK 13: Add missing tests for DoCalculus, Counterfactuals, matching, stratification, doubly_robust (HIGH) + +*Files:* `+/var$REPOS_DIR/Causals.jl/test/runtests.jl+` + +*Problem:* The test file has no test sections for: - DoCalculus (no +`+@testset "DoCalculus"+` at all) - Counterfactuals (no +`+@testset "Counterfactuals"+` at all) - `+matching+` (the function is +not tested despite being exported) - `+stratification+` (not tested) - +`+doubly_robust+` (not tested) - `+d_separation+` (not tested despite +being a critical function) - `+frontdoor_criterion+` (not tested) - +`+markov_blanket+` (not tested) + +*What to do:* + +[arabic] +. Add a `+@testset "D-Separation"+` block with tests for chains, forks, +and colliders (similar to Task 1 verification). +. Add a `+@testset "Frontdoor Criterion"+` block with positive and +negative cases. +. Add a `+@testset "Markov Blanket"+` block verifying parents, children, +and co-parents are included. +. Add a `+@testset "Propensity Score Matching"+` block testing the +`+matching+` function. +. Add a `+@testset "Stratification"+` block testing the +`+stratification+` function. +. Add a `+@testset "Doubly Robust"+` block testing `+doubly_robust+`. +. Add a `+@testset "DoCalculus"+` block testing `+do_intervention+`, +`+identify_effect+`, `+adjustment_formula+`, and +`+confounding_adjustment+`. +. Add a `+@testset "Counterfactuals"+` block testing `+counterfactual+`, +`+twin_network+`, `+probability_of_necessity+`, +`+probability_of_sufficiency+`, and +`+probability_of_necessity_and_sufficiency+`. +. Each test should verify both normal operation and edge cases. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg; Pkg.activate(".") +Pkg.test() +# Should report all test sets passing with 0 failures +---- + +''''' + +=== TASK 14: Create missing documentation pages referenced in docs/make.jl (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Causals.jl/docs/src/+` + +*Problem:* The `+docs/make.jl+` file at lines 13-25 references 9 +documentation pages, but only 1 exists (`+index.md+`). Missing pages: - +`+dempster_shafer.md+` - `+bradford_hill.md+` - `+causal_dag.md+` - +`+granger.md+` - `+propensity.md+` - `+do_calculus.md+` - +`+counterfactuals.md+` - `+examples.md+` - `+api.md+` + +This means `+makedocs+` will fail with `+checkdocs = :exports+`. + +*What to do:* + +[arabic] +. Create each missing `+.md+` file in +`+/var$REPOS_DIR/Causals.jl/docs/src/+`. +. Each module page should contain: +* A brief description of the module +* Key concepts +* API reference using Documenter.jl `+@docs+` blocks for all exported +functions/types +. `+examples.md+` should reference the two example files with brief +descriptions. +. `+api.md+` should be a comprehensive API reference listing all +exported symbols with `+@docs+` blocks. +. Verify that `+makedocs+` can at least parse the pages without errors +(full build requires all deps). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +expected = ["index.md", "dempster_shafer.md", "bradford_hill.md", "causal_dag.md", + "granger.md", "propensity.md", "do_calculus.md", "counterfactuals.md", + "examples.md", "api.md"] +actual = readdir("docs/src") +for page in expected + @assert page in actual "Missing docs page: $page" +end +println("TASK 14 PASSED: all documentation pages exist") +---- + +''''' + +=== TASK 15: Fix version inconsistency between Project.toml and Manifest.toml (LOW) + +*Files:* `+/var$REPOS_DIR/Causals.jl/Project.toml+`, +`+/var$REPOS_DIR/Causals.jl/Manifest.toml+` + +*Problem:* `+Project.toml+` line 5 says `+version = "1.0.0"+` but +`+Manifest.toml+` line 33 says `+version = "0.1.0"+`. Additionally, the +git tags show both `+v0.1.0+` and `+v1.0.0+` exist. Given the actual +state of the code (many stubs and placeholders), `+1.0.0+` is dishonest. +The version should be `+0.2.0+` at most until all stubs are implemented. + +*What to do:* + +[arabic] +. Change `+Project.toml+` line 5 to `+version = "0.2.0"+`. +. Delete the `+Manifest.toml+` file and regenerate it: +`+cd /var$REPOS_DIR/Causals.jl && julia --project=. -e 'using Pkg; Pkg.resolve(); Pkg.instantiate()'+` +. The regenerated Manifest.toml will have the correct version. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +toml = read("Project.toml", String) +@assert occursin("version = \"0.2.0\"", toml) "Project.toml should have version 0.2.0" +println("TASK 15 PASSED: version is honest") +---- + +''''' + +=== TASK 16: Fix ROADMAP.md claims about non-existent modules (LOW) + +*Files:* `+/var$REPOS_DIR/Causals.jl/ROADMAP.md+` + +*Problem:* Lines 7-13 of ROADMAP.md claim "`Production-ready +implementation of 7 causal inference methods`" and list: +Dempster-Shafer, Conditional Probability, Probabilistic Logic, Bayesian +Networks, Fuzzy Logic, Evidential Reasoning, Belief Propagation. In +reality, the codebase has 7 DIFFERENT modules: DempsterShafer, +BradfordHill, CausalDAG, Granger, PropensityScore, DoCalculus, +Counterfactuals. The ROADMAP lists modules that do not exist. + +Line 14 claims "`Complete with comprehensive test coverage (66 tests)`" +– the actual test file has far fewer distinct assertions, and zero tests +for 3 of the 7 modules. + +*What to do:* + +[arabic] +. Replace lines 5-14 of ROADMAP.md with accurate module listing: +* DempsterShafer (mostly complete) +* BradfordHill (complete) +* CausalDAG (d_separation and frontdoor_criterion are stubs) +* Granger (p-value computation is fake) +* PropensityScore (propensity_score and doubly_robust are stubs) +* DoCalculus (confounding_adjustment and do_calculus_rules are stubs) +* Counterfactuals (counterfactual function is stub) +. Update the status line to say "`Alpha`" or "`In development`" instead +of "`Production-ready`". +. Update test count to actual number. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +roadmap = read("ROADMAP.md", String) +@assert !occursin("Bayesian Networks", roadmap) "ROADMAP should not claim Bayesian Networks exist" +@assert !occursin("Fuzzy Logic", roadmap) "ROADMAP should not claim Fuzzy Logic exists" +@assert !occursin("Production-ready", roadmap) "ROADMAP should not claim production-ready" +println("TASK 16 PASSED: ROADMAP is honest") +---- + +''''' + +=== TASK 17: Fix CITATIONS.adoc template placeholders (LOW) + +*Files:* `+/var$REPOS_DIR/Causals.jl/docs/CITATIONS.adoc+` + +*Problem:* The entire file is an unmodified RSR template. Line 1 says +`+= RSR-template-repo - Citation Guide+`, line 8 says +`+rsr-template-repo_2025+`, and line 14 references `+AGPL-3.0-or-later+` +(banned license). All references point to +`+hyperpolymath/RSR-template-repo+` instead of +`+hyperpolymath/Causals.jl+`. + +*What to do:* + +[arabic] +. Replace all occurrences of `+RSR-template-repo+` with `+Causals.jl+`. +. Replace `+rsr-template-repo+` with `+causals_jl+`. +. Replace `+AGPL-3.0-or-later+` with `+MPL-2.0+`. +. Replace `+Polymath, Hyper+` / `+Hyper Polymath+` with +`+Jewell, Jonathan D.A.+` / `+Jonathan D.A. Jewell+`. +. Update the year to 2026 if applicable. +. Update URLs to point to `+hyperpolymath/Causals.jl+`. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +citations = read("docs/CITATIONS.adoc", String) +@assert !occursin("RSR-template-repo", citations) "Should not reference template repo" +@assert !occursin("AGPL", citations) "Should not reference AGPL license" +@assert occursin("Causals.jl", citations) "Should reference Causals.jl" +@assert occursin("PMPL", citations) "Should reference PMPL license" +println("TASK 17 PASSED: CITATIONS.adoc is properly customized") +---- + +''''' + +=== TASK 18: Fix ROADMAP.adoc template placeholders (LOW) + +*Files:* `+/var$REPOS_DIR/Causals.jl/ROADMAP.adoc+` + +*Problem:* The entire file is the unmodified RSR template. Line 2 says +`+= YOUR Template Repo Roadmap+`. All milestones are generic +placeholders (`+Core functionality+`, `+Basic documentation+`, +`+Full feature set+`). + +*What to do:* + +[arabic] +. Replace the title with `+= Causals.jl Roadmap+`. +. Replace the generic milestones with actual Causals.jl milestones (can +be based on ROADMAP.md content, corrected per Task 16). +. Or delete this file entirely since ROADMAP.md already exists and +serves the same purpose. Having both is confusing. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +if isfile("ROADMAP.adoc") + roadmap = read("ROADMAP.adoc", String) + @assert !occursin("YOUR Template Repo", roadmap) "Should not be template placeholder" + @assert occursin("Causals", roadmap) "Should reference Causals.jl" +end +println("TASK 18 PASSED: ROADMAP.adoc is resolved") +---- + +''''' + +=== TASK 19: Fix AI.a2ml to reference correct directory and project (LOW) + +*Files:* `+/var$REPOS_DIR/Causals.jl/AI.a2ml+` + +*Problem:* Line 5 says +`+rsr-template-repo is treated as a Rhodium Standard Repository+` – +should reference Causals.jl. Line 5 also references +`+.machines_readable/6scm/+` (wrong path – should be +`+.machine_readable/+`). Lines 9-10 reference +`+.machines_readable/6scm/STATE.scm+` and +`+.machines_readable/6scm/AGENTIC.scm+` with the wrong directory name +and a nonexistent `+6scm+` subdirectory. There is no +`+.machine_readable/+` directory at all in this repo. + +*What to do:* + +[arabic] +. Replace `+rsr-template-repo+` with `+Causals.jl+` on line 5. +. Fix directory references from `+.machines_readable/6scm/+` to +`+.machine_readable/+`. +. Create the `+.machine_readable/+` directory with at minimum +`+STATE.scm+`, `+ECOSYSTEM.scm+`, and `+META.scm+` files. +. Update all path references throughout the file. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +ai = read("AI.a2ml", String) +@assert !occursin("rsr-template-repo", ai) "Should not reference template repo" +@assert occursin("Causals.jl", ai) "Should reference Causals.jl" +@assert isdir(".machine_readable") ".machine_readable directory must exist" +println("TASK 19 PASSED: AI.a2ml is properly configured") +---- + +''''' + +=== FINAL VERIFICATION + +After completing all tasks, run the following to verify the entire +package is working: + +[source,julia] +---- +cd("/var$REPOS_DIR/Causals.jl") +using Pkg +Pkg.activate(".") + +# 1. Full test suite +Pkg.test() + +# 2. Run both examples +include("examples/01_basic_usage.jl") +include("examples/02_advanced_analysis.jl") + +# 3. Verify no placeholder code remains +for f in ["src/CausalDAG.jl", "src/DoCalculus.jl", "src/Counterfactuals.jl", + "src/Granger.jl", "src/PropensityScore.jl"] + content = read(f, String) + @assert !occursin("# Placeholder", content) "Placeholder found in $f" + @assert !occursin("# Simplified", content) || occursin("# Simplified standard error", content) "Stub found in $f" +end + +# 4. Verify version +toml = read("Project.toml", String) +@assert occursin("version = \"0.2.0\"", toml) "Version should be 0.2.0" + +# 5. Verify docs pages exist +expected_docs = ["index.md", "dempster_shafer.md", "bradford_hill.md", "causal_dag.md", + "granger.md", "propensity.md", "do_calculus.md", "counterfactuals.md", + "examples.md", "api.md"] +actual_docs = readdir("docs/src") +for page in expected_docs + @assert page in actual_docs "Missing doc: $page" +end + +# 6. Verify no junk files in examples +example_files = readdir("examples") +@assert all(endswith.(example_files, ".jl")) "Only .jl files should be in examples/" + +println("=" ^ 60) +println("ALL VERIFICATION PASSED - Causals.jl is genuinely complete") +println("=" ^ 60) +---- diff --git a/packages/Causals.jl/SONNET-TASKS.md b/packages/Causals.jl/SONNET-TASKS.md deleted file mode 100644 index 74752b3bf..000000000 --- a/packages/Causals.jl/SONNET-TASKS.md +++ /dev/null @@ -1,812 +0,0 @@ -# SONNET-TASKS.md — Causals.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 42% - -The README claims "production-ready" and "complete with comprehensive test coverage." The ROADMAP.md claims v1.0 is done with "7 causal inference methods" (some of which do not even exist in the codebase -- Bayesian Networks, Fuzzy Logic, Evidential Reasoning, Belief Propagation, Conditional Probability, Probabilistic Logic are listed in the ROADMAP but not implemented). The Project.toml says version `1.0.0`. In reality: - -- 5 out of 7 source modules contain placeholder/stub code -- `d_separation` always returns `true` (hardcoded) -- `frontdoor_criterion` always returns `true` (hardcoded) -- `confounding_adjustment` always returns `0.0` (hardcoded) -- `do_calculus_rules` returns its input unchanged (no-op) -- `counterfactual` returns `nothing` (completely unimplemented) -- `propensity_score` ignores covariates entirely (returns constant) -- `doubly_robust` just calls IPW (defeats the purpose) -- `granger_test` uses a hardcoded critical F-value instead of the Distributions.jl F-distribution that is already a dependency -- Both example files have severe API mismatches and will not run -- No tests exist for DoCalculus, Counterfactuals, matching, stratification, or doubly_robust -- 6 of 7 docs pages referenced in `docs/make.jl` do not exist -- The ABI/FFI Idris2/Zig files are unmodified templates with `{{PROJECT}}` placeholders -- The `examples/` directory contains two unrelated non-Julia files (SafeDOMExample.res, web-project-deno.json) that should not be there - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update STATE.scm with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/Causals.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix d_separation to use proper Bayes-Ball algorithm (CRITICAL) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/CausalDAG.jl` - -**Problem:** The `d_separation` function at lines 60-70 is a complete stub. It always returns `true` regardless of input. The comment at line 62 says "Simplified implementation" and line 69 says `true # Placeholder`. This makes all downstream d-separation-dependent code (backdoor criterion, frontdoor criterion, do-calculus identification) unreliable. - -**What to do:** - -1. Replace the body of `d_separation` (lines 60-70) with a proper implementation using the Bayes-Ball algorithm (Shachter 1998) or the reachability-based algorithm: - - Build the "ancestral graph" of X, Y, and Z - - Moralize the ancestral graph (add edges between parents of common children) - - Remove edges involving Z nodes - - Check if X and Y are still connected in the resulting undirected graph -2. The function signature stays the same: `d_separation(g::CausalGraph, X::Set{Symbol}, Y::Set{Symbol}, Z::Set{Symbol}) -> Bool` -3. Return `true` if X and Y are d-separated given Z, `false` otherwise. -4. Handle edge cases: empty Z set, X or Y being singletons, X == Y (should return true trivially). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Causals.CausalDAG: add_edge! - -# Chain: X -> M -> Y -- X _|_ Y | M should be true -g1 = CausalGraph([:X, :M, :Y]) -add_edge!(g1, :X, :M) -add_edge!(g1, :M, :Y) -@assert d_separation(g1, Set([:X]), Set([:Y]), Set([:M])) == true "Chain: X _|_ Y | M" -@assert d_separation(g1, Set([:X]), Set([:Y]), Set{Symbol}()) == false "Chain: X NOT _|_ Y | {}" - -# Fork: X <- C -> Y -- X _|_ Y | C should be true -g2 = CausalGraph([:X, :C, :Y]) -add_edge!(g2, :C, :X) -add_edge!(g2, :C, :Y) -@assert d_separation(g2, Set([:X]), Set([:Y]), Set([:C])) == true "Fork: X _|_ Y | C" -@assert d_separation(g2, Set([:X]), Set([:Y]), Set{Symbol}()) == false "Fork: X NOT _|_ Y | {}" - -# Collider: X -> M <- Y -- X _|_ Y | {} should be true, X NOT _|_ Y | M -g3 = CausalGraph([:X, :M, :Y]) -add_edge!(g3, :X, :M) -add_edge!(g3, :Y, :M) -@assert d_separation(g3, Set([:X]), Set([:Y]), Set{Symbol}()) == true "Collider: X _|_ Y | {}" -@assert d_separation(g3, Set([:X]), Set([:Y]), Set([:M])) == false "Collider: X NOT _|_ Y | M" - -println("TASK 1 PASSED: d_separation works correctly") -``` - ---- - -## TASK 2: Fix frontdoor_criterion stub (CRITICAL) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/CausalDAG.jl` - -**Problem:** The `frontdoor_criterion` function at lines 188-194 always returns `true`. The body is `true` with a comment saying "Simplified implementation". The three conditions listed in the docstring (lines 184-186) are never checked. - -**What to do:** - -1. Replace the body of `frontdoor_criterion` (lines 188-194) with a proper implementation that checks all three conditions: - - Condition 1: M intercepts all directed paths from X to Y (every directed path from X to Y passes through some node in M) - - Condition 2: There are no unblocked backdoor paths from X to any node in M (i.e., no unconfounded relationship X->M) - - Condition 3: All backdoor paths from M to Y are blocked by X -2. For condition 1, enumerate directed paths from X to Y (DFS on the directed graph) and verify each passes through at least one node in M. -3. For condition 2, check `backdoor_criterion(g, X, m, Set{Symbol}())` or equivalent for each m in M (after removing X from the graph conceptually). -4. For condition 3, check d-separation conditions with X as the conditioning set. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Causals.CausalDAG: add_edge! - -# Classic frontdoor: X -> M -> Y, U -> X, U -> Y (U unobserved but in graph) -g = CausalGraph([:X, :M, :Y, :U]) -add_edge!(g, :X, :M) -add_edge!(g, :M, :Y) -add_edge!(g, :U, :X) -add_edge!(g, :U, :Y) -@assert frontdoor_criterion(g, :X, :Y, Set([:M])) == true "Frontdoor should hold for M" - -# Invalid frontdoor: M does not intercept all paths (direct X->Y edge exists) -g2 = CausalGraph([:X, :M, :Y, :U]) -add_edge!(g2, :X, :M) -add_edge!(g2, :M, :Y) -add_edge!(g2, :X, :Y) # Direct path bypasses M -add_edge!(g2, :U, :X) -add_edge!(g2, :U, :Y) -@assert frontdoor_criterion(g2, :X, :Y, Set([:M])) == false "Frontdoor should fail: direct X->Y bypasses M" - -println("TASK 2 PASSED: frontdoor_criterion works correctly") -``` - ---- - -## TASK 3: Implement proper p-value computation in granger_test using Distributions.jl (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/Granger.jl` - -**Problem:** Lines 49-50 compute the p-value using a hardcoded critical value `critical_F = 3.0` and return fake p-values (`0.01` or `0.1`). The package already depends on `Distributions.jl` (listed in Project.toml line 11) but it is not used in this module. - -**What to do:** - -1. Add `using Distributions` at the top of the Granger module (after line 11). -2. Replace lines 49-52 with proper F-distribution computation: - ```julia - df1 = k # numerator degrees of freedom - df2 = n_obs - 2 * best_lag - 1 # denominator degrees of freedom - f_dist = FDist(df1, df2) - p_value = 1.0 - cdf(f_dist, F_stat) - causes = p_value < α - ``` -3. Remove the `critical_F` variable entirely. -4. Ensure the `α` keyword argument is actually used (currently it is accepted but ignored because the hardcoded critical value is used instead). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals - -# Known causal relationship -n = 200 -x = randn(n) -y = zeros(n) -for t in 2:n - y[t] = 0.5 * y[t-1] + 0.8 * x[t-1] + 0.05 * randn() -end - -causes, F_stat, p_value, lag = granger_test(x, y, 5) -@assert p_value >= 0.0 && p_value <= 1.0 "p-value must be in [0,1], got $p_value" -@assert p_value < 0.05 "Strong causal signal should have p < 0.05, got $p_value" -@assert causes == true "Should detect Granger causality" - -# Independent series should not show causality -x_indep = randn(200) -y_indep = randn(200) -causes_indep, _, p_indep, _ = granger_test(x_indep, y_indep, 5) -@assert p_indep > 0.0 "Independent series p-value should not be zero" - -println("TASK 3 PASSED: granger_test uses proper F-distribution p-values") -``` - ---- - -## TASK 4: Implement real propensity_score using logistic regression (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/PropensityScore.jl` - -**Problem:** The `propensity_score` function at lines 22-31 completely ignores the `covariates` argument. It computes `p = sum(treatment) / n` (the marginal treatment probability) and returns `fill(p, n)` -- a vector of identical values. This makes all downstream methods (matching, IPW, stratification) meaningless because every unit gets the same propensity score. - -**What to do:** - -1. Implement logistic regression using iteratively reweighted least squares (IRLS): - - Initialize coefficients beta to zeros - - Iterate: compute predictions p = logistic(X*beta), weights W = diag(p.*(1-p)), update beta = beta + inv(X'*W*X) * X' * (treatment - p) - - Converge when max change in beta < 1e-8 or after 25 iterations -2. Add an intercept column to covariates internally: `X = hcat(ones(n), covariates)` -3. Clip propensity scores to [0.01, 0.99] to avoid division by zero in IPW. -4. Return the fitted propensity scores. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Random; Random.seed!(42) - -n = 200 -x1 = randn(n) -x2 = randn(n) -# Treatment depends on covariates -logit = 0.5 .* x1 .+ 0.3 .* x2 .- 0.2 -p_true = 1.0 ./ (1.0 .+ exp.(-logit)) -treatment = rand(n) .< p_true - -ps = propensity_score(treatment, hcat(x1, x2)) -@assert length(ps) == n -@assert !all(ps .== ps[1]) "Propensity scores must vary across observations, not be constant" -@assert all(0.0 .<= ps .<= 1.0) "All scores must be in [0,1]" -@assert cor(ps, p_true) > 0.5 "Estimated scores should correlate with true propensity" - -println("TASK 4 PASSED: propensity_score uses actual logistic regression") -``` - ---- - -## TASK 5: Implement confounding_adjustment (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/DoCalculus.jl` - -**Problem:** The `confounding_adjustment` function at lines 90-103 always returns `0.0` (line 102 says `0.0 # Placeholder`). The function is supposed to compute the backdoor-adjusted causal effect E[Y|do(X=1)] - E[Y|do(X=0)] using stratification over confounders. - -**What to do:** - -1. Replace the body of `confounding_adjustment` (lines 90-103) with a real implementation: - - The `data` dictionary maps variable names to Float64 vectors. - - Binarize or stratify by the confounder values (use quantile-based binning for continuous confounders). - - For each stratum z of confounders: compute E[Y|X=1,Z=z] and E[Y|X=0,Z=z], weighted by P(Z=z). - - Return the weighted sum: sum_z (E[Y|X=1,Z=z] - E[Y|X=0,Z=z]) * P(Z=z). -2. Handle cases where a stratum has no treated or no control units (skip that stratum). -3. Handle single vs multiple confounders by creating combined strata. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Random; Random.seed!(42) - -n = 500 -z = randn(n) -x = (z .+ randn(n)) .> 0 # Treatment depends on confounder -x_float = Float64.(x) -y = 2.0 .* x_float .+ 1.5 .* z .+ randn(n) # True causal effect of X is 2.0 - -data = Dict( - :X => x_float, - :Y => y, - :Z => z -) - -effect = confounding_adjustment(:X, :Y, Set([:Z]), data) -@assert abs(effect) > 0.0 "Effect must not be zero placeholder" -@assert abs(effect - 2.0) < 1.0 "Adjusted effect should be near 2.0, got $effect" - -println("TASK 5 PASSED: confounding_adjustment computes real adjusted effects") -``` - ---- - -## TASK 6: Implement do_calculus_rules (MEDIUM) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/DoCalculus.jl` - -**Problem:** The `do_calculus_rules` function at lines 78-82 is a no-op that returns its input query unchanged. The docstring describes Pearl's three rules of do-calculus but none are implemented. - -**What to do:** - -1. Define a proper query representation type. At minimum, a tagged union or struct that can represent: - - `P(Y | do(X), Z)` -- conditional with intervention - - `P(Y | X, Z)` -- standard conditional -2. Implement Rule 1 (insertion/deletion of observations): P(Y | do(X), Z, W) = P(Y | do(X), Z) if Y _|_ W | X, Z in G_overbar_X -3. Implement Rule 2 (action/observation exchange): P(Y | do(X), do(Z), W) = P(Y | do(X), Z, W) if Y _|_ Z | X, W in G_overbar_X_underbar_Z -4. Implement Rule 3 (insertion/deletion of actions): P(Y | do(X), do(Z), W) = P(Y | do(X), W) if Y _|_ Z | X, W in G_overbar_X_overbar_Z(W) -5. If full implementation is too complex, implement at least Rules 1 and 2 with proper graph manipulation and d-separation checks (which will work after Task 1). -6. Update the function signature to accept a `CausalGraph` and return a simplified query or `:cannot_simplify`. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Causals.CausalDAG: add_edge! -using Causals.DoCalculus - -# Build a simple graph -g = CausalGraph([:X, :Y, :Z]) -add_edge!(g, :X, :Y) -add_edge!(g, :Z, :X) -add_edge!(g, :Z, :Y) - -# At minimum, the function should not be a no-op -result = do_calculus_rules(g, (:Y, :do_X)) -@assert result !== (:Y, :do_X) || typeof(result) != typeof((:Y, :do_X)) "do_calculus_rules must not be a no-op" - -println("TASK 6 PASSED: do_calculus_rules implements at least basic simplification") -``` - ---- - -## TASK 7: Implement counterfactual function with structural equations (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/Counterfactuals.jl` - -**Problem:** The `counterfactual` function at lines 37-54 returns `nothing` (line 53). The three-step process described in the docstring (Abduction, Action, Prediction) is outlined in comments but not implemented. `U` is an empty Dict (line 45) and the function terminates with `nothing`. - -**What to do:** - -1. Extend the `counterfactual` function to accept structural equations. Add an optional `equations` parameter of type `Dict{Symbol, Function}` where each function takes a Dict of parent values and noise and returns the variable's value. -2. Implement the three-step process: - - **Abduction**: Given observations and structural equations, infer noise terms U by solving the equations backwards. - - **Action**: Apply the intervention (set X=x, remove incoming edges to X in the graph). - - **Prediction**: Evaluate structural equations forward in topological order using the inferred U values and the intervention. -3. Return the counterfactual value of the outcome variable as a `Dict{Symbol, Any}` mapping variable names to their counterfactual values. -4. If no equations are provided, return `nothing` with a warning (preserve backward compatibility). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Causals.CausalDAG: add_edge! -using Causals.Counterfactuals - -# Simple SCM: X -> Y, Y = 2*X + noise -g = CausalGraph([:X, :Y]) -add_edge!(g, :X, :Y) - -# Structural equations: Y = 2X + U_Y -equations = Dict( - :X => (parents, noise) -> get(noise, :U_X, 0.0), - :Y => (parents, noise) -> 2.0 * parents[:X] + get(noise, :U_Y, 0.0) -) - -# Observed: X=3, Y=6.5 (so U_Y = 0.5) -observations = Dict(:X => 3.0, :Y => 6.5) - -result = counterfactual(g, :Y, :X => 5.0, observations; equations=equations) -@assert result !== nothing "counterfactual must not return nothing" -# Counterfactual Y when X=5: 2*5 + 0.5 = 10.5 -@assert abs(result - 10.5) < 0.01 "Counterfactual Y should be 10.5, got $result" - -println("TASK 7 PASSED: counterfactual computes actual counterfactual values") -``` - ---- - -## TASK 8: Implement doubly_robust estimator properly (MEDIUM) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/PropensityScore.jl` - -**Problem:** The `doubly_robust` function at lines 145-155 just calls `inverse_probability_weighting` and returns its result. The comment on line 151 says "Simplified implementation". This defeats the entire purpose of the doubly robust estimator, which should be consistent if EITHER the propensity model OR the outcome model is correct. - -**What to do:** - -1. Replace the body of `doubly_robust` (lines 145-155) with the proper Augmented IPW (AIPW) formula: - ``` - ATE = (1/n) * sum_i [ - (treatment_i * outcome_i / propensity_i) - ((treatment_i - propensity_i) / propensity_i) * outcome_model_1(x_i) - - ((1-treatment_i) * outcome_i / (1-propensity_i)) + ((treatment_i - propensity_i) / (1-propensity_i)) * outcome_model_0(x_i) - ] - ``` -2. The `outcome_model` parameter should accept predicted outcomes for both treated and control groups. Update the function signature if needed: accept `outcome_model_1` and `outcome_model_0` vectors (predicted outcomes under treatment and control), or a single function that takes covariates and treatment indicator. -3. Compute proper standard errors using the influence function. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Random; Random.seed!(42) - -n = 200 -treatment = rand(Bool, n) -outcome = Float64.(treatment) .* 2.0 .+ randn(n) -propensity = fill(0.5, n) - -# Simple outcome model: predict mean outcome per group -mean_treated = mean(outcome[treatment]) -mean_control = mean(outcome[.!treatment]) -outcome_model = (x) -> treatment .* mean_treated .+ (1 .- treatment) .* mean_control - -dr_ate = doubly_robust(treatment, outcome, propensity, outcome_model) -@assert !isnan(dr_ate) "DR estimate must not be NaN" -@assert abs(dr_ate - 2.0) < 1.5 "DR estimate should be near true effect 2.0, got $dr_ate" - -# Verify it gives different result than plain IPW -ipw_ate, _ = inverse_probability_weighting(treatment, outcome, propensity) -# They may be similar but should not be identical in general -println("DR ATE: $dr_ate, IPW ATE: $ipw_ate") - -println("TASK 8 PASSED: doubly_robust uses proper AIPW estimator") -``` - ---- - -## TASK 9: Fix identify_effect to try frontdoor criterion (MEDIUM) - -**Files:** `/var$REPOS_DIR/Causals.jl/src/DoCalculus.jl` - -**Problem:** The `identify_effect` function at lines 41-51 only tries the backdoor criterion and immediately gives up if it fails (line 49-50: "Simplified: return false if backdoor fails"). The comment at lines 47-49 says it should try frontdoor but does not. - -**What to do:** - -1. After the backdoor check fails, enumerate possible mediator sets M (subsets of non-treatment, non-outcome nodes). -2. For each candidate set M, call `frontdoor_criterion(g, X, Y, M)`. -3. If any M satisfies the frontdoor criterion, return `(true, :frontdoor, M)`. -4. Only return `(false, :unidentifiable, Set{Symbol}())` if BOTH backdoor and frontdoor criteria fail for all candidate adjustment/mediator sets. -5. For the backdoor case with empty Z: also try non-empty subsets of valid adjustment sets (non-descendants of X). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -using Causals -using Causals.CausalDAG: add_edge! -using Causals.DoCalculus - -# Frontdoor-identifiable graph: X -> M -> Y, U -> X, U -> Y -g = CausalGraph([:X, :M, :Y, :U]) -add_edge!(g, :X, :M) -add_edge!(g, :M, :Y) -add_edge!(g, :U, :X) -add_edge!(g, :U, :Y) - -identifiable, method, set = identify_effect(g, :X, :Y) -@assert identifiable == true "Effect should be identifiable via frontdoor" -@assert method == :frontdoor "Should identify via frontdoor, got $method" -@assert :M in set "Mediator set should contain M" - -# Also test backdoor still works -g2 = CausalGraph([:X, :Y, :Z]) -add_edge!(g2, :X, :Y) -add_edge!(g2, :Z, :X) -add_edge!(g2, :Z, :Y) - -identifiable2, method2, set2 = identify_effect(g2, :X, :Y, Set([:Z])) -@assert identifiable2 == true "Effect should be identifiable via backdoor" -@assert method2 == :backdoor "Should identify via backdoor" - -println("TASK 9 PASSED: identify_effect tries frontdoor criterion") -``` - ---- - -## TASK 10: Fix example 01_basic_usage.jl API mismatches (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/examples/01_basic_usage.jl` - -**Problem:** The example will not run because it uses APIs that do not match the actual source code. Specific mismatches: - -- Line 30-31: `MassAssignment(Dict(...))` -- constructor requires TWO args: `MassAssignment(frame, masses_dict)`, not just a dict. -- Line 36-38: Same issue for `evidence2`. -- Line 51: `pignistic_transform(combined, frame)` -- function only takes 1 argument: `pignistic_transform(m::MassAssignment)`. -- Line 75-79: `assess_causality(assessment)` returns a tuple `(verdict, confidence)`, not a scalar. The code assigns it to `causality_score` and calls it as if it is a number, then also calls `strength_of_evidence` separately. -- Line 91: `CausalGraph(DiGraph(4))` -- constructor takes `Vector{Symbol}`, not a `DiGraph`. Should be `CausalGraph([:Education, :Income, :Health, :Exercise])`. -- Lines 94-97: `CausalDAG.add_edge!(cg, 1, 2)` -- uses integer indices, but `add_edge!` takes `Symbol` arguments. -- Line 105: `d_separation(cg, [1], [4], [2])` -- takes `Set{Symbol}`, not `Vector{Int}`. -- Lines 112-113: `ancestors(cg, 3)` and `descendants(cg, 1)` -- take `Symbol`, not `Int`. -- Line 117: `backdoor_criterion(cg, 2, 3, [1])` -- takes `Symbol, Symbol, Set{Symbol}`, not integers and vector. - -**What to do:** - -1. Fix all constructor calls to use `MassAssignment(frame, masses)` (two arguments). -2. Fix `pignistic_transform` call to pass only one argument. -3. Fix `assess_causality` return value handling (it returns a tuple). -4. Replace `CausalGraph(DiGraph(4))` with `CausalGraph([:Education, :Income, :Health, :Exercise])`. -5. Replace all integer-based API calls with Symbol-based calls. -6. Replace `d_separation(cg, [1], [4], [2])` with `d_separation(cg, Set([:Education]), Set([:Exercise]), Set([:Income]))`. -7. Fix `ancestors`/`descendants` calls to use Symbols. -8. Fix `backdoor_criterion` call to use Symbols and Set. -9. Remove `using Graphs` import (no longer needed after fixing CausalGraph constructor). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -include("/var$REPOS_DIR/Causals.jl/examples/01_basic_usage.jl") -println("TASK 10 PASSED: example 01 runs without errors") -``` - ---- - -## TASK 11: Fix example 02_advanced_analysis.jl API mismatches (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/examples/02_advanced_analysis.jl` - -**Problem:** The example will not run because it uses APIs that do not match the actual source code. Specific mismatches: - -- Line 47: `granger_test(x, y; max_lag=5)` uses keyword arg syntax. The actual function has `max_lag` as a positional argument: `granger_test(x, y, 5)`. -- Lines 48-50: `result.f_stat`, `result.p_value`, `result.causes` -- `granger_test` returns a tuple `(causes, F_stat, p_value, best_lag)`, not a named struct. -- Line 54: `optimal_lag(x, y; max_lag=8)` uses keyword arg. Actual signature: `optimal_lag(x, y, 8)`. -- Line 88: `matching(treatment, propensity_scores)` -- missing `outcome` argument. Actual signature: `matching(treatment, outcome, propensity; method=:nearest, caliper=0.1)`, returns `(matches, ate, se)`. -- Lines 93-94: Tries to index matches as `pair[1]`, `pair[2]` -- but matches are `Tuple{Int,Int}` which is indexed this way, so this may work if matching returns pairs. -- Line 108: `CausalGraph(DiGraph(3))` -- should be `CausalGraph([:Z, :X, :Y])` with Symbols. -- Lines 109-111: `CausalDAG.add_edge!(confounded_graph, 1, 2)` -- uses integers, should use Symbols. -- Line 117: `identify_effect(confounded_graph, 2, 3)` -- uses integers, should use Symbols. -- Line 123: `confounding_adjustment(confounded_graph, 2, 3)` -- completely wrong signature. The actual function takes `(treatment::Symbol, outcome::Symbol, confounders::Set{Symbol}, data::Dict{...})`, not a graph with integers. -- Lines 135-158: The counterfactual section uses `counterfactual(structural_equations, observed_values, Dict(:X => 5.0))` -- completely wrong API. Actual signature: `counterfactual(g::CausalGraph, outcome::Symbol, intervention::Pair{Symbol, Any}, observations::Dict{Symbol, Any})`. - -**What to do:** - -1. Fix `granger_test` call to use positional `max_lag` and destructure the tuple return. -2. Fix `optimal_lag` call to use positional argument. -3. Fix `matching` call to include all required arguments: `matching(treatment, observed_outcomes, propensity_scores)`. -4. Fix `CausalGraph` constructor to use Symbols. -5. Fix all `add_edge!` calls to use Symbols. -6. Fix `identify_effect` call to use Symbols. -7. Fix `confounding_adjustment` call to use the correct signature. -8. Fix the counterfactual section to use the actual API. -9. Remove `using Graphs` import (no longer needed). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -include("/var$REPOS_DIR/Causals.jl/examples/02_advanced_analysis.jl") -println("TASK 11 PASSED: example 02 runs without errors") -``` - ---- - -## TASK 12: Remove non-Julia junk files from examples/ (LOW) - -**Files:** `/var$REPOS_DIR/Causals.jl/examples/SafeDOMExample.res`, `/var$REPOS_DIR/Causals.jl/examples/web-project-deno.json` - -**Problem:** The `examples/` directory contains two files that have nothing to do with Causals.jl: -- `SafeDOMExample.res` -- a ReScript DOM mounting example (from a different project entirely) -- `web-project-deno.json` -- a Deno project config for ReScript web projects - -These are RSR template leftovers that were never cleaned up. - -**What to do:** - -1. Delete `/var$REPOS_DIR/Causals.jl/examples/SafeDOMExample.res` -2. Delete `/var$REPOS_DIR/Causals.jl/examples/web-project-deno.json` -3. Verify only `01_basic_usage.jl` and `02_advanced_analysis.jl` remain in `examples/`. - -**Verification:** -```julia -files = readdir("/var$REPOS_DIR/Causals.jl/examples/") -@assert files == ["01_basic_usage.jl", "02_advanced_analysis.jl"] "examples/ should only contain Julia files, got $files" -println("TASK 12 PASSED: examples directory is clean") -``` - ---- - -## TASK 13: Add missing tests for DoCalculus, Counterfactuals, matching, stratification, doubly_robust (HIGH) - -**Files:** `/var$REPOS_DIR/Causals.jl/test/runtests.jl` - -**Problem:** The test file has no test sections for: -- DoCalculus (no `@testset "DoCalculus"` at all) -- Counterfactuals (no `@testset "Counterfactuals"` at all) -- `matching` (the function is not tested despite being exported) -- `stratification` (not tested) -- `doubly_robust` (not tested) -- `d_separation` (not tested despite being a critical function) -- `frontdoor_criterion` (not tested) -- `markov_blanket` (not tested) - -**What to do:** - -1. Add a `@testset "D-Separation"` block with tests for chains, forks, and colliders (similar to Task 1 verification). -2. Add a `@testset "Frontdoor Criterion"` block with positive and negative cases. -3. Add a `@testset "Markov Blanket"` block verifying parents, children, and co-parents are included. -4. Add a `@testset "Propensity Score Matching"` block testing the `matching` function. -5. Add a `@testset "Stratification"` block testing the `stratification` function. -6. Add a `@testset "Doubly Robust"` block testing `doubly_robust`. -7. Add a `@testset "DoCalculus"` block testing `do_intervention`, `identify_effect`, `adjustment_formula`, and `confounding_adjustment`. -8. Add a `@testset "Counterfactuals"` block testing `counterfactual`, `twin_network`, `probability_of_necessity`, `probability_of_sufficiency`, and `probability_of_necessity_and_sufficiency`. -9. Each test should verify both normal operation and edge cases. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg; Pkg.activate(".") -Pkg.test() -# Should report all test sets passing with 0 failures -``` - ---- - -## TASK 14: Create missing documentation pages referenced in docs/make.jl (MEDIUM) - -**Files:** `/var$REPOS_DIR/Causals.jl/docs/src/` - -**Problem:** The `docs/make.jl` file at lines 13-25 references 9 documentation pages, but only 1 exists (`index.md`). Missing pages: -- `dempster_shafer.md` -- `bradford_hill.md` -- `causal_dag.md` -- `granger.md` -- `propensity.md` -- `do_calculus.md` -- `counterfactuals.md` -- `examples.md` -- `api.md` - -This means `makedocs` will fail with `checkdocs = :exports`. - -**What to do:** - -1. Create each missing `.md` file in `/var$REPOS_DIR/Causals.jl/docs/src/`. -2. Each module page should contain: - - A brief description of the module - - Key concepts - - API reference using Documenter.jl `@docs` blocks for all exported functions/types -3. `examples.md` should reference the two example files with brief descriptions. -4. `api.md` should be a comprehensive API reference listing all exported symbols with `@docs` blocks. -5. Verify that `makedocs` can at least parse the pages without errors (full build requires all deps). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -expected = ["index.md", "dempster_shafer.md", "bradford_hill.md", "causal_dag.md", - "granger.md", "propensity.md", "do_calculus.md", "counterfactuals.md", - "examples.md", "api.md"] -actual = readdir("docs/src") -for page in expected - @assert page in actual "Missing docs page: $page" -end -println("TASK 14 PASSED: all documentation pages exist") -``` - ---- - -## TASK 15: Fix version inconsistency between Project.toml and Manifest.toml (LOW) - -**Files:** `/var$REPOS_DIR/Causals.jl/Project.toml`, `/var$REPOS_DIR/Causals.jl/Manifest.toml` - -**Problem:** `Project.toml` line 5 says `version = "1.0.0"` but `Manifest.toml` line 33 says `version = "0.1.0"`. Additionally, the git tags show both `v0.1.0` and `v1.0.0` exist. Given the actual state of the code (many stubs and placeholders), `1.0.0` is dishonest. The version should be `0.2.0` at most until all stubs are implemented. - -**What to do:** - -1. Change `Project.toml` line 5 to `version = "0.2.0"`. -2. Delete the `Manifest.toml` file and regenerate it: `cd /var$REPOS_DIR/Causals.jl && julia --project=. -e 'using Pkg; Pkg.resolve(); Pkg.instantiate()'` -3. The regenerated Manifest.toml will have the correct version. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -toml = read("Project.toml", String) -@assert occursin("version = \"0.2.0\"", toml) "Project.toml should have version 0.2.0" -println("TASK 15 PASSED: version is honest") -``` - ---- - -## TASK 16: Fix ROADMAP.md claims about non-existent modules (LOW) - -**Files:** `/var$REPOS_DIR/Causals.jl/ROADMAP.md` - -**Problem:** Lines 7-13 of ROADMAP.md claim "Production-ready implementation of 7 causal inference methods" and list: Dempster-Shafer, Conditional Probability, Probabilistic Logic, Bayesian Networks, Fuzzy Logic, Evidential Reasoning, Belief Propagation. In reality, the codebase has 7 DIFFERENT modules: DempsterShafer, BradfordHill, CausalDAG, Granger, PropensityScore, DoCalculus, Counterfactuals. The ROADMAP lists modules that do not exist. - -Line 14 claims "Complete with comprehensive test coverage (66 tests)" -- the actual test file has far fewer distinct assertions, and zero tests for 3 of the 7 modules. - -**What to do:** - -1. Replace lines 5-14 of ROADMAP.md with accurate module listing: - - DempsterShafer (mostly complete) - - BradfordHill (complete) - - CausalDAG (d_separation and frontdoor_criterion are stubs) - - Granger (p-value computation is fake) - - PropensityScore (propensity_score and doubly_robust are stubs) - - DoCalculus (confounding_adjustment and do_calculus_rules are stubs) - - Counterfactuals (counterfactual function is stub) -2. Update the status line to say "Alpha" or "In development" instead of "Production-ready". -3. Update test count to actual number. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -roadmap = read("ROADMAP.md", String) -@assert !occursin("Bayesian Networks", roadmap) "ROADMAP should not claim Bayesian Networks exist" -@assert !occursin("Fuzzy Logic", roadmap) "ROADMAP should not claim Fuzzy Logic exists" -@assert !occursin("Production-ready", roadmap) "ROADMAP should not claim production-ready" -println("TASK 16 PASSED: ROADMAP is honest") -``` - ---- - -## TASK 17: Fix CITATIONS.adoc template placeholders (LOW) - -**Files:** `/var$REPOS_DIR/Causals.jl/docs/CITATIONS.adoc` - -**Problem:** The entire file is an unmodified RSR template. Line 1 says `= RSR-template-repo - Citation Guide`, line 8 says `rsr-template-repo_2025`, and line 14 references `AGPL-3.0-or-later` (banned license). All references point to `hyperpolymath/RSR-template-repo` instead of `hyperpolymath/Causals.jl`. - -**What to do:** - -1. Replace all occurrences of `RSR-template-repo` with `Causals.jl`. -2. Replace `rsr-template-repo` with `causals_jl`. -3. Replace `AGPL-3.0-or-later` with `MPL-2.0`. -4. Replace `Polymath, Hyper` / `Hyper Polymath` with `Jewell, Jonathan D.A.` / `Jonathan D.A. Jewell`. -5. Update the year to 2026 if applicable. -6. Update URLs to point to `hyperpolymath/Causals.jl`. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -citations = read("docs/CITATIONS.adoc", String) -@assert !occursin("RSR-template-repo", citations) "Should not reference template repo" -@assert !occursin("AGPL", citations) "Should not reference AGPL license" -@assert occursin("Causals.jl", citations) "Should reference Causals.jl" -@assert occursin("PMPL", citations) "Should reference PMPL license" -println("TASK 17 PASSED: CITATIONS.adoc is properly customized") -``` - ---- - -## TASK 18: Fix ROADMAP.adoc template placeholders (LOW) - -**Files:** `/var$REPOS_DIR/Causals.jl/ROADMAP.adoc` - -**Problem:** The entire file is the unmodified RSR template. Line 2 says `= YOUR Template Repo Roadmap`. All milestones are generic placeholders (`Core functionality`, `Basic documentation`, `Full feature set`). - -**What to do:** - -1. Replace the title with `= Causals.jl Roadmap`. -2. Replace the generic milestones with actual Causals.jl milestones (can be based on ROADMAP.md content, corrected per Task 16). -3. Or delete this file entirely since ROADMAP.md already exists and serves the same purpose. Having both is confusing. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -if isfile("ROADMAP.adoc") - roadmap = read("ROADMAP.adoc", String) - @assert !occursin("YOUR Template Repo", roadmap) "Should not be template placeholder" - @assert occursin("Causals", roadmap) "Should reference Causals.jl" -end -println("TASK 18 PASSED: ROADMAP.adoc is resolved") -``` - ---- - -## TASK 19: Fix AI.a2ml to reference correct directory and project (LOW) - -**Files:** `/var$REPOS_DIR/Causals.jl/AI.a2ml` - -**Problem:** Line 5 says `rsr-template-repo is treated as a Rhodium Standard Repository` -- should reference Causals.jl. Line 5 also references `.machines_readable/6scm/` (wrong path -- should be `.machine_readable/`). Lines 9-10 reference `.machines_readable/6scm/STATE.scm` and `.machines_readable/6scm/AGENTIC.scm` with the wrong directory name and a nonexistent `6scm` subdirectory. There is no `.machine_readable/` directory at all in this repo. - -**What to do:** - -1. Replace `rsr-template-repo` with `Causals.jl` on line 5. -2. Fix directory references from `.machines_readable/6scm/` to `.machine_readable/`. -3. Create the `.machine_readable/` directory with at minimum `STATE.scm`, `ECOSYSTEM.scm`, and `META.scm` files. -4. Update all path references throughout the file. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Causals.jl") -ai = read("AI.a2ml", String) -@assert !occursin("rsr-template-repo", ai) "Should not reference template repo" -@assert occursin("Causals.jl", ai) "Should reference Causals.jl" -@assert isdir(".machine_readable") ".machine_readable directory must exist" -println("TASK 19 PASSED: AI.a2ml is properly configured") -``` - ---- - -## FINAL VERIFICATION - -After completing all tasks, run the following to verify the entire package is working: - -```julia -cd("/var$REPOS_DIR/Causals.jl") -using Pkg -Pkg.activate(".") - -# 1. Full test suite -Pkg.test() - -# 2. Run both examples -include("examples/01_basic_usage.jl") -include("examples/02_advanced_analysis.jl") - -# 3. Verify no placeholder code remains -for f in ["src/CausalDAG.jl", "src/DoCalculus.jl", "src/Counterfactuals.jl", - "src/Granger.jl", "src/PropensityScore.jl"] - content = read(f, String) - @assert !occursin("# Placeholder", content) "Placeholder found in $f" - @assert !occursin("# Simplified", content) || occursin("# Simplified standard error", content) "Stub found in $f" -end - -# 4. Verify version -toml = read("Project.toml", String) -@assert occursin("version = \"0.2.0\"", toml) "Version should be 0.2.0" - -# 5. Verify docs pages exist -expected_docs = ["index.md", "dempster_shafer.md", "bradford_hill.md", "causal_dag.md", - "granger.md", "propensity.md", "do_calculus.md", "counterfactuals.md", - "examples.md", "api.md"] -actual_docs = readdir("docs/src") -for page in expected_docs - @assert page in actual_docs "Missing doc: $page" -end - -# 6. Verify no junk files in examples -example_files = readdir("examples") -@assert all(endswith.(example_files, ".jl")) "Only .jl files should be in examples/" - -println("=" ^ 60) -println("ALL VERIFICATION PASSED - Causals.jl is genuinely complete") -println("=" ^ 60) -``` diff --git a/packages/Causals.jl/TOPOLOGY.md b/packages/Causals.jl/TOPOLOGY.adoc similarity index 90% rename from packages/Causals.jl/TOPOLOGY.md rename to packages/Causals.jl/TOPOLOGY.adoc index 49d3735f2..844ca7d67 100644 --- a/packages/Causals.jl/TOPOLOGY.md +++ b/packages/Causals.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Causals.jl — Project Topology -# Causals.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -48,11 +44,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CAUSAL METHODS @@ -72,26 +68,27 @@ INFRASTRUCTURE & DOCS ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~95% Core Implementation Complete -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Causal DAG ───────────► Do-Calculus ──────────► Counterfactuals ▲ Propensity Score ───────────┘ │ Granger ─────────────► Unified API ◀────────── Bradford Hill -``` +.... -## 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/packages/Causals.jl/docs/src/api.md b/packages/Causals.jl/docs/src/api.adoc similarity index 57% rename from packages/Causals.jl/docs/src/api.md rename to packages/Causals.jl/docs/src/api.adoc index aef308334..cf86f7c1f 100644 --- a/packages/Causals.jl/docs/src/api.md +++ b/packages/Causals.jl/docs/src/api.adoc @@ -1,28 +1,32 @@ -# API Reference +== API Reference -Complete API reference for all exported functions and types in Causals.jl. +Complete API reference for all exported functions and types in +Causals.jl. -## Dempster-Shafer Module +=== Dempster-Shafer Module -```@docs +[source,@docs] +---- MassAssignment belief plausibility combine_dempster pignistic_transform -``` +---- -## Bradford Hill Module +=== Bradford Hill Module -```@docs +[source,@docs] +---- BradfordHillCriteria assess_causality strength_of_evidence -``` +---- -## Causal DAG Module +=== Causal DAG Module -```@docs +[source,@docs] +---- CausalGraph add_edge! remove_edge! @@ -32,50 +36,55 @@ descendants backdoor_criterion frontdoor_criterion markov_blanket -``` +---- -## Granger Causality Module +=== Granger Causality Module -```@docs +[source,@docs] +---- granger_test granger_causality optimal_lag bidirectional_granger -``` +---- -## Propensity Score Module +=== Propensity Score Module -```@docs +[source,@docs] +---- propensity_score matching inverse_probability_weighting stratification doubly_robust -``` +---- -## Do-Calculus Module +=== Do-Calculus Module -```@docs +[source,@docs] +---- do_intervention identify_effect adjustment_formula confounding_adjustment do_calculus_rules Query -``` +---- -## Counterfactuals Module +=== Counterfactuals Module -```@docs +[source,@docs] +---- counterfactual twin_network probability_of_necessity probability_of_sufficiency probability_of_necessity_and_sufficiency Counterfactual -``` +---- -## Index +=== Index -```@index -``` +[source,@index] +---- +---- diff --git a/packages/Causals.jl/docs/src/bradford_hill.adoc b/packages/Causals.jl/docs/src/bradford_hill.adoc new file mode 100644 index 000000000..824dd7500 --- /dev/null +++ b/packages/Causals.jl/docs/src/bradford_hill.adoc @@ -0,0 +1,25 @@ +== Bradford Hill Criteria + +The Bradford Hill module provides systematic assessment of causal +relationships using the nine Bradford Hill criteria. + +=== Key Concepts + +* *Strength of Association*: How strong is the relationship? +* *Consistency*: Is it replicated across studies? +* *Specificity*: Is the effect specific to the exposure? +* *Temporality*: Does cause precede effect? +* *Biological Gradient*: Is there a dose-response relationship? +* *Plausibility*: Is there a plausible mechanism? +* *Coherence*: Does it fit with existing knowledge? +* *Experiment*: Is there experimental evidence? +* *Analogy*: Are there analogous relationships? + +=== API Reference + +[source,@docs] +---- +BradfordHillCriteria +assess_causality +strength_of_evidence +---- diff --git a/packages/Causals.jl/docs/src/bradford_hill.md b/packages/Causals.jl/docs/src/bradford_hill.md deleted file mode 100644 index d782339a7..000000000 --- a/packages/Causals.jl/docs/src/bradford_hill.md +++ /dev/null @@ -1,23 +0,0 @@ -# Bradford Hill Criteria - -The Bradford Hill module provides systematic assessment of causal relationships using the nine Bradford Hill criteria. - -## Key Concepts - -- **Strength of Association**: How strong is the relationship? -- **Consistency**: Is it replicated across studies? -- **Specificity**: Is the effect specific to the exposure? -- **Temporality**: Does cause precede effect? -- **Biological Gradient**: Is there a dose-response relationship? -- **Plausibility**: Is there a plausible mechanism? -- **Coherence**: Does it fit with existing knowledge? -- **Experiment**: Is there experimental evidence? -- **Analogy**: Are there analogous relationships? - -## API Reference - -```@docs -BradfordHillCriteria -assess_causality -strength_of_evidence -``` diff --git a/packages/Causals.jl/docs/src/causal_dag.adoc b/packages/Causals.jl/docs/src/causal_dag.adoc new file mode 100644 index 000000000..19f8de783 --- /dev/null +++ b/packages/Causals.jl/docs/src/causal_dag.adoc @@ -0,0 +1,28 @@ +== Causal Directed Acyclic Graphs + +The CausalDAG module provides tools for representing and reasoning about +causal relationships using directed acyclic graphs. + +=== Key Concepts + +* *DAG*: Directed acyclic graph representing causal structure +* *D-Separation*: Conditional independence criterion in DAGs +* *Backdoor Criterion*: Conditions for identifying causal effects +* *Frontdoor Criterion*: Alternative identification strategy +* *Markov Blanket*: Set of variables that render a node conditionally +independent + +=== API Reference + +[source,@docs] +---- +CausalGraph +add_edge! +remove_edge! +d_separation +ancestors +descendants +backdoor_criterion +frontdoor_criterion +markov_blanket +---- diff --git a/packages/Causals.jl/docs/src/causal_dag.md b/packages/Causals.jl/docs/src/causal_dag.md deleted file mode 100644 index 8636e257a..000000000 --- a/packages/Causals.jl/docs/src/causal_dag.md +++ /dev/null @@ -1,25 +0,0 @@ -# Causal Directed Acyclic Graphs - -The CausalDAG module provides tools for representing and reasoning about causal relationships using directed acyclic graphs. - -## Key Concepts - -- **DAG**: Directed acyclic graph representing causal structure -- **D-Separation**: Conditional independence criterion in DAGs -- **Backdoor Criterion**: Conditions for identifying causal effects -- **Frontdoor Criterion**: Alternative identification strategy -- **Markov Blanket**: Set of variables that render a node conditionally independent - -## API Reference - -```@docs -CausalGraph -add_edge! -remove_edge! -d_separation -ancestors -descendants -backdoor_criterion -frontdoor_criterion -markov_blanket -``` diff --git a/packages/Causals.jl/docs/src/counterfactuals.adoc b/packages/Causals.jl/docs/src/counterfactuals.adoc new file mode 100644 index 000000000..3d02c228c --- /dev/null +++ b/packages/Causals.jl/docs/src/counterfactuals.adoc @@ -0,0 +1,29 @@ +== Counterfactual Reasoning + +The Counterfactuals module provides tools for counterfactual reasoning +and causal responsibility. + +=== Key Concepts + +* *Counterfactual*: "`What would have happened if…?`" questions +* *Structural Causal Model (SCM)*: Equations defining how variables are +generated +* *Three-Step Process*: Abduction (infer noise), Action (intervene), +Prediction (compute counterfactual) +* *Probability of Necessity (PN)*: Was treatment necessary for outcome? +* *Probability of Sufficiency (PS)*: Would treatment be sufficient for +outcome? +* *Twin Network*: Graph representing both factual and counterfactual +worlds + +=== API Reference + +[source,@docs] +---- +counterfactual +twin_network +probability_of_necessity +probability_of_sufficiency +probability_of_necessity_and_sufficiency +Counterfactual +---- diff --git a/packages/Causals.jl/docs/src/counterfactuals.md b/packages/Causals.jl/docs/src/counterfactuals.md deleted file mode 100644 index bd7340fb1..000000000 --- a/packages/Causals.jl/docs/src/counterfactuals.md +++ /dev/null @@ -1,23 +0,0 @@ -# Counterfactual Reasoning - -The Counterfactuals module provides tools for counterfactual reasoning and causal responsibility. - -## Key Concepts - -- **Counterfactual**: "What would have happened if...?" questions -- **Structural Causal Model (SCM)**: Equations defining how variables are generated -- **Three-Step Process**: Abduction (infer noise), Action (intervene), Prediction (compute counterfactual) -- **Probability of Necessity (PN)**: Was treatment necessary for outcome? -- **Probability of Sufficiency (PS)**: Would treatment be sufficient for outcome? -- **Twin Network**: Graph representing both factual and counterfactual worlds - -## API Reference - -```@docs -counterfactual -twin_network -probability_of_necessity -probability_of_sufficiency -probability_of_necessity_and_sufficiency -Counterfactual -``` diff --git a/packages/Causals.jl/docs/src/dempster_shafer.adoc b/packages/Causals.jl/docs/src/dempster_shafer.adoc new file mode 100644 index 000000000..1134171c8 --- /dev/null +++ b/packages/Causals.jl/docs/src/dempster_shafer.adoc @@ -0,0 +1,24 @@ +== Dempster-Shafer Theory + +The Dempster-Shafer module provides evidence combination and belief +functions for reasoning under uncertainty. + +=== Key Concepts + +* *Frame of Discernment*: Set of mutually exclusive hypotheses +* *Mass Assignment*: Probability mass distributed over subsets of +hypotheses +* *Belief Function*: Lower probability bound for a proposition +* *Plausibility Function*: Upper probability bound for a proposition +* *Dempster’s Rule*: Combines evidence from independent sources + +=== API Reference + +[source,@docs] +---- +MassAssignment +belief +plausibility +combine_dempster +pignistic_transform +---- diff --git a/packages/Causals.jl/docs/src/dempster_shafer.md b/packages/Causals.jl/docs/src/dempster_shafer.md deleted file mode 100644 index f6686f499..000000000 --- a/packages/Causals.jl/docs/src/dempster_shafer.md +++ /dev/null @@ -1,21 +0,0 @@ -# Dempster-Shafer Theory - -The Dempster-Shafer module provides evidence combination and belief functions for reasoning under uncertainty. - -## Key Concepts - -- **Frame of Discernment**: Set of mutually exclusive hypotheses -- **Mass Assignment**: Probability mass distributed over subsets of hypotheses -- **Belief Function**: Lower probability bound for a proposition -- **Plausibility Function**: Upper probability bound for a proposition -- **Dempster's Rule**: Combines evidence from independent sources - -## API Reference - -```@docs -MassAssignment -belief -plausibility -combine_dempster -pignistic_transform -``` diff --git a/packages/Causals.jl/docs/src/do_calculus.adoc b/packages/Causals.jl/docs/src/do_calculus.adoc new file mode 100644 index 000000000..477792c44 --- /dev/null +++ b/packages/Causals.jl/docs/src/do_calculus.adoc @@ -0,0 +1,27 @@ +== Do-Calculus and Interventions + +The DoCalculus module provides Pearl’s do-calculus for reasoning about +causal interventions. + +=== Key Concepts + +* *Do-Operator*: do(X=x) represents setting X to value x (intervention) +* *Interventional Query*: P(Y | do(X)) differs from observational P(Y | +X) +* *Effect Identification*: Determining if causal effect can be computed +from observational data +* *Adjustment Formula*: Computing P(Y | do(X)) using backdoor adjustment +* *Do-Calculus Rules*: Three rules for simplifying interventional +queries + +=== API Reference + +[source,@docs] +---- +do_intervention +identify_effect +adjustment_formula +confounding_adjustment +do_calculus_rules +Query +---- diff --git a/packages/Causals.jl/docs/src/do_calculus.md b/packages/Causals.jl/docs/src/do_calculus.md deleted file mode 100644 index e4a708d87..000000000 --- a/packages/Causals.jl/docs/src/do_calculus.md +++ /dev/null @@ -1,22 +0,0 @@ -# Do-Calculus and Interventions - -The DoCalculus module provides Pearl's do-calculus for reasoning about causal interventions. - -## Key Concepts - -- **Do-Operator**: do(X=x) represents setting X to value x (intervention) -- **Interventional Query**: P(Y | do(X)) differs from observational P(Y | X) -- **Effect Identification**: Determining if causal effect can be computed from observational data -- **Adjustment Formula**: Computing P(Y | do(X)) using backdoor adjustment -- **Do-Calculus Rules**: Three rules for simplifying interventional queries - -## API Reference - -```@docs -do_intervention -identify_effect -adjustment_formula -confounding_adjustment -do_calculus_rules -Query -``` diff --git a/packages/Causals.jl/docs/src/examples.adoc b/packages/Causals.jl/docs/src/examples.adoc new file mode 100644 index 000000000..ed12569cd --- /dev/null +++ b/packages/Causals.jl/docs/src/examples.adoc @@ -0,0 +1,48 @@ +== Examples + +This page provides examples demonstrating the functionality of +Causals.jl. + +=== Basic Usage + +The `+examples/01_basic_usage.jl+` file demonstrates: + +* *Dempster-Shafer Evidence Combination*: Combining evidence from +multiple sources about medical diagnoses +* *Bradford Hill Causal Assessment*: Assessing the causal relationship +between smoking and lung cancer +* *Causal DAG Operations*: Building causal graphs, testing d-separation, +checking backdoor criterion + +To run the basic usage example: + +[source,julia] +---- +include("examples/01_basic_usage.jl") +---- + +=== Advanced Analysis + +The `+examples/02_advanced_analysis.jl+` file demonstrates: + +* *Granger Causality*: Testing whether one time series helps predict +another +* *Propensity Score Matching*: Estimating treatment effects from +observational data with confounding +* *Do-Calculus and Interventions*: Identifying causal effects and using +adjustment formulas +* *Counterfactual Reasoning*: Computing "`what if`" scenarios using +structural causal models + +To run the advanced analysis example: + +[source,julia] +---- +include("examples/02_advanced_analysis.jl") +---- + +=== Example Datasets + +The examples use synthetic datasets to demonstrate the methods. For +real-world applications, you can replace these with your own data +following the same structure. diff --git a/packages/Causals.jl/docs/src/examples.md b/packages/Causals.jl/docs/src/examples.md deleted file mode 100644 index aa6629958..000000000 --- a/packages/Causals.jl/docs/src/examples.md +++ /dev/null @@ -1,36 +0,0 @@ -# Examples - -This page provides examples demonstrating the functionality of Causals.jl. - -## Basic Usage - -The `examples/01_basic_usage.jl` file demonstrates: - -- **Dempster-Shafer Evidence Combination**: Combining evidence from multiple sources about medical diagnoses -- **Bradford Hill Causal Assessment**: Assessing the causal relationship between smoking and lung cancer -- **Causal DAG Operations**: Building causal graphs, testing d-separation, checking backdoor criterion - -To run the basic usage example: - -```julia -include("examples/01_basic_usage.jl") -``` - -## Advanced Analysis - -The `examples/02_advanced_analysis.jl` file demonstrates: - -- **Granger Causality**: Testing whether one time series helps predict another -- **Propensity Score Matching**: Estimating treatment effects from observational data with confounding -- **Do-Calculus and Interventions**: Identifying causal effects and using adjustment formulas -- **Counterfactual Reasoning**: Computing "what if" scenarios using structural causal models - -To run the advanced analysis example: - -```julia -include("examples/02_advanced_analysis.jl") -``` - -## Example Datasets - -The examples use synthetic datasets to demonstrate the methods. For real-world applications, you can replace these with your own data following the same structure. diff --git a/packages/Causals.jl/docs/src/granger.adoc b/packages/Causals.jl/docs/src/granger.adoc new file mode 100644 index 000000000..4a5b7a4ee --- /dev/null +++ b/packages/Causals.jl/docs/src/granger.adoc @@ -0,0 +1,24 @@ +== Granger Causality + +The Granger module provides Granger causality tests for time series +analysis. + +=== Key Concepts + +* *Granger Causality*: X Granger-causes Y if past values of X help +predict Y beyond Y’s own past +* *F-Test*: Statistical test comparing restricted and unrestricted VAR +models +* *Optimal Lag*: Number of lags that minimizes information criterion +(AIC) +* *Bidirectional Causality*: Testing causality in both directions + +=== API Reference + +[source,@docs] +---- +granger_test +granger_causality +optimal_lag +bidirectional_granger +---- diff --git a/packages/Causals.jl/docs/src/granger.md b/packages/Causals.jl/docs/src/granger.md deleted file mode 100644 index 6608e062a..000000000 --- a/packages/Causals.jl/docs/src/granger.md +++ /dev/null @@ -1,19 +0,0 @@ -# Granger Causality - -The Granger module provides Granger causality tests for time series analysis. - -## Key Concepts - -- **Granger Causality**: X Granger-causes Y if past values of X help predict Y beyond Y's own past -- **F-Test**: Statistical test comparing restricted and unrestricted VAR models -- **Optimal Lag**: Number of lags that minimizes information criterion (AIC) -- **Bidirectional Causality**: Testing causality in both directions - -## API Reference - -```@docs -granger_test -granger_causality -optimal_lag -bidirectional_granger -``` diff --git a/packages/Causals.jl/docs/src/index.md b/packages/Causals.jl/docs/src/index.adoc similarity index 60% rename from packages/Causals.jl/docs/src/index.md rename to packages/Causals.jl/docs/src/index.adoc index 0d7aab016..48ac40ce0 100644 --- a/packages/Causals.jl/docs/src/index.md +++ b/packages/Causals.jl/docs/src/index.adoc @@ -1,40 +1,40 @@ -# Causals.jl +== Causals.jl Comprehensive causal inference toolkit for Julia. -## Overview +=== Overview Causals.jl unifies multiple approaches to causal reasoning: -- **Dempster-Shafer theory** - Combine uncertain expert opinions -- **Bradford Hill criteria** - Assess causality in observational studies -- **Causal DAGs** - Graphical models and identification -- **Granger causality** - Time series causal analysis -- **Propensity scores** - Observational study adjustment -- **Do-calculus** - Pearl's intervention framework -- **Counterfactuals** - "What if" reasoning +* *Dempster-Shafer theory* - Combine uncertain expert opinions +* *Bradford Hill criteria* - Assess causality in observational studies +* *Causal DAGs* - Graphical models and identification +* *Granger causality* - Time series causal analysis +* *Propensity scores* - Observational study adjustment +* *Do-calculus* - Pearl’s intervention framework +* *Counterfactuals* - "`What if`" reasoning -## Why Causals.jl? +=== Why Causals.jl? Existing Julia causal packages are fragmented. Causals.jl provides: -✓ Complete coverage of major causal methods -✓ Production-quality implementations -✓ Comprehensive documentation -✓ Active maintenance +✓ Complete coverage of major causal methods ✓ Production-quality +implementations ✓ Comprehensive documentation ✓ Active maintenance -## Installation +=== Installation -```julia +[source,julia] +---- using Pkg Pkg.add(url="https://github.com/hyperpolymath/Causals.jl") -``` +---- -## Quick Start +=== Quick Start -### Combining Expert Evidence +==== Combining Expert Evidence -```julia +[source,julia] +---- using Causals # Two experts provide evidence about hypotheses @@ -55,22 +55,24 @@ combined = combine_dempster(expert1, expert2) # Get belief interval lower, upper = uncertainty(combined, Set([:A])) -``` +---- -### Granger Causality +==== Granger Causality -```julia +[source,julia] +---- # Test if X Granger-causes Y causes, F_stat, p_value, lag = granger_test(x_series, y_series) if causes println("X Granger-causes Y with lag $lag") end -``` +---- -### Causal DAG Analysis +==== Causal DAG Analysis -```julia +[source,julia] +---- # Build causal graph g = CausalGraph([:X, :Y, :Z]) add_edge!(g, :Z, :X) # Z → X @@ -79,16 +81,17 @@ add_edge!(g, :X, :Y) # X → Y # Check if Z blocks backdoor path @assert backdoor_criterion(g, :X, :Y, Set([:Z])) -``` +---- -## Modules +=== Modules -```@contents +[source,@contents] +---- Pages = ["dempster_shafer.md", "bradford_hill.md", "causal_dag.md", "granger.md", "propensity.md", "do_calculus.md", "counterfactuals.md"] Depth = 1 -``` +---- -## License +=== License MPL-2.0 (MPL-2.0 compatible) diff --git a/packages/Causals.jl/docs/src/propensity.adoc b/packages/Causals.jl/docs/src/propensity.adoc new file mode 100644 index 000000000..fbd2e47ca --- /dev/null +++ b/packages/Causals.jl/docs/src/propensity.adoc @@ -0,0 +1,28 @@ +== Propensity Score Methods + +The PropensityScore module provides methods for causal inference from +observational data using propensity scores. + +=== Key Concepts + +* *Propensity Score*: P(treatment=1 | covariates) - probability of +receiving treatment +* *Matching*: Pair treated and control units with similar propensity +scores +* *Inverse Probability Weighting (IPW)*: Weight observations by inverse +propensity +* *Stratification*: Group by propensity score and estimate effects +within strata +* *Doubly Robust*: Consistent if either propensity or outcome model is +correct + +=== API Reference + +[source,@docs] +---- +propensity_score +matching +inverse_probability_weighting +stratification +doubly_robust +---- diff --git a/packages/Causals.jl/docs/src/propensity.md b/packages/Causals.jl/docs/src/propensity.md deleted file mode 100644 index 7ffa5fad2..000000000 --- a/packages/Causals.jl/docs/src/propensity.md +++ /dev/null @@ -1,21 +0,0 @@ -# Propensity Score Methods - -The PropensityScore module provides methods for causal inference from observational data using propensity scores. - -## Key Concepts - -- **Propensity Score**: P(treatment=1 | covariates) - probability of receiving treatment -- **Matching**: Pair treated and control units with similar propensity scores -- **Inverse Probability Weighting (IPW)**: Weight observations by inverse propensity -- **Stratification**: Group by propensity score and estimate effects within strata -- **Doubly Robust**: Consistent if either propensity or outcome model is correct - -## API Reference - -```@docs -propensity_score -matching -inverse_probability_weighting -stratification -doubly_robust -``` diff --git a/packages/Axiology.jl/ABI-FFI-README.md b/packages/Cladistics.jl/ABI-FFI-README.adoc similarity index 74% rename from packages/Axiology.jl/ABI-FFI-README.md rename to packages/Cladistics.jl/ABI-FFI-README.adoc index 08d35da64..8e5244189 100644 --- a/packages/Axiology.jl/ABI-FFI-README.md +++ b/packages/Cladistics.jl/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/Cladistics.jl/CODE_OF_CONDUCT.adoc b/packages/Cladistics.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/Cladistics.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Cladistics.jl/CODE_OF_CONDUCT.md b/packages/Cladistics.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/Cladistics.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Cladistics.jl/CONTRIBUTING.adoc b/packages/Cladistics.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/Cladistics.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Cladistics.jl/CONTRIBUTING.md b/packages/Cladistics.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/Cladistics.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Cladistics.jl/README.md b/packages/Cladistics.jl/README.adoc similarity index 58% rename from packages/Cladistics.jl/README.md rename to packages/Cladistics.jl/README.adoc index 07957db94..377120735 100644 --- a/packages/Cladistics.jl/README.md +++ b/packages/Cladistics.jl/README.adoc @@ -1,60 +1,81 @@ -# Cladistics.jl +== Cladistics.jl -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-75%25-yellow)](TOPOLOGY.md) +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-75%25-yellow[Completion +Status]] -[![License](https://img.shields.io/badge/license-PMPL--1.0--or--later-blue.svg)](LICENSE) -[![Julia](https://img.shields.io/badge/julia-1.6+-purple.svg)](https://julialang.org) +link:LICENSE[image:https://img.shields.io/badge/license-PMPL--1.0--or--later-blue.svg[License]] +https://julialang.org[image:https://img.shields.io/badge/julia-1.6+-purple.svg[Julia]] -A Julia package for phylogenetic analysis and cladistics - the study of evolutionary relationships among organisms. +A Julia package for phylogenetic analysis and cladistics - the study of +evolutionary relationships among organisms. -## Overview +=== Overview -Cladistics is a method of biological classification that groups organisms based on their evolutionary ancestry and shared derived characteristics (synapomorphies). This package provides computational tools for reconstructing and analyzing phylogenetic trees from molecular sequence data and morphological characters. +Cladistics is a method of biological classification that groups +organisms based on their evolutionary ancestry and shared derived +characteristics (synapomorphies). This package provides computational +tools for reconstructing and analyzing phylogenetic trees from molecular +sequence data and morphological characters. -## What is Cladistics? +=== What is Cladistics? -Cladistics revolutionized biological classification by emphasizing evolutionary relationships over superficial similarities. Key concepts: +Cladistics revolutionized biological classification by emphasizing +evolutionary relationships over superficial similarities. Key concepts: -- **Clade**: A monophyletic group consisting of an ancestor and all its descendants -- **Synapomorphy**: A shared derived characteristic that defines a clade -- **Phylogenetic Tree**: A branching diagram showing evolutionary relationships -- **Parsimony**: The principle that the simplest evolutionary explanation (fewest changes) is preferred -- **Bootstrap Analysis**: Statistical method to assess confidence in tree topology +* *Clade*: A monophyletic group consisting of an ancestor and all its +descendants +* *Synapomorphy*: A shared derived characteristic that defines a clade +* *Phylogenetic Tree*: A branching diagram showing evolutionary +relationships +* *Parsimony*: The principle that the simplest evolutionary explanation +(fewest changes) is preferred +* *Bootstrap Analysis*: Statistical method to assess confidence in tree +topology -## Features +=== Features -### Distance-Based Methods -- **Multiple Distance Metrics**: - - Hamming distance (simple count of differences) - - p-distance (proportion of differences) - - Jukes-Cantor 1969 (corrects for multiple substitutions) - - Kimura 2-parameter (distinguishes transitions vs transversions) -- **UPGMA**: Unweighted Pair Group Method with Arithmetic Mean (assumes molecular clock) -- **Neighbor-Joining**: Does not assume molecular clock, handles rate variation +==== Distance-Based Methods -### Character-Based Methods -- **Maximum Parsimony**: Find trees requiring fewest evolutionary changes -- **Fitch Algorithm**: Efficient parsimony score calculation -- **Parsimony-Informative Sites**: Identify characters useful for phylogenetic inference +* *Multiple Distance Metrics*: +** Hamming distance (simple count of differences) +** p-distance (proportion of differences) +** Jukes-Cantor 1969 (corrects for multiple substitutions) +** Kimura 2-parameter (distinguishes transitions vs transversions) +* *UPGMA*: Unweighted Pair Group Method with Arithmetic Mean (assumes +molecular clock) +* *Neighbor-Joining*: Does not assume molecular clock, handles rate +variation -### Tree Analysis -- **Bootstrap Support**: Assess confidence in tree topology (1000+ replicates) -- **Clade Identification**: Extract well-supported monophyletic groups -- **Robinson-Foulds Distance**: Compare tree topologies quantitatively -- **Tree Rooting**: Root unrooted trees using outgroup taxa -- **Newick Format**: Export trees in standard phylogenetic format +==== Character-Based Methods -## Installation +* *Maximum Parsimony*: Find trees requiring fewest evolutionary changes +* *Fitch Algorithm*: Efficient parsimony score calculation +* *Parsimony-Informative Sites*: Identify characters useful for +phylogenetic inference -```julia +==== Tree Analysis + +* *Bootstrap Support*: Assess confidence in tree topology (1000+ +replicates) +* *Clade Identification*: Extract well-supported monophyletic groups +* *Robinson-Foulds Distance*: Compare tree topologies quantitatively +* *Tree Rooting*: Root unrooted trees using outgroup taxa +* *Newick Format*: Export trees in standard phylogenetic format + +=== Installation + +[source,julia] +---- using Pkg Pkg.add("Cladistics") -``` +---- -## Quick Start +=== Quick Start -```julia +[source,julia] +---- using Cladistics using Plots @@ -98,13 +119,14 @@ println("\nWell-supported clades (>95%):") for clade in clades println(" ", clade) end -``` +---- -## Distance Methods Comparison +=== Distance Methods Comparison Different evolutionary models for different scenarios: -```julia +[source,julia] +---- using Cladistics sequences = ["ATCG", "ATCG", "TTCG", "TTCC"] @@ -125,13 +147,14 @@ println("Hamming distance [1,3]: ", hamming[1,3]) println("p-distance [1,3]: ", p_dist[1,3]) println("Jukes-Cantor [1,3]: ", jc69[1,3]) println("Kimura 2P [1,3]: ", k2p[1,3]) -``` +---- -## Tree Construction Methods +=== Tree Construction Methods -### UPGMA: Simple but assumes molecular clock +==== UPGMA: Simple but assumes molecular clock -```julia +[source,julia] +---- using Cladistics # UPGMA assumes constant evolutionary rate (molecular clock) @@ -151,11 +174,12 @@ tree = upgma(dmat, taxa_names=["Human", "Chimp", "Gorilla"]) # - Ancient divergences # - Variable evolutionary rates # - Rapid radiations -``` +---- -### Neighbor-Joining: No molecular clock assumption +==== Neighbor-Joining: No molecular clock assumption -```julia +[source,julia] +---- using Cladistics # NJ handles rate variation across lineages @@ -173,13 +197,14 @@ tree = neighbor_joining(dmat, taxa_names=["A", "B", "C", "D"]) # - When molecular clock violated # Produces minimum evolution tree -``` +---- -## Bootstrap Analysis +=== Bootstrap Analysis Assess confidence in your phylogenetic tree: -```julia +[source,julia] +---- using Cladistics using Random @@ -217,13 +242,14 @@ for (clade, value) in sort(collect(support), by=x->x[2], rev=true) println("Clade $taxa: $percent% ($confidence)") end -``` +---- -## Maximum Parsimony +=== Maximum Parsimony Find trees requiring the fewest evolutionary changes: -```julia +[source,julia] +---- using Cladistics # Aligned DNA sequences @@ -251,11 +277,12 @@ score = calculate_parsimony_score(tree, char_matrix) println("Parsimony score: $score changes") # Lower scores = more parsimonious (preferred) -``` +---- -## Real-World Example: Primate Phylogeny +=== Real-World Example: Primate Phylogeny -```julia +[source,julia] +---- using Cladistics # Partial mitochondrial cytochrome b sequences (simplified) @@ -286,11 +313,12 @@ newick = tree_to_newick(rooted_tree) println("Newick format: $newick") # Can import into FigTree, iTOL, or other phylogenetic viewers -``` +---- -## Character Evolution Example +=== Character Evolution Example -```julia +[source,julia] +---- using Cladistics # Morphological character matrix @@ -317,11 +345,12 @@ parsimony_score = calculate_parsimony_score(tree, char_matrix) println("Minimum evolutionary changes: $parsimony_score") # Low score = good fit between characters and tree topology -``` +---- -## Comparing Alternative Hypotheses +=== Comparing Alternative Hypotheses -```julia +[source,julia] +---- using Cladistics sequences = ["ATCG", "ATCG", "TTCG", "GTCC"] @@ -351,78 +380,103 @@ println("UPGMA parsimony score: $score1") println("NJ parsimony score: $score2") # Prefer tree with lower parsimony score (fewer changes) -``` - -## Key Concepts Explained - -### Molecular Clock -- **Assumption**: Evolutionary rate is constant across lineages -- **When valid**: Recent species, similar generation times -- **Methods**: UPGMA assumes molecular clock -- **When violated**: Use Neighbor-Joining instead - -### Bootstrap Support -- **Purpose**: Assess confidence in tree branches -- **Method**: Resample alignment columns with replacement -- **Interpretation**: - - >95%: Publish with confidence - - 70-95%: Mention uncertainty - - <70%: Weak support, collect more data - -### Parsimony vs Distance -- **Parsimony**: Find tree requiring fewest character changes - - Good: Morphological data, theoretical clarity - - Bad: Computationally expensive (NP-hard) -- **Distance**: Build tree from pairwise distances - - Good: Fast, scales to large datasets - - Bad: Information loss from pairwise comparisons - -## References - -### Classic Papers -- Felsenstein, J. (1985). "Confidence limits on phylogenies: An approach using the bootstrap." *Evolution*, 39(4), 783-791. -- Saitou, N., & Nei, M. (1987). "The neighbor-joining method: A new method for reconstructing phylogenetic trees." *Molecular Biology and Evolution*, 4(4), 406-425. -- Fitch, W. M. (1971). "Toward defining the course of evolution: Minimum change for a specific tree topology." *Systematic Zoology*, 20(4), 406-416. - -### Textbooks -- Felsenstein, J. (2004). *Inferring Phylogenies*. Sinauer Associates. -- Lemey, P., Salemi, M., & Vandamme, A. M. (2009). *The Phylogenetic Handbook: A Practical Approach to Phylogenetic Analysis and Hypothesis Testing*. Cambridge University Press. -- Hall, B. G. (2011). *Phylogenetic Trees Made Easy: A How-To Manual*. Sinauer Associates. - -### Evolutionary Models -- Jukes, T. H., & Cantor, C. R. (1969). "Evolution of protein molecules." In *Mammalian Protein Metabolism*, pp. 21-132. -- Kimura, M. (1980). "A simple method for estimating evolutionary rates of base substitutions." *Journal of Molecular Evolution*, 16(2), 111-120. - -## Citation +---- + +=== Key Concepts Explained + +==== Molecular Clock + +* *Assumption*: Evolutionary rate is constant across lineages +* *When valid*: Recent species, similar generation times +* *Methods*: UPGMA assumes molecular clock +* *When violated*: Use Neighbor-Joining instead + +==== Bootstrap Support + +* *Purpose*: Assess confidence in tree branches +* *Method*: Resample alignment columns with replacement +* *Interpretation*: +** {blank} ++ +____ +95%: Publish with confidence +____ +** 70-95%: Mention uncertainty +** <70%: Weak support, collect more data + +==== Parsimony vs Distance + +* *Parsimony*: Find tree requiring fewest character changes +** Good: Morphological data, theoretical clarity +** Bad: Computationally expensive (NP-hard) +* *Distance*: Build tree from pairwise distances +** Good: Fast, scales to large datasets +** Bad: Information loss from pairwise comparisons + +=== References + +==== Classic Papers + +* Felsenstein, J. (1985). "`Confidence limits on phylogenies: An +approach using the bootstrap.`" _Evolution_, 39(4), 783-791. +* Saitou, N., & Nei, M. (1987). "`The neighbor-joining method: A new +method for reconstructing phylogenetic trees.`" _Molecular Biology and +Evolution_, 4(4), 406-425. +* Fitch, W. M. (1971). "`Toward defining the course of evolution: +Minimum change for a specific tree topology.`" _Systematic Zoology_, +20(4), 406-416. + +==== Textbooks + +* Felsenstein, J. (2004). _Inferring Phylogenies_. Sinauer Associates. +* Lemey, P., Salemi, M., & Vandamme, A. M. (2009). _The Phylogenetic +Handbook: A Practical Approach to Phylogenetic Analysis and Hypothesis +Testing_. Cambridge University Press. +* Hall, B. G. (2011). _Phylogenetic Trees Made Easy: A How-To Manual_. +Sinauer Associates. + +==== Evolutionary Models + +* Jukes, T. H., & Cantor, C. R. (1969). "`Evolution of protein +molecules.`" In _Mammalian Protein Metabolism_, pp. 21-132. +* Kimura, M. (1980). "`A simple method for estimating evolutionary rates +of base substitutions.`" _Journal of Molecular Evolution_, 16(2), +111-120. + +=== Citation If you use this package in research, please cite: -```bibtex +[source,bibtex] +---- @software{cladistics_jl, author = {Jewell, Jonathan D.A.}, title = {Cladistics.jl: Phylogenetic Analysis in Julia}, year = {2026}, url = {https://github.com/hyperpolymath/Cladistics.jl} } -``` +---- -## Related Projects +=== Related Projects -- [BioJulia](https://github.com/BioJulia) - Broader bioinformatics ecosystem -- [PhyloNetworks.jl](https://github.com/crsl4/PhyloNetworks.jl) - Phylogenetic networks -- [Phylo.jl](https://github.com/richardreeve/Phylo.jl) - Alternative phylogenetics package +* https://github.com/BioJulia[BioJulia] - Broader bioinformatics +ecosystem +* https://github.com/crsl4/PhyloNetworks.jl[PhyloNetworks.jl] - +Phylogenetic networks +* https://github.com/richardreeve/Phylo.jl[Phylo.jl] - Alternative +phylogenetics package -## External Tools +=== External Tools -Visualize Newick trees with: -- [FigTree](http://tree.bio.ed.ac.uk/software/figtree/) -- [iTOL](https://itol.embl.de/) -- [ETE Toolkit](http://etetoolkit.org/) +Visualize Newick trees with: - +http://tree.bio.ed.ac.uk/software/figtree/[FigTree] - +https://itol.embl.de/[iTOL] - http://etetoolkit.org/[ETE Toolkit] -## Contributing +=== Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +See CONTRIBUTING.md for guidelines. -## License +=== License -This project is licensed under the Palimpsest License (MPL-2.0). See [LICENSE](LICENSE) for details. +This project is licensed under the Palimpsest License (MPL-2.0). See +LICENSE for details. diff --git a/packages/Cladistics.jl/SECURITY.adoc b/packages/Cladistics.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/Cladistics.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Cladistics.jl/SECURITY.md b/packages/Cladistics.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/Cladistics.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Cladistics.jl/SONNET-TASKS.adoc b/packages/Cladistics.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..1d581a812 --- /dev/null +++ b/packages/Cladistics.jl/SONNET-TASKS.adoc @@ -0,0 +1,718 @@ +== SONNET-TASKS.md – Cladistics.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 55% +____ + +The package has a solid single-file implementation +(`+src/Cladistics.jl+`) with working distance matrix calculations, +UPGMA, Neighbor-Joining, bootstrap support, clade identification, +Robinson-Foulds distance, and Newick export. However, it contains three +critical bugs that will cause runtime crashes, one fully stubbed +function (`+root_tree+`), one exported symbol with no implementation +(`+maximum_parsimony+`), and extensive uncustomized RSR template +boilerplate across all metadata files. The Project.toml UUID is +fabricated (not generated by Julia’s `+Pkg.generate+`). + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update `+.machines_readable/6scm/STATE.scm+` with honest completion +percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/Cladistics.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix `+fitch_score+` inconsistent return type (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl+` lines +474-492 + +*Problem:* `+fitch_score+` has an inconsistent return type that will +crash at runtime. + +* Line 478: Terminal nodes return `+Set{Char}+` (a single value). +* Line 488: Internal nodes return `+(Set{Char}, Int)+` (a tuple). +* Line 490: Internal nodes return `+(Set{Char}, Int)+` (a tuple). + +When `+calculate_parsimony_score+` (line 467) calls `+fitch_score+`, it +does `+score = fitch_score(...)+` and then `+total_score += score+`. But +`+score+` will be either a `+Set{Char}+` or a `+Tuple{Set{Char}, Int}+`, +neither of which can be added to an `+Int+`. + +Additionally, line 482 calls `+fitch_score+` recursively on children and +stores results in `+child_sets+`. When children are leaf nodes, +`+child_sets+` contains `+Set{Char}+` values. When children are internal +nodes, `+child_sets+` contains `+(Set{Char}, Int)+` tuples. Then line +485 calls `+reduce(intersect, child_sets)+` which will fail because you +cannot `+intersect+` tuples. + +*What to do:* + +[arabic] +. Rewrite `+fitch_score+` to return a `+Tuple{Set{Char}, Int}+` +consistently. Terminal nodes should return +`+(Set([char_column[idx]]), 0)+`. +. Internal nodes must unpack the tuple from each child: extract the +`+Set{Char}+` part for the intersection/union logic, and sum the `+Int+` +parts for the cumulative score. +. The function should return +`+(result_set, child_score_sum + local_cost)+` where `+local_cost+` is 0 +if intersection is non-empty, 1 if union was needed. +. Update `+calculate_parsimony_score+` (lines 462-472) to unpack the +tuple: +`+(_, score) = fitch_score(tree.root, char_matrix[:, j], tree.taxa)+` +and then `+total_score += score+`. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") +using Cladistics + +seqs = ["ATCG", "ATCG", "TTCG", "TTCC"] +dmat = distance_matrix(seqs, method=:hamming) +tree = upgma(dmat, taxa_names=["A", "B", "C", "D"]) +cm = character_state_matrix(seqs) +score = calculate_parsimony_score(tree, cm) +@assert score isa Int "Score must be an Int, got $(typeof(score))" +@assert score >= 0 "Score must be non-negative" +@assert score <= 8 "Score suspiciously high for 4 taxa, 4 chars" +println("TASK 1 PASS: parsimony score = $score") +---- + +''''' + +=== TASK 2: Fix Kimura 2-parameter operator precedence bug (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl+` line 187 + +*Problem:* Line 187 reads: + +[source,julia] +---- +(1.0 - 2P - Q) <= 0 || (1.0 - 2Q) <= 0 && return Inf +---- + +In Julia, `+&&+` binds tighter than `+||+`. So this parses as: + +[source,julia] +---- +(1.0 - 2P - Q) <= 0 || ((1.0 - 2Q) <= 0 && return Inf) +---- + +This means: - If `+(1.0 - 2P - Q) <= 0+` is true but `+(1.0 - 2Q) > 0+`, +the function does NOT return `+Inf+`. It continues to line 189 and +computes `+log+` of a non-positive number, producing `+NaN+` or throwing +a `+DomainError+`. - The fix must ensure that if EITHER condition is +non-positive, `+Inf+` is returned. + +Additionally, `+2P+` and `+2Q+` in Julia are parsed as `+2 * P+` and +`+2 * Q+` only because Julia supports coefficient syntax, but this is +fragile and unconventional for a scientific package. Use explicit +`+2.0 * P+` and `+2.0 * Q+` for clarity. + +*What to do:* + +[arabic] +. Replace line 187 with: ++ +[source,julia] +---- +if (1.0 - 2.0 * P - Q) <= 0.0 || (1.0 - 2.0 * Q) <= 0.0 + return Inf +end +---- +. Also update line 189 to use explicit multiplication for consistency: ++ +[source,julia] +---- +return -0.5 * log((1.0 - 2.0 * P - Q) * sqrt(1.0 - 2.0 * Q)) +---- + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") +using Cladistics + +# Case where (1-2P-Q) <= 0 but (1-2Q) > 0 -- would have been a bug +# P=0.4, Q=0.1 => 1-2(0.4)-0.1 = 0.1 > 0, OK +# P=0.45, Q=0.1 => 1-2(0.45)-0.1 = 0.0 <= 0, should be Inf +# Use sequences that produce high transition ratio +seqs_saturated = ["AAAA", "GGGG"] # All transitions A<->G +dmat = distance_matrix(seqs_saturated, method=:k2p) +@assert isinf(dmat[1,2]) "Saturated transitions must give Inf, got $(dmat[1,2])" + +# Normal case still works +seqs_normal = ["ATCG", "GTCG"] # One transition +dmat_normal = distance_matrix(seqs_normal, method=:k2p) +@assert isfinite(dmat_normal[1,2]) "Normal case must be finite" +@assert dmat_normal[1,2] > 0 "Normal case must be positive" +println("TASK 2 PASS: K2P operator precedence fixed") +---- + +''''' + +=== TASK 3: Implement `+root_tree+` (stub removal) (HIGH) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl+` lines +665-673 + +*Problem:* `+root_tree+` is exported and documented but is a stub. Lines +670-672: + +[source,julia] +---- +# Implementation would reroot the tree structure +# Simplified version returns the original tree +return tree +---- + +It finds the outgroup node but then ignores it and returns the original +tree unchanged. This is silently wrong – callers expect a rerooted tree +but get the original. + +*What to do:* + +[arabic] +. Implement proper midpoint rerooting on the outgroup branch. The +algorithm: +[loweralpha] +.. Find the outgroup leaf node by name. +.. Get its parent (the node it is attached to). +.. Create a new root node at the midpoint of the outgroup’s branch. +.. One child of the new root is the outgroup (with half its original +branch length). +.. The other child is the rest of the tree (with the other half of the +branch length). +.. Unlink the outgroup from its old parent by removing it from +`+children+`. +.. The old parent becomes the child of the new root on the ingroup side. +.. Fix all `+parent+` references. +. Return a new `+PhylogeneticTree+` with `+method+` preserved from the +input tree. +. Handle edge case: if the outgroup is already a direct child of the +root, just rebalance the branch lengths. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") +using Cladistics + +dmat = [0.0 0.2 0.4 0.5; + 0.2 0.0 0.3 0.4; + 0.4 0.3 0.0 0.2; + 0.5 0.4 0.2 0.0] +tree = neighbor_joining(dmat, taxa_names=["A", "B", "C", "Outgroup"]) +rooted = root_tree(tree, "Outgroup") + +# The rooted tree must NOT be the same object as the input +@assert rooted !== tree || rooted.root !== tree.root "root_tree must not return input unchanged" + +# The outgroup must be a direct child (or grandchild) of the new root +function find_leaf(node, name) + node.name == name && isempty(node.children) && return true + any(c -> find_leaf(c, name), node.children) +end +@assert find_leaf(rooted.root, "Outgroup") "Outgroup must be in rooted tree" + +# All original taxa must still be present +descendants = String[] +function collect_leaves(node) + if isempty(node.children) + push!(descendants, node.name) + else + for c in node.children; collect_leaves(c); end + end +end +collect_leaves(rooted.root) +@assert sort(descendants) == ["A", "B", "C", "Outgroup"] "All taxa must be preserved" + +println("TASK 3 PASS: root_tree properly reroots on outgroup") +---- + +''''' + +=== TASK 4: Implement `+maximum_parsimony+` (exported but missing) (HIGH) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl+` line 57 + +*Problem:* `+maximum_parsimony+` is listed in the `+export+` statement +on line 57 but has no function definition anywhere in the file. Calling +`+maximum_parsimony(...)+` will throw `+UndefVarError+`. + +*What to do:* + +[arabic] +. Add a `+maximum_parsimony+` function that performs a heuristic search +for the most parsimonious tree. Since exhaustive search is NP-hard, +implement a stepwise addition heuristic: +[loweralpha] +.. Start with a tree of the first 3 taxa (only one unrooted topology +exists). +.. For each remaining taxon, try inserting it at every branch of the +current tree. +.. Keep the insertion that gives the lowest parsimony score (using the +now-fixed `+calculate_parsimony_score+`). +.. Return the final tree. +. Signature: +`+maximum_parsimony(sequences::Vector{String}; taxa_names=nothing) -> PhylogeneticTree+` +. Add a proper docstring following the style of the existing functions. +. Set `+method = :parsimony+` on the returned `+PhylogeneticTree+`. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") +using Cladistics + +seqs = ["ATCGATCG", "ATCGATCG", "TTCGTTCG", "TTCCTTCC", "AACGAACG"] +tree = maximum_parsimony(seqs, taxa_names=["A", "B", "C", "D", "E"]) + +@assert tree isa Cladistics.PhylogeneticTree "Must return PhylogeneticTree" +@assert tree.method == :parsimony "Method must be :parsimony" +@assert length(tree.taxa) == 5 "Must have 5 taxa" +@assert !isempty(tree.root.children) "Root must have children" + +# Parsimony score should be computable and reasonable +cm = character_state_matrix(seqs) +score = calculate_parsimony_score(tree, cm) +@assert score isa Int +@assert score >= 0 +println("TASK 4 PASS: maximum_parsimony returns valid tree with score=$score") +---- + +''''' + +=== TASK 5: Generate valid Project.toml UUID (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/Project.toml+` line 2 + +*Problem:* The UUID `+9e3g4f80-5d7c-6f0d-b4e2-3g9f0d1c2e3f+` is invalid. +UUIDs use hexadecimal digits (0-9, a-f) only. This UUID contains `+g+` +characters, which are not valid hex digits. Julia’s package manager will +reject this. + +*What to do:* + +[arabic] +. Generate a valid UUID by running: ++ +[source,julia] +---- +using UUIDs; println(uuid4()) +---- +. Replace the `+uuid+` line in `+Project.toml+` with the generated UUID. +. Do NOT change any other field in `+Project.toml+`. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +toml_text = read("Project.toml", String) +uuid_match = match(r"uuid = \"([^\"]+)\"", toml_text) +uuid_str = uuid_match.captures[1] +@assert all(c -> c in "0123456789abcdef-", uuid_str) "UUID must be valid hex, got: $uuid_str" +@assert length(uuid_str) == 36 "UUID must be 36 chars (with dashes)" +@assert count(==('-'), uuid_str) == 4 "UUID must have 4 dashes" +println("TASK 5 PASS: UUID is valid: $uuid_str") +---- + +''''' + +=== TASK 6: Fix SPDX license headers – replace all AGPL-3.0-or-later with MPL-2.0 (MEDIUM) + +*Files:* All files listed below that still contain +`+AGPL-3.0-or-later+`: - `+.machines_readable/6scm/STATE.scm+` line 1 - +`+.machines_readable/6scm/META.scm+` line 1 - +`+.machines_readable/6scm/ECOSYSTEM.scm+` line 1 - `+.gitignore+` line 1 +- `+.gitattributes+` line 1 - `+ffi/zig/build.zig+` line 2 - +`+ffi/zig/src/main.zig+` line 6 - `+ffi/zig/test/integration_test.zig+` +line 2 - `+examples/SafeDOMExample.res+` line 1 - +`+docs/CITATIONS.adoc+` line 13 + +*Problem:* Per CLAUDE.md, the AGPL-3.0-or-later license has been +replaced by MPL-2.0 for all hyperpolymath original code. These files +still use the old license identifier. + +*What to do:* + +[arabic] +. In every file listed above, replace `+AGPL-3.0-or-later+` with +`+MPL-2.0+`. +. Do not change anything else in these files. +. Verify no other files still contain `+AGPL-3.0-or-later+` (except +`+RSR_OUTLINE.adoc+` which discusses licensing policy historically and +should not be changed). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +for f in readdir(".", join=true) + isfile(f) || continue + endswith(f, ".adoc") && basename(f) == "RSR_OUTLINE.adoc" && continue + content = read(f, String) + if occursin("AGPL-3.0-or-later", content) + error("AGPL still found in: $f") + end +end +# Check subdirectories +for (root, dirs, files) in walkdir(".") + startswith(root, "./.git") && continue + for f in files + path = joinpath(root, f) + endswith(path, "RSR_OUTLINE.adoc") && continue + content = read(path, String) + if occursin("AGPL-3.0-or-later", content) + error("AGPL still found in: $path") + end + end +end +println("TASK 6 PASS: No AGPL-3.0-or-later headers remain (except RSR_OUTLINE.adoc)") +---- + +''''' + +=== TASK 7: Customize SCM files – replace template placeholders with Cladistics.jl content (MEDIUM) + +*Files:* - `+.machines_readable/6scm/STATE.scm+` (entire file) - +`+.machines_readable/6scm/META.scm+` (entire file) - +`+.machines_readable/6scm/ECOSYSTEM.scm+` (entire file) - +`+.machines_readable/6scm/AGENTIC.scm+` (entire file) - +`+.machines_readable/6scm/NEUROSYM.scm+` (entire file) - +`+.machines_readable/6scm/PLAYBOOK.scm+` (entire file) + +*Problem:* All six SCM files are unmodified RSR template copies. Every +reference says `+rsr-template-repo+` instead of `+Cladistics.jl+`. +STATE.scm claims 5% completion and has no Cladistics-specific +milestones. ECOSYSTEM.scm says `+[TODO: Add specific description]+`. +META.scm has no architecture decisions relevant to a Julia phylogenetics +package. + +*What to do:* + +[arabic] +. *STATE.scm:* +* Replace all `+rsr-template-repo+` with `+Cladistics.jl+`. +* Set `+overall-completion+` to the honest value after all preceding +tasks are done (should be around 80-85% at this point). +* Add real milestones: "`v0.1.0 - Core algorithms`" (done), "`v0.2.0 - +Maximum parsimony and rerooting`" (done after tasks 3-4), "`v1.0.0 - +Package registration and Newick I/O`" (todo). +* Set `+tech-stack+` to +`+("Julia" "LinearAlgebra" "Graphs" "Clustering")+`. +* Set `+working-features+` to list what actually works. +* Update `+repo+` to `+hyperpolymath/Cladistics.jl+`. +. *ECOSYSTEM.scm:* +* Replace `+rsr-template-repo+` with `+Cladistics.jl+`. +* Set `+type+` to `+"library"+`. +* Set `+purpose+` to a real description of a Julia phylogenetics +package. +* Remove `+[TODO: Add specific description]+` and write a real +description. +* Add related projects: `+(related "PhyloNetworks.jl")+`, +`+(related "BioJulia")+`. +. *META.scm:* +* Replace `+rsr-template-repo+` with `+Cladistics.jl+`. +* Add an ADR for "`Use Fitch algorithm for parsimony scoring`". +* Add an ADR for "`Support four distance metrics (Hamming, p-distance, +JC69, K2P)`". +* Update `+code-style+` to mention Julia conventions. +. *AGENTIC.scm:* Replace `+rsr-template-repo+` with `+Cladistics.jl+` in +the comment. Add `+"julia"+` to the languages list. +. *NEUROSYM.scm:* Replace `+rsr-template-repo+` with `+Cladistics.jl+` +in the comment. +. *PLAYBOOK.scm:* Replace `+rsr-template-repo+` with `+Cladistics.jl+` +in the comment. Update build/test commands to use Julia: +`+"test" . "julia --project=. -e 'using Pkg; Pkg.test()'"+`. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +for f in readdir(".machines_readable/6scm", join=true) + content = read(f, String) + if occursin("rsr-template-repo", content) + error("Template placeholder 'rsr-template-repo' still in: $f") + end + if occursin("[TODO", content) + error("TODO placeholder still in: $f") + end +end +state = read(".machines_readable/6scm/STATE.scm", String) +@assert occursin("Cladistics", state) "STATE.scm must reference Cladistics" +@assert occursin("Julia", state) || occursin("julia", state) "STATE.scm must mention Julia" +println("TASK 7 PASS: All SCM files customized for Cladistics.jl") +---- + +''''' + +=== TASK 8: Customize AI manifest and docs – replace template placeholders (LOW) + +*Files:* - `+/var$REPOS_DIR/Cladistics.jl/0-AI-MANIFEST.a2ml+` (lines 7, +51, 56-57, 112-114) - `+/var$REPOS_DIR/Cladistics.jl/AI.a2ml+` (line 5 +and throughout) - `+/var$REPOS_DIR/Cladistics.jl/docs/CITATIONS.adoc+` +(entire file) - `+/var$REPOS_DIR/Cladistics.jl/ROADMAP.adoc+` (entire +file) + +*Problem:* + +* `+0-AI-MANIFEST.a2ml+` line 7 says `+[YOUR-REPO-NAME]+`, lines 56-57 +show `+[YOUR-REPO-NAME]/+` as directory name, lines 112-114 have +`+[DATE]+`, `+[YOUR-NAME/ORG]+` placeholders. +* `+AI.a2ml+` line 5 refers to `+rsr-template-repo+` instead of +`+Cladistics.jl+`. +* `+docs/CITATIONS.adoc+` references `+RSR-template-repo+` with author +"`Polymath, Hyper`" and year 2025. Should reference `+Cladistics.jl+` +with author "`Jewell, Jonathan D.A.`" and year 2026. +* `+ROADMAP.adoc+` line 2 says `+YOUR Template Repo Roadmap+` and has no +Cladistics-specific content. + +*What to do:* + +[arabic] +. In `+0-AI-MANIFEST.a2ml+`: +* Replace `+[YOUR-REPO-NAME]+` with `+Cladistics.jl+` (3 occurrences). +* Replace `+[DATE]+` with `+2026-02-12+`. +* Replace `+[YOUR-NAME/ORG]+` with +`+Jonathan D.A. Jewell / hyperpolymath+`. +* Update the repository structure section to show the actual `+src/+`, +`+test/+` layout. +. In `+AI.a2ml+`: +* Replace `+rsr-template-repo+` with `+Cladistics.jl+` on line 5. +. In `+docs/CITATIONS.adoc+`: +* Replace all `+RSR-template-repo+` with `+Cladistics.jl+`. +* Replace `+Polymath, Hyper+` / `+Hyper Polymath+` with +`+Jewell, Jonathan D.A.+`. +* Replace year `+2025+` with `+2026+`. +* Replace author in BibTeX `+author+` field with +`+{Jewell, Jonathan D.A.}+`. +* Update URL to `+https://github.com/hyperpolymath/Cladistics.jl+`. +* Replace `+license = {AGPL-3.0-or-later}+` with +`+license = {MPL-2.0}+`. +. In `+ROADMAP.adoc+`: +* Replace `+YOUR Template Repo Roadmap+` with `+Cladistics.jl Roadmap+`. +* Replace the generic milestones with real ones: +** v0.1.0: Core distance metrics and tree-building algorithms (done). +** v0.2.0: Maximum parsimony search and tree rerooting (done after tasks +3-4). +** v0.3.0: Newick parser (read trees from strings), tree visualization. +** v1.0.0: Julia General registry submission, full API docs, benchmarks. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +manifest = read("0-AI-MANIFEST.a2ml", String) +@assert !occursin("[YOUR-REPO-NAME]", manifest) "Manifest still has placeholder" +@assert !occursin("[DATE]", manifest) "Manifest still has [DATE]" +@assert !occursin("[YOUR-NAME/ORG]", manifest) "Manifest still has [YOUR-NAME/ORG]" +@assert occursin("Cladistics.jl", manifest) "Manifest must reference Cladistics.jl" + +ai = read("AI.a2ml", String) +@assert !occursin("rsr-template-repo", ai) "AI.a2ml still references template" + +citations = read("docs/CITATIONS.adoc", String) +@assert occursin("Jewell", citations) "Citations must credit Jewell" +@assert !occursin("Polymath, Hyper", citations) "Citations must not use old author" + +roadmap = read("ROADMAP.adoc", String) +@assert !occursin("YOUR Template", roadmap) "Roadmap still has template title" +@assert occursin("Cladistics", roadmap) "Roadmap must reference Cladistics" + +println("TASK 8 PASS: All template placeholders replaced") +---- + +''''' + +=== TASK 9: Add test for `+maximum_parsimony+` and fix test for `+calculate_parsimony_score+` (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/test/runtests.jl+` + +*Problem:* The existing test suite has no test for `+maximum_parsimony+` +(which did not exist before Task 4). The existing test for +`+calculate_parsimony_score+` (which would be in the "`Comparing +Alternative Hypotheses`" example in the README but is not in the test +file) is absent. The existing tests will also fail until Task 1 is +completed because `+calculate_parsimony_score+` crashes. + +*What to do:* + +[arabic] +. Add a new `+@testset "Maximum Parsimony Search"+` block after the +existing `+"Parsimony Informative Sites"+` testset. Test: +* Returns a `+PhylogeneticTree+` with `+method == :parsimony+`. +* Contains all input taxa. +* Parsimony score is computable and reasonable. +* With identical sequences, parsimony score should be 0. +. Add a new `+@testset "Calculate Parsimony Score"+` block that +explicitly tests `+calculate_parsimony_score+` with known inputs: +* 4 identical sequences should give score 0. +* 4 sequences with known differences should give a predictable non-zero +score. +. Add a test for `+maximum_parsimony+` with `+taxa_names+` omitted +(default naming). + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") +Pkg.test() +println("TASK 9 PASS: All tests pass including new ones") +---- + +''''' + +=== TASK 10: Add Newick parser (`+parse_newick+`) (LOW) + +*Files:* `+/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl+` + +*Problem:* The package can export trees to Newick format +(`+tree_to_newick+`) but cannot read them back. A phylogenetics package +without a Newick parser is incomplete. Users cannot import trees from +other tools (FigTree, MEGA, RAxML, etc.). + +*What to do:* + +[arabic] +. Implement `+parse_newick(newick_str::String) -> PhylogeneticTree+` +that parses a standard Newick format string into a `+PhylogeneticTree+`. +. Support: +* Named and unnamed internal nodes. +* Branch lengths (`+:0.123+` notation). +* Nested parentheses for subtrees. +* Trailing semicolon. +. Add `+parse_newick+` to the `+export+` list on line 57. +. Add a proper docstring. +. Add tests in `+test/runtests.jl+`: +* Round-trip test: `+parse_newick(tree_to_newick(tree))+` should produce +a tree with the same taxa. +* Parse a known Newick string and verify structure. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") +using Cladistics + +# Round-trip test +dmat = [0.0 0.2 0.4; 0.2 0.0 0.3; 0.4 0.3 0.0] +original = upgma(dmat, taxa_names=["A", "B", "C"]) +newick = tree_to_newick(original) +parsed = parse_newick(newick) + +original_leaves = sort(original.taxa) +parsed_leaves = sort(parsed.taxa) +@assert original_leaves == parsed_leaves "Round-trip must preserve taxa: $original_leaves vs $parsed_leaves" + +# Parse known string +tree2 = parse_newick("((A:0.1,B:0.2):0.3,C:0.4);") +@assert "A" in tree2.taxa +@assert "B" in tree2.taxa +@assert "C" in tree2.taxa +@assert length(tree2.taxa) == 3 + +println("TASK 10 PASS: Newick parser works with round-trip") +---- + +''''' + +=== FINAL VERIFICATION + +After all tasks are complete, run this comprehensive check: + +[source,julia] +---- +cd("/var$REPOS_DIR/Cladistics.jl") +using Pkg; Pkg.activate(".") + +# 1. Full test suite must pass +Pkg.test() + +# 2. All exports must be callable +using Cladistics +seqs = ["ATCGATCG", "ATCGATCG", "TTCGTTCG", "TTCCTTCC"] +taxa = ["A", "B", "C", "D"] + +dmat = distance_matrix(seqs, method=:hamming) +@assert dmat isa Matrix{Float64} + +tree1 = upgma(dmat, taxa_names=taxa) +@assert tree1 isa Cladistics.PhylogeneticTree + +tree2 = neighbor_joining(dmat, taxa_names=taxa) +@assert tree2 isa Cladistics.PhylogeneticTree + +tree3 = maximum_parsimony(seqs, taxa_names=taxa) +@assert tree3 isa Cladistics.PhylogeneticTree +@assert tree3.method == :parsimony + +cm = character_state_matrix(seqs) +score = calculate_parsimony_score(tree1, cm) +@assert score isa Int && score >= 0 + +sites = parsimony_informative_sites(cm) +@assert sites isa Vector{Int} + +support = bootstrap_support(seqs, replicates=10) +@assert support isa Dict + +clades = identify_clades(tree1, 0.5) +@assert clades isa Vector{Set{String}} + +rf = tree_distance(tree1, tree2) +@assert rf isa Int && rf >= 0 + +rooted = root_tree(tree2, "D") +# Must not be a no-op stub + +newick = tree_to_newick(tree1) +@assert endswith(newick, ";") + +parsed = parse_newick(newick) +@assert sort(parsed.taxa) == sort(taxa) + +# 3. No template placeholders remain +for (root, dirs, files) in walkdir(".") + startswith(root, "./.git") && continue + for f in files + path = joinpath(root, f) + content = try read(path, String) catch; continue end + if occursin("[YOUR-REPO-NAME]", content) + error("Template placeholder in: $path") + end + end +end + +println("\n=== ALL FINAL VERIFICATION CHECKS PASSED ===") +---- diff --git a/packages/Cladistics.jl/SONNET-TASKS.md b/packages/Cladistics.jl/SONNET-TASKS.md deleted file mode 100644 index 7e7ba5e58..000000000 --- a/packages/Cladistics.jl/SONNET-TASKS.md +++ /dev/null @@ -1,638 +0,0 @@ -# SONNET-TASKS.md -- Cladistics.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 55% - -The package has a solid single-file implementation (`src/Cladistics.jl`) with working distance -matrix calculations, UPGMA, Neighbor-Joining, bootstrap support, clade identification, -Robinson-Foulds distance, and Newick export. However, it contains three critical bugs that -will cause runtime crashes, one fully stubbed function (`root_tree`), one exported symbol -with no implementation (`maximum_parsimony`), and extensive uncustomized RSR template -boilerplate across all metadata files. The Project.toml UUID is fabricated (not generated -by Julia's `Pkg.generate`). - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update `.machines_readable/6scm/STATE.scm` with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/Cladistics.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix `fitch_score` inconsistent return type (CRITICAL) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl` lines 474-492 - -**Problem:** `fitch_score` has an inconsistent return type that will crash at runtime. - -- Line 478: Terminal nodes return `Set{Char}` (a single value). -- Line 488: Internal nodes return `(Set{Char}, Int)` (a tuple). -- Line 490: Internal nodes return `(Set{Char}, Int)` (a tuple). - -When `calculate_parsimony_score` (line 467) calls `fitch_score`, it does -`score = fitch_score(...)` and then `total_score += score`. But `score` will be either -a `Set{Char}` or a `Tuple{Set{Char}, Int}`, neither of which can be added to an `Int`. - -Additionally, line 482 calls `fitch_score` recursively on children and stores results in -`child_sets`. When children are leaf nodes, `child_sets` contains `Set{Char}` values. -When children are internal nodes, `child_sets` contains `(Set{Char}, Int)` tuples. Then -line 485 calls `reduce(intersect, child_sets)` which will fail because you cannot -`intersect` tuples. - -**What to do:** - -1. Rewrite `fitch_score` to return a `Tuple{Set{Char}, Int}` consistently. Terminal nodes - should return `(Set([char_column[idx]]), 0)`. -2. Internal nodes must unpack the tuple from each child: extract the `Set{Char}` part for - the intersection/union logic, and sum the `Int` parts for the cumulative score. -3. The function should return `(result_set, child_score_sum + local_cost)` where - `local_cost` is 0 if intersection is non-empty, 1 if union was needed. -4. Update `calculate_parsimony_score` (lines 462-472) to unpack the tuple: - `(_, score) = fitch_score(tree.root, char_matrix[:, j], tree.taxa)` and then - `total_score += score`. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") -using Cladistics - -seqs = ["ATCG", "ATCG", "TTCG", "TTCC"] -dmat = distance_matrix(seqs, method=:hamming) -tree = upgma(dmat, taxa_names=["A", "B", "C", "D"]) -cm = character_state_matrix(seqs) -score = calculate_parsimony_score(tree, cm) -@assert score isa Int "Score must be an Int, got $(typeof(score))" -@assert score >= 0 "Score must be non-negative" -@assert score <= 8 "Score suspiciously high for 4 taxa, 4 chars" -println("TASK 1 PASS: parsimony score = $score") -``` - ---- - -## TASK 2: Fix Kimura 2-parameter operator precedence bug (CRITICAL) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl` line 187 - -**Problem:** Line 187 reads: - -```julia -(1.0 - 2P - Q) <= 0 || (1.0 - 2Q) <= 0 && return Inf -``` - -In Julia, `&&` binds tighter than `||`. So this parses as: - -```julia -(1.0 - 2P - Q) <= 0 || ((1.0 - 2Q) <= 0 && return Inf) -``` - -This means: -- If `(1.0 - 2P - Q) <= 0` is true but `(1.0 - 2Q) > 0`, the function does NOT return - `Inf`. It continues to line 189 and computes `log` of a non-positive number, producing - `NaN` or throwing a `DomainError`. -- The fix must ensure that if EITHER condition is non-positive, `Inf` is returned. - -Additionally, `2P` and `2Q` in Julia are parsed as `2 * P` and `2 * Q` only because Julia -supports coefficient syntax, but this is fragile and unconventional for a scientific -package. Use explicit `2.0 * P` and `2.0 * Q` for clarity. - -**What to do:** - -1. Replace line 187 with: - ```julia - if (1.0 - 2.0 * P - Q) <= 0.0 || (1.0 - 2.0 * Q) <= 0.0 - return Inf - end - ``` -2. Also update line 189 to use explicit multiplication for consistency: - ```julia - return -0.5 * log((1.0 - 2.0 * P - Q) * sqrt(1.0 - 2.0 * Q)) - ``` - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") -using Cladistics - -# Case where (1-2P-Q) <= 0 but (1-2Q) > 0 -- would have been a bug -# P=0.4, Q=0.1 => 1-2(0.4)-0.1 = 0.1 > 0, OK -# P=0.45, Q=0.1 => 1-2(0.45)-0.1 = 0.0 <= 0, should be Inf -# Use sequences that produce high transition ratio -seqs_saturated = ["AAAA", "GGGG"] # All transitions A<->G -dmat = distance_matrix(seqs_saturated, method=:k2p) -@assert isinf(dmat[1,2]) "Saturated transitions must give Inf, got $(dmat[1,2])" - -# Normal case still works -seqs_normal = ["ATCG", "GTCG"] # One transition -dmat_normal = distance_matrix(seqs_normal, method=:k2p) -@assert isfinite(dmat_normal[1,2]) "Normal case must be finite" -@assert dmat_normal[1,2] > 0 "Normal case must be positive" -println("TASK 2 PASS: K2P operator precedence fixed") -``` - ---- - -## TASK 3: Implement `root_tree` (stub removal) (HIGH) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl` lines 665-673 - -**Problem:** `root_tree` is exported and documented but is a stub. Lines 670-672: - -```julia -# Implementation would reroot the tree structure -# Simplified version returns the original tree -return tree -``` - -It finds the outgroup node but then ignores it and returns the original tree unchanged. -This is silently wrong -- callers expect a rerooted tree but get the original. - -**What to do:** - -1. Implement proper midpoint rerooting on the outgroup branch. The algorithm: - a. Find the outgroup leaf node by name. - b. Get its parent (the node it is attached to). - c. Create a new root node at the midpoint of the outgroup's branch. - d. One child of the new root is the outgroup (with half its original branch length). - e. The other child is the rest of the tree (with the other half of the branch length). - f. Unlink the outgroup from its old parent by removing it from `children`. - g. The old parent becomes the child of the new root on the ingroup side. - h. Fix all `parent` references. -2. Return a new `PhylogeneticTree` with `method` preserved from the input tree. -3. Handle edge case: if the outgroup is already a direct child of the root, just - rebalance the branch lengths. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") -using Cladistics - -dmat = [0.0 0.2 0.4 0.5; - 0.2 0.0 0.3 0.4; - 0.4 0.3 0.0 0.2; - 0.5 0.4 0.2 0.0] -tree = neighbor_joining(dmat, taxa_names=["A", "B", "C", "Outgroup"]) -rooted = root_tree(tree, "Outgroup") - -# The rooted tree must NOT be the same object as the input -@assert rooted !== tree || rooted.root !== tree.root "root_tree must not return input unchanged" - -# The outgroup must be a direct child (or grandchild) of the new root -function find_leaf(node, name) - node.name == name && isempty(node.children) && return true - any(c -> find_leaf(c, name), node.children) -end -@assert find_leaf(rooted.root, "Outgroup") "Outgroup must be in rooted tree" - -# All original taxa must still be present -descendants = String[] -function collect_leaves(node) - if isempty(node.children) - push!(descendants, node.name) - else - for c in node.children; collect_leaves(c); end - end -end -collect_leaves(rooted.root) -@assert sort(descendants) == ["A", "B", "C", "Outgroup"] "All taxa must be preserved" - -println("TASK 3 PASS: root_tree properly reroots on outgroup") -``` - ---- - -## TASK 4: Implement `maximum_parsimony` (exported but missing) (HIGH) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl` line 57 - -**Problem:** `maximum_parsimony` is listed in the `export` statement on line 57 but has -no function definition anywhere in the file. Calling `maximum_parsimony(...)` will throw -`UndefVarError`. - -**What to do:** - -1. Add a `maximum_parsimony` function that performs a heuristic search for the most - parsimonious tree. Since exhaustive search is NP-hard, implement a stepwise addition - heuristic: - a. Start with a tree of the first 3 taxa (only one unrooted topology exists). - b. For each remaining taxon, try inserting it at every branch of the current tree. - c. Keep the insertion that gives the lowest parsimony score (using the now-fixed - `calculate_parsimony_score`). - d. Return the final tree. -2. Signature: `maximum_parsimony(sequences::Vector{String}; taxa_names=nothing) -> PhylogeneticTree` -3. Add a proper docstring following the style of the existing functions. -4. Set `method = :parsimony` on the returned `PhylogeneticTree`. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") -using Cladistics - -seqs = ["ATCGATCG", "ATCGATCG", "TTCGTTCG", "TTCCTTCC", "AACGAACG"] -tree = maximum_parsimony(seqs, taxa_names=["A", "B", "C", "D", "E"]) - -@assert tree isa Cladistics.PhylogeneticTree "Must return PhylogeneticTree" -@assert tree.method == :parsimony "Method must be :parsimony" -@assert length(tree.taxa) == 5 "Must have 5 taxa" -@assert !isempty(tree.root.children) "Root must have children" - -# Parsimony score should be computable and reasonable -cm = character_state_matrix(seqs) -score = calculate_parsimony_score(tree, cm) -@assert score isa Int -@assert score >= 0 -println("TASK 4 PASS: maximum_parsimony returns valid tree with score=$score") -``` - ---- - -## TASK 5: Generate valid Project.toml UUID (MEDIUM) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/Project.toml` line 2 - -**Problem:** The UUID `9e3g4f80-5d7c-6f0d-b4e2-3g9f0d1c2e3f` is invalid. UUIDs use -hexadecimal digits (0-9, a-f) only. This UUID contains `g` characters, which are not valid -hex digits. Julia's package manager will reject this. - -**What to do:** - -1. Generate a valid UUID by running: - ```julia - using UUIDs; println(uuid4()) - ``` -2. Replace the `uuid` line in `Project.toml` with the generated UUID. -3. Do NOT change any other field in `Project.toml`. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -toml_text = read("Project.toml", String) -uuid_match = match(r"uuid = \"([^\"]+)\"", toml_text) -uuid_str = uuid_match.captures[1] -@assert all(c -> c in "0123456789abcdef-", uuid_str) "UUID must be valid hex, got: $uuid_str" -@assert length(uuid_str) == 36 "UUID must be 36 chars (with dashes)" -@assert count(==('-'), uuid_str) == 4 "UUID must have 4 dashes" -println("TASK 5 PASS: UUID is valid: $uuid_str") -``` - ---- - -## TASK 6: Fix SPDX license headers -- replace all AGPL-3.0-or-later with MPL-2.0 (MEDIUM) - -**Files:** All files listed below that still contain `AGPL-3.0-or-later`: -- `.machines_readable/6scm/STATE.scm` line 1 -- `.machines_readable/6scm/META.scm` line 1 -- `.machines_readable/6scm/ECOSYSTEM.scm` line 1 -- `.gitignore` line 1 -- `.gitattributes` line 1 -- `ffi/zig/build.zig` line 2 -- `ffi/zig/src/main.zig` line 6 -- `ffi/zig/test/integration_test.zig` line 2 -- `examples/SafeDOMExample.res` line 1 -- `docs/CITATIONS.adoc` line 13 - -**Problem:** Per CLAUDE.md, the AGPL-3.0-or-later license has been replaced by -MPL-2.0 for all hyperpolymath original code. These files still use the old -license identifier. - -**What to do:** - -1. In every file listed above, replace `AGPL-3.0-or-later` with `MPL-2.0`. -2. Do not change anything else in these files. -3. Verify no other files still contain `AGPL-3.0-or-later` (except `RSR_OUTLINE.adoc` - which discusses licensing policy historically and should not be changed). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -for f in readdir(".", join=true) - isfile(f) || continue - endswith(f, ".adoc") && basename(f) == "RSR_OUTLINE.adoc" && continue - content = read(f, String) - if occursin("AGPL-3.0-or-later", content) - error("AGPL still found in: $f") - end -end -# Check subdirectories -for (root, dirs, files) in walkdir(".") - startswith(root, "./.git") && continue - for f in files - path = joinpath(root, f) - endswith(path, "RSR_OUTLINE.adoc") && continue - content = read(path, String) - if occursin("AGPL-3.0-or-later", content) - error("AGPL still found in: $path") - end - end -end -println("TASK 6 PASS: No AGPL-3.0-or-later headers remain (except RSR_OUTLINE.adoc)") -``` - ---- - -## TASK 7: Customize SCM files -- replace template placeholders with Cladistics.jl content (MEDIUM) - -**Files:** -- `.machines_readable/6scm/STATE.scm` (entire file) -- `.machines_readable/6scm/META.scm` (entire file) -- `.machines_readable/6scm/ECOSYSTEM.scm` (entire file) -- `.machines_readable/6scm/AGENTIC.scm` (entire file) -- `.machines_readable/6scm/NEUROSYM.scm` (entire file) -- `.machines_readable/6scm/PLAYBOOK.scm` (entire file) - -**Problem:** All six SCM files are unmodified RSR template copies. Every reference says -`rsr-template-repo` instead of `Cladistics.jl`. STATE.scm claims 5% completion and has -no Cladistics-specific milestones. ECOSYSTEM.scm says `[TODO: Add specific description]`. -META.scm has no architecture decisions relevant to a Julia phylogenetics package. - -**What to do:** - -1. **STATE.scm:** - - Replace all `rsr-template-repo` with `Cladistics.jl`. - - Set `overall-completion` to the honest value after all preceding tasks are done - (should be around 80-85% at this point). - - Add real milestones: "v0.1.0 - Core algorithms" (done), "v0.2.0 - Maximum parsimony - and rerooting" (done after tasks 3-4), "v1.0.0 - Package registration and Newick I/O" - (todo). - - Set `tech-stack` to `("Julia" "LinearAlgebra" "Graphs" "Clustering")`. - - Set `working-features` to list what actually works. - - Update `repo` to `hyperpolymath/Cladistics.jl`. - -2. **ECOSYSTEM.scm:** - - Replace `rsr-template-repo` with `Cladistics.jl`. - - Set `type` to `"library"`. - - Set `purpose` to a real description of a Julia phylogenetics package. - - Remove `[TODO: Add specific description]` and write a real description. - - Add related projects: `(related "PhyloNetworks.jl")`, `(related "BioJulia")`. - -3. **META.scm:** - - Replace `rsr-template-repo` with `Cladistics.jl`. - - Add an ADR for "Use Fitch algorithm for parsimony scoring". - - Add an ADR for "Support four distance metrics (Hamming, p-distance, JC69, K2P)". - - Update `code-style` to mention Julia conventions. - -4. **AGENTIC.scm:** Replace `rsr-template-repo` with `Cladistics.jl` in the comment. - Add `"julia"` to the languages list. - -5. **NEUROSYM.scm:** Replace `rsr-template-repo` with `Cladistics.jl` in the comment. - -6. **PLAYBOOK.scm:** Replace `rsr-template-repo` with `Cladistics.jl` in the comment. - Update build/test commands to use Julia: `"test" . "julia --project=. -e 'using Pkg; Pkg.test()'"`. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -for f in readdir(".machines_readable/6scm", join=true) - content = read(f, String) - if occursin("rsr-template-repo", content) - error("Template placeholder 'rsr-template-repo' still in: $f") - end - if occursin("[TODO", content) - error("TODO placeholder still in: $f") - end -end -state = read(".machines_readable/6scm/STATE.scm", String) -@assert occursin("Cladistics", state) "STATE.scm must reference Cladistics" -@assert occursin("Julia", state) || occursin("julia", state) "STATE.scm must mention Julia" -println("TASK 7 PASS: All SCM files customized for Cladistics.jl") -``` - ---- - -## TASK 8: Customize AI manifest and docs -- replace template placeholders (LOW) - -**Files:** -- `/var$REPOS_DIR/Cladistics.jl/0-AI-MANIFEST.a2ml` (lines 7, 51, 56-57, 112-114) -- `/var$REPOS_DIR/Cladistics.jl/AI.a2ml` (line 5 and throughout) -- `/var$REPOS_DIR/Cladistics.jl/docs/CITATIONS.adoc` (entire file) -- `/var$REPOS_DIR/Cladistics.jl/ROADMAP.adoc` (entire file) - -**Problem:** - -- `0-AI-MANIFEST.a2ml` line 7 says `[YOUR-REPO-NAME]`, lines 56-57 show `[YOUR-REPO-NAME]/` - as directory name, lines 112-114 have `[DATE]`, `[YOUR-NAME/ORG]` placeholders. -- `AI.a2ml` line 5 refers to `rsr-template-repo` instead of `Cladistics.jl`. -- `docs/CITATIONS.adoc` references `RSR-template-repo` with author "Polymath, Hyper" and - year 2025. Should reference `Cladistics.jl` with author "Jewell, Jonathan D.A." and - year 2026. -- `ROADMAP.adoc` line 2 says `YOUR Template Repo Roadmap` and has no Cladistics-specific - content. - -**What to do:** - -1. In `0-AI-MANIFEST.a2ml`: - - Replace `[YOUR-REPO-NAME]` with `Cladistics.jl` (3 occurrences). - - Replace `[DATE]` with `2026-02-12`. - - Replace `[YOUR-NAME/ORG]` with `Jonathan D.A. Jewell / hyperpolymath`. - - Update the repository structure section to show the actual `src/`, `test/` layout. - -2. In `AI.a2ml`: - - Replace `rsr-template-repo` with `Cladistics.jl` on line 5. - -3. In `docs/CITATIONS.adoc`: - - Replace all `RSR-template-repo` with `Cladistics.jl`. - - Replace `Polymath, Hyper` / `Hyper Polymath` with `Jewell, Jonathan D.A.`. - - Replace year `2025` with `2026`. - - Replace author in BibTeX `author` field with `{Jewell, Jonathan D.A.}`. - - Update URL to `https://github.com/hyperpolymath/Cladistics.jl`. - - Replace `license = {AGPL-3.0-or-later}` with `license = {MPL-2.0}`. - -4. In `ROADMAP.adoc`: - - Replace `YOUR Template Repo Roadmap` with `Cladistics.jl Roadmap`. - - Replace the generic milestones with real ones: - - v0.1.0: Core distance metrics and tree-building algorithms (done). - - v0.2.0: Maximum parsimony search and tree rerooting (done after tasks 3-4). - - v0.3.0: Newick parser (read trees from strings), tree visualization. - - v1.0.0: Julia General registry submission, full API docs, benchmarks. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -manifest = read("0-AI-MANIFEST.a2ml", String) -@assert !occursin("[YOUR-REPO-NAME]", manifest) "Manifest still has placeholder" -@assert !occursin("[DATE]", manifest) "Manifest still has [DATE]" -@assert !occursin("[YOUR-NAME/ORG]", manifest) "Manifest still has [YOUR-NAME/ORG]" -@assert occursin("Cladistics.jl", manifest) "Manifest must reference Cladistics.jl" - -ai = read("AI.a2ml", String) -@assert !occursin("rsr-template-repo", ai) "AI.a2ml still references template" - -citations = read("docs/CITATIONS.adoc", String) -@assert occursin("Jewell", citations) "Citations must credit Jewell" -@assert !occursin("Polymath, Hyper", citations) "Citations must not use old author" - -roadmap = read("ROADMAP.adoc", String) -@assert !occursin("YOUR Template", roadmap) "Roadmap still has template title" -@assert occursin("Cladistics", roadmap) "Roadmap must reference Cladistics" - -println("TASK 8 PASS: All template placeholders replaced") -``` - ---- - -## TASK 9: Add test for `maximum_parsimony` and fix test for `calculate_parsimony_score` (MEDIUM) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/test/runtests.jl` - -**Problem:** The existing test suite has no test for `maximum_parsimony` (which did not -exist before Task 4). The existing test for `calculate_parsimony_score` (which would be -in the "Comparing Alternative Hypotheses" example in the README but is not in the test -file) is absent. The existing tests will also fail until Task 1 is completed because -`calculate_parsimony_score` crashes. - -**What to do:** - -1. Add a new `@testset "Maximum Parsimony Search"` block after the existing - `"Parsimony Informative Sites"` testset. Test: - - Returns a `PhylogeneticTree` with `method == :parsimony`. - - Contains all input taxa. - - Parsimony score is computable and reasonable. - - With identical sequences, parsimony score should be 0. - -2. Add a new `@testset "Calculate Parsimony Score"` block that explicitly tests - `calculate_parsimony_score` with known inputs: - - 4 identical sequences should give score 0. - - 4 sequences with known differences should give a predictable non-zero score. - -3. Add a test for `maximum_parsimony` with `taxa_names` omitted (default naming). - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") -Pkg.test() -println("TASK 9 PASS: All tests pass including new ones") -``` - ---- - -## TASK 10: Add Newick parser (`parse_newick`) (LOW) - -**Files:** `/var$REPOS_DIR/Cladistics.jl/src/Cladistics.jl` - -**Problem:** The package can export trees to Newick format (`tree_to_newick`) but cannot -read them back. A phylogenetics package without a Newick parser is incomplete. Users -cannot import trees from other tools (FigTree, MEGA, RAxML, etc.). - -**What to do:** - -1. Implement `parse_newick(newick_str::String) -> PhylogeneticTree` that parses a standard - Newick format string into a `PhylogeneticTree`. -2. Support: - - Named and unnamed internal nodes. - - Branch lengths (`:0.123` notation). - - Nested parentheses for subtrees. - - Trailing semicolon. -3. Add `parse_newick` to the `export` list on line 57. -4. Add a proper docstring. -5. Add tests in `test/runtests.jl`: - - Round-trip test: `parse_newick(tree_to_newick(tree))` should produce a tree with the - same taxa. - - Parse a known Newick string and verify structure. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") -using Cladistics - -# Round-trip test -dmat = [0.0 0.2 0.4; 0.2 0.0 0.3; 0.4 0.3 0.0] -original = upgma(dmat, taxa_names=["A", "B", "C"]) -newick = tree_to_newick(original) -parsed = parse_newick(newick) - -original_leaves = sort(original.taxa) -parsed_leaves = sort(parsed.taxa) -@assert original_leaves == parsed_leaves "Round-trip must preserve taxa: $original_leaves vs $parsed_leaves" - -# Parse known string -tree2 = parse_newick("((A:0.1,B:0.2):0.3,C:0.4);") -@assert "A" in tree2.taxa -@assert "B" in tree2.taxa -@assert "C" in tree2.taxa -@assert length(tree2.taxa) == 3 - -println("TASK 10 PASS: Newick parser works with round-trip") -``` - ---- - -## FINAL VERIFICATION - -After all tasks are complete, run this comprehensive check: - -```julia -cd("/var$REPOS_DIR/Cladistics.jl") -using Pkg; Pkg.activate(".") - -# 1. Full test suite must pass -Pkg.test() - -# 2. All exports must be callable -using Cladistics -seqs = ["ATCGATCG", "ATCGATCG", "TTCGTTCG", "TTCCTTCC"] -taxa = ["A", "B", "C", "D"] - -dmat = distance_matrix(seqs, method=:hamming) -@assert dmat isa Matrix{Float64} - -tree1 = upgma(dmat, taxa_names=taxa) -@assert tree1 isa Cladistics.PhylogeneticTree - -tree2 = neighbor_joining(dmat, taxa_names=taxa) -@assert tree2 isa Cladistics.PhylogeneticTree - -tree3 = maximum_parsimony(seqs, taxa_names=taxa) -@assert tree3 isa Cladistics.PhylogeneticTree -@assert tree3.method == :parsimony - -cm = character_state_matrix(seqs) -score = calculate_parsimony_score(tree1, cm) -@assert score isa Int && score >= 0 - -sites = parsimony_informative_sites(cm) -@assert sites isa Vector{Int} - -support = bootstrap_support(seqs, replicates=10) -@assert support isa Dict - -clades = identify_clades(tree1, 0.5) -@assert clades isa Vector{Set{String}} - -rf = tree_distance(tree1, tree2) -@assert rf isa Int && rf >= 0 - -rooted = root_tree(tree2, "D") -# Must not be a no-op stub - -newick = tree_to_newick(tree1) -@assert endswith(newick, ";") - -parsed = parse_newick(newick) -@assert sort(parsed.taxa) == sort(taxa) - -# 3. No template placeholders remain -for (root, dirs, files) in walkdir(".") - startswith(root, "./.git") && continue - for f in files - path = joinpath(root, f) - content = try read(path, String) catch; continue end - if occursin("[YOUR-REPO-NAME]", content) - error("Template placeholder in: $path") - end - end -end - -println("\n=== ALL FINAL VERIFICATION CHECKS PASSED ===") -``` diff --git a/packages/Cladistics.jl/TOPOLOGY.md b/packages/Cladistics.jl/TOPOLOGY.adoc similarity index 89% rename from packages/Cladistics.jl/TOPOLOGY.md rename to packages/Cladistics.jl/TOPOLOGY.adoc index 988682d0b..bf81f7662 100644 --- a/packages/Cladistics.jl/TOPOLOGY.md +++ b/packages/Cladistics.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Cladistics.jl — Project Topology -# Cladistics.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── DISTANCE METHODS @@ -71,26 +67,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~75% Functional Alpha -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Distance Metrics ──────► UPGMA/NJ ──────► Tree Analysis │ Character States ──────► Parsimony ──────► Bootstrap Support │ Newick Export -``` +.... -## 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/packages/Cliodynamics.jl/ABI-FFI-README.md b/packages/Cliodynamics.jl/ABI-FFI-README.adoc similarity index 75% rename from packages/Cliodynamics.jl/ABI-FFI-README.md rename to packages/Cliodynamics.jl/ABI-FFI-README.adoc index c0f38f849..37297ddd9 100644 --- a/packages/Cliodynamics.jl/ABI-FFI-README.md +++ b/packages/Cliodynamics.jl/ABI-FFI-README.adoc @@ -1,18 +1,20 @@ +== Cliodynamics ABI/FFI Documentation -# Cliodynamics ABI/FFI Documentation +=== Overview -## Overview +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +=== Architecture -## Architecture - -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -44,11 +46,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... cliodynamics/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -76,15 +78,17 @@ cliodynamics/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export simulationResultSize : HasSize SimulationResult 24 @@ -96,13 +100,14 @@ fieldAligned : Divides 8 (offsetOf SimulationResult.time) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -110,13 +115,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -124,13 +130,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -139,71 +146,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/cliodynamics.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -214,13 +228,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "cliodynamics.h" int main() { @@ -236,16 +251,19 @@ int main() { cliodynamics_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -lcliodynamics -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import Cliodynamics.ABI.Foreign main : IO () @@ -258,11 +276,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "cliodynamics")] extern "C" { fn cliodynamics_init() -> *mut std::ffi::c_void; @@ -281,11 +300,12 @@ fn main() { cliodynamics_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const libcliodynamics = "libcliodynamics" function init() @@ -311,27 +331,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -341,44 +364,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/cliodynamics.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/cliodynamics.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/Cliodynamics.jl/CODE_OF_CONDUCT.adoc b/packages/Cliodynamics.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/Cliodynamics.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Cliodynamics.jl/CODE_OF_CONDUCT.md b/packages/Cliodynamics.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/Cliodynamics.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Cliodynamics.jl/CONTRIBUTING.adoc b/packages/Cliodynamics.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/Cliodynamics.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Cliodynamics.jl/CONTRIBUTING.md b/packages/Cliodynamics.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/Cliodynamics.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/Cliodynamics.jl/SECURITY.adoc b/packages/Cliodynamics.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/Cliodynamics.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Cliodynamics.jl/SECURITY.md b/packages/Cliodynamics.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/Cliodynamics.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Cliodynamics.jl/SONNET-TASKS.adoc b/packages/Cliodynamics.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..5ffbb089f --- /dev/null +++ b/packages/Cliodynamics.jl/SONNET-TASKS.adoc @@ -0,0 +1,680 @@ +== SONNET-TASKS.md — Cliodynamics.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 35% +____ + +The Julia source code (`+src/Cliodynamics.jl+`) and tests +(`+test/runtests.jl+`) are genuinely complete – all 16 exported +functions have real implementations, all types are defined, and the test +suite covers every public API. That part is solid. + +However, the repository was cloned from `+rsr-template-repo+` and the +vast majority of infrastructure files were never customized. SCM files +describe "`rsr-template-repo`" at 5% completion. ABI/FFI files are raw +`+{{project}}+` templates. Examples are ReScript/Deno leftovers from the +template, not Julia. The AI manifest, ROADMAP, and README.adoc still +have placeholder text. SPDX headers in SCM files are wrong. The SCM +directory is named incorrectly. A phantom `+Plots+` dependency sits in +Project.toml unused by source code. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update `+.machine_readable/STATE.scm+` with honest completion +percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/Cliodynamics.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix SCM directory name (CRITICAL) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/.machines_readable/+` +(entire directory) + +*Problem:* The SCM directory is named `+.machines_readable/6scm/+` but +the standard requires `+.machine_readable/+` (no trailing "`s`", no +`+6scm/+` subdirectory). The AI manifest at line 16 and CLAUDE.md both +state SCM files MUST be in `+.machine_readable/+` ONLY. + +*What to do:* 1. Create directory `+.machine_readable/+` in repository +root. 2. Move all 6 `+.scm+` files from `+.machines_readable/6scm/+` to +`+.machine_readable/+`: - `+STATE.scm+` - `+META.scm+` - +`+ECOSYSTEM.scm+` - `+AGENTIC.scm+` - `+NEUROSYM.scm+` - +`+PLAYBOOK.scm+` 3. Remove the empty `+.machines_readable/6scm/+` +directory. 4. Remove the empty `+.machines_readable/+` directory. 5. +Update `+.gitignore+` if it references the old path. + +*Verification:* + +[source,bash] +---- +# All 6 SCM files exist in correct location +test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/STATE.scm && \ +test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/META.scm && \ +test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/ECOSYSTEM.scm && \ +test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/AGENTIC.scm && \ +test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/NEUROSYM.scm && \ +test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/PLAYBOOK.scm && \ +! test -d /var$REPOS_DIR/Cliodynamics.jl/.machines_readable && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 2: Fix SPDX headers in all SCM files (CRITICAL) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/STATE.scm+` (line 1) +- `+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/META.scm+` (line 1) +- `+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/ECOSYSTEM.scm+` +(line 1) + +*Problem:* STATE.scm, META.scm, and ECOSYSTEM.scm all have +`+AGPL-3.0-or-later+` as their SPDX identifier. Per CLAUDE.md license +policy, AGPL-3.0 must NEVER be used. All hyperpolymath original code +uses `+MPL-2.0+`. AGENTIC.scm, NEUROSYM.scm, and PLAYBOOK.scm already +have the correct header. + +*What to do:* 1. In `+STATE.scm+` line 1: change `+AGPL-3.0-or-later+` +to `+MPL-2.0+`. 2. In `+META.scm+` line 1: change `+AGPL-3.0-or-later+` +to `+MPL-2.0+`. 3. In `+ECOSYSTEM.scm+` line 1: change +`+AGPL-3.0-or-later+` to `+MPL-2.0+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable +grep -c "MPL-2.0" STATE.scm META.scm ECOSYSTEM.scm AGENTIC.scm NEUROSYM.scm PLAYBOOK.scm | \ + awk -F: '{sum += $2} END {if (sum == 6) print "PASS"; else print "FAIL: only " sum " of 6 files have correct SPDX"}' +---- + +''''' + +=== TASK 3: Fix SPDX headers in Zig and Idris2 template files (CRITICAL) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/src/main.zig+` (line +6) - `+/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/build.zig+` (line 2) - +`+/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/test/integration_test.zig+` +(line 2) + +*Problem:* All three Zig files have +`+SPDX-License-Identifier: CC-BY-SA-4.0+`. Must be `+MPL-2.0+`. + +*What to do:* 1. In `+ffi/zig/src/main.zig+` line 6: change +`+AGPL-3.0-or-later+` to `+MPL-2.0+`. 2. In `+ffi/zig/build.zig+` line +2: change `+AGPL-3.0-or-later+` to `+MPL-2.0+`. 3. In +`+ffi/zig/test/integration_test.zig+` line 2: change +`+AGPL-3.0-or-later+` to `+MPL-2.0+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +grep -r "AGPL" ffi/ src/abi/ .machine_readable/ && echo "FAIL: AGPL references remain" || echo "PASS: no AGPL references" +---- + +''''' + +=== TASK 4: Rewrite STATE.scm for Cliodynamics.jl (HIGH) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/STATE.scm+` + +*Problem:* The entire file (lines 1-65) still describes +"`rsr-template-repo`" with 5% completion and generic milestones. The +actual Julia source code is complete with 16 exported functions and a +full test suite. + +*What to do:* 1. Replace the entire contents of STATE.scm with a file +that accurately describes Cliodynamics.jl. 2. Set `+project+` to +`+"Cliodynamics.jl"+`. 3. Set `+repo+` to +`+"hyperpolymath/Cliodynamics.jl"+`. 4. Set `+tech-stack+` to +`+("Julia" "DifferentialEquations.jl" "DataFrames.jl" "Optim.jl")+`. 5. +Set `+overall-completion+` to `+90+` (core Julia code is done, but +infrastructure/metadata needs cleanup). 6. List working features: +Malthusian model, DST model, elite overproduction index, PSI, secular +cycle analysis, phase detection, state capacity model, collective action +problem, utility functions (moving average, detrend, normalize, carrying +capacity, crisis threshold, instability events, conflict intensity, +population pressure). 7. List remaining items: Julia examples needed, +Project.toml cleanup, ABI/FFI template customization, documentation +polish. 8. Set `+phase+` to `+"beta"+`. 9. Keep the helper functions at +the bottom. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable +grep -q "Cliodynamics" STATE.scm && \ +grep -q "90" STATE.scm && \ +! grep -q "rsr-template-repo" STATE.scm && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 5: Rewrite META.scm for Cliodynamics.jl (HIGH) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/META.scm+` + +*Problem:* Lines 1-47 still describe "`rsr-template-repo`" with generic +RSR-focused ADRs and development practices. Should describe +Cliodynamics.jl architectural decisions. + +*What to do:* 1. Change `+define-meta+` name from `+rsr-template-repo+` +to `+Cliodynamics.jl+`. 2. Replace ADR-001 with a decision about using +Julia + DifferentialEquations.jl for cliodynamic modeling. 3. Add +ADR-002 about the single-file module design (`+src/Cliodynamics.jl+`). +4. Update development practices to reference Julia conventions +(docstrings, `+@testset+`, Pkg.test). 5. Update design rationale to +explain why cliodynamics models benefit from Julia’s ODE solvers. 6. +Remove references to ReScript/Rust/Gleam in code-style (this is a Julia +project). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable +grep -q "Cliodynamics" META.scm && \ +! grep -q "rsr-template-repo" META.scm && \ +grep -q "Julia" META.scm && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 6: Rewrite ECOSYSTEM.scm for Cliodynamics.jl (HIGH) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/ECOSYSTEM.scm+` + +*Problem:* Lines 1-29 still describe "`rsr-template-repo`" with +`+[TODO: Add specific description]+` on line 24. Must describe +Cliodynamics.jl’s position in the ecosystem. + +*What to do:* 1. Change `+name+` from `+"rsr-template-repo"+` to +`+"Cliodynamics.jl"+`. 2. Set `+type+` to `+"library"+`. 3. Set +`+purpose+` to describe cliodynamic modeling and historical dynamics +analysis. 4. Update `+position-in-ecosystem+` to describe this as a +Julia scientific computing library. 5. Add `+related-projects+`: sibling +`+Cliometrics.jl+`, dependency `+DifferentialEquations.jl+`, inspiration +`+Seshat Global History Databank+`. 6. Replace the +`+[TODO: Add specific description]+` in `+what-this-is+`. 7. Update +`+what-this-is-not+` to clarify it is not a general-purpose statistics +library. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable +grep -q "Cliodynamics" ECOSYSTEM.scm && \ +! grep -q "rsr-template-repo" ECOSYSTEM.scm && \ +! grep -q "TODO" ECOSYSTEM.scm && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 7: Remove unused Plots dependency from Project.toml (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/Project.toml+` (lines 12, +20) + +*Problem:* `+Plots+` is listed as a dependency (line 12, UUID +`+91a5bcdd-55d7-5caf-9e0b-520d859cae80+`) and in compat (line 20), but +it is never `+using Plots+` in `+src/Cliodynamics.jl+`. Plots is a heavy +dependency (~100+ transitive packages) and should not be a hard +dependency. The README.md shows Plots in example code, but that is +user-side usage, not library code. + +*What to do:* 1. Remove the line +`+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"+` from `+[deps]+` (line +12). 2. Remove the line `+Plots = "1"+` from `+[compat]+` (line 20). 3. +Do NOT add Plots to `+[extras]+` – it is only used in README examples, +not tests. + +*Verification:* + +[source,julia] +---- +# Run from repo root +cd("/var$REPOS_DIR/Cliodynamics.jl") +toml = read("Project.toml", String) +@assert !occursin("Plots", toml) "FAIL: Plots still in Project.toml" +println("PASS: Plots removed from Project.toml") +---- + +''''' + +=== TASK 8: Add DataFrames and Statistics to test dependencies (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/Project.toml+` (lines 22-26) + +*Problem:* `+test/runtests.jl+` uses `+using DataFrames+` (line 5) and +`+using Statistics+` (line 6), but neither is listed in `+[extras]+` or +`+[targets]+`. Currently only `+Test+` is in extras. While they are +regular deps, best practice for Julia packages is to also list test +dependencies in `+[extras]+` if they are used in tests beyond the main +package deps. However, since DataFrames and Statistics ARE already in +`+[deps]+`, they will be available during testing. This task is about +ensuring the test target is correct. + +Actually, the current setup works because `+[deps]+` packages are +available during testing. *Skip this task – no changes needed.* The +existing `+[extras]+` and `+[targets]+` are correct. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cliodynamics.jl") +using Pkg +Pkg.activate(".") +Pkg.test() +---- + +''''' + +=== TASK 9: Remove template ReScript/Deno examples (MEDIUM) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/examples/SafeDOMExample.res+` (entire +file) - +`+/var$REPOS_DIR/Cliodynamics.jl/examples/web-project-deno.json+` +(entire file) + +*Problem:* These files are leftover from `+rsr-template-repo+`. A Julia +cliodynamics library has no use for ReScript DOM mounting examples or +Deno project config. They are confusing and irrelevant. + +*What to do:* 1. Delete `+examples/SafeDOMExample.res+`. 2. Delete +`+examples/web-project-deno.json+`. 3. Create +`+examples/basic_usage.jl+` with a runnable Julia script demonstrating: +- Malthusian model simulation - Demographic-structural model simulation +- Elite overproduction index calculation - Political stress indicator +calculation - Secular cycle analysis Use the examples from the module +docstring (lines 48-66 of `+src/Cliodynamics.jl+`) and the README.md +Quick Start section as a guide. 4. Create +`+examples/historical_analysis.jl+` demonstrating phase detection, +instability events, and conflict intensity with synthetic data. 5. Add +`+# SPDX-License-Identifier: CC-BY-SA-4.0+` as the first line of each +new file. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +! test -f examples/SafeDOMExample.res && \ +! test -f examples/web-project-deno.json && \ +test -f examples/basic_usage.jl && \ +test -f examples/historical_analysis.jl && \ +head -1 examples/basic_usage.jl | grep -q "PMPL" && \ +echo "PASS" || echo "FAIL" +---- + +[source,julia] +---- +# Verify examples are syntactically valid +cd("/var$REPOS_DIR/Cliodynamics.jl") +include("examples/basic_usage.jl") +include("examples/historical_analysis.jl") +println("PASS: examples run without error") +---- + +''''' + +=== TASK 10: Customize 0-AI-MANIFEST.a2ml (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/0-AI-MANIFEST.a2ml+` + +*Problem:* Lines 7-8 still say `+[YOUR-REPO-NAME]+`. Lines 51-67 have +generic placeholder structure. Lines 112-114 have `+[DATE]+`, +`+[YOUR-NAME/ORG]+`. The manifest does not describe the actual +Cliodynamics.jl repository. + +*What to do:* 1. Replace all `+[YOUR-REPO-NAME]+` with +`+Cliodynamics.jl+` (lines 7, 56). 2. Replace the repository structure +section (lines 55-68) with the actual structure: +`+Cliodynamics.jl/ ├── 0-AI-MANIFEST.a2ml ├── README.md ├── Project.toml ├── src/ │ ├── Cliodynamics.jl # Main module (all code) │ └── abi/ # Idris2 ABI definitions (template) ├── test/ │ └── runtests.jl # Test suite ├── examples/ # Usage examples ├── ffi/zig/ # Zig FFI (template) ├── .machine_readable/ # SCM files (6 files) └── .bot_directives/ # Bot instructions+` +3. Set `+[DATE]+` to `+2026-02-07+` (line 112). 4. Set +`+[YOUR-NAME/ORG]+` to `+Jonathan D.A. Jewell / hyperpolymath+` (line +113). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +! grep -q "\[YOUR-REPO-NAME\]" 0-AI-MANIFEST.a2ml && \ +! grep -q "\[DATE\]" 0-AI-MANIFEST.a2ml && \ +! grep -q "\[YOUR-NAME/ORG\]" 0-AI-MANIFEST.a2ml && \ +grep -q "Cliodynamics" 0-AI-MANIFEST.a2ml && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 11: Replace ROADMAP.adoc with Cliodynamics.jl-specific content (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/ROADMAP.adoc+` + +*Problem:* Line 2 says "`YOUR Template Repo Roadmap`". All milestone +items are generic placeholders. The actual Julia code is at v0.1.0 with +all core features implemented. + +*What to do:* 1. Replace the entire file with a roadmap specific to +Cliodynamics.jl. 2. Add `+// SPDX-License-Identifier: CC-BY-SA-4.0+` as +line 1 (already present). 3. Mark v0.1.0 milestones as complete: - Core +population dynamics models - Elite dynamics analysis - Political stress +indicators - Secular cycle analysis - State formation models - Utility +functions - Comprehensive test suite 4. Add v0.2.0 planned milestones: - +Empirical dataset integration (Seshat, CrisisDB) - Plotting recipes for +Plots.jl - Model fitting to historical data - Parameter estimation with +Optim.jl 5. Add v1.0.0 goals: - Bayesian inference support (Turing.jl +integration) - Spatial cliodynamic models - Interactive documentation +(Documenter.jl) - Publication-quality examples + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +! grep -q "YOUR Template" ROADMAP.adoc && \ +grep -q "Cliodynamics" ROADMAP.adoc && \ +grep -q "v0.1.0" ROADMAP.adoc && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 12: Replace README.adoc with Cliodynamics.jl-specific content (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/README.adoc+` + +*Problem:* The entire file (134 lines) is the RSR template README +describing ReScript, SafeDOM, Deno, and the ABI/FFI standard. It has +nothing to do with cliodynamic modeling. Line 1: "`RSR template repo`". +Line 43: "`Update `+[YOUR-REPO-NAME]+` placeholders`". Lines 79-133: +ReScript SafeDOM documentation. + +*What to do:* 1. Replace the entire file with a brief AsciiDoc version +of the Cliodynamics.jl description. 2. Since `+README.md+` already has +the full project description, `+README.adoc+` should be a concise +pointer that says "`See README.md for full documentation`" plus a brief +summary. 3. Alternatively, DELETE `+README.adoc+` entirely – GitHub +renders `+README.md+` by default, and having both is confusing. If you +keep it, make it Cliodynamics-specific. 4. Recommended: Delete +`+README.adoc+` and let `+README.md+` be the single README. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +# If README.adoc was deleted: +! test -f README.adoc && echo "PASS: README.adoc deleted" || \ +# If README.adoc was kept: +(! grep -q "RSR template" README.adoc && grep -q "Cliodynamics" README.adoc && echo "PASS: README.adoc customized") +---- + +''''' + +=== TASK 13: Customize ABI Idris2 files for Cliodynamics.jl (LOW) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/src/abi/Types.idr+` (lines +11, 172-175, 198-202) - +`+/var$REPOS_DIR/Cliodynamics.jl/src/abi/Layout.idr+` (line 8) - +`+/var$REPOS_DIR/Cliodynamics.jl/src/abi/Foreign.idr+` (lines 9, 23, 35, +49, 77, 98, 125, 152, 164, 185, 211) + +*Problem:* Every Idris2 file has `+{{PROJECT}}+` and `+{{project}}+` +placeholders throughout. Module names are `+{{PROJECT}}.ABI.Types+`, +etc. FFI declarations reference `+lib{{project}}+`. These files will not +compile. + +*What to do:* 1. In all three `+.idr+` files, replace `+{{PROJECT}}+` +with `+Cliodynamics+` (uppercase for module names). 2. Replace +`+{{project}}+` with `+cliodynamics+` (lowercase for library names and +function prefixes). 3. In `+Types.idr+`: Replace `+ExampleStruct+` with +a cliodynamics-relevant struct, e.g., `+SimulationResult+` with fields +`+time : Double+`, `+population : Double+`, `+elites : Double+`. Update +the size proofs accordingly. 4. In `+Foreign.idr+`: Update the FFI +function declarations to reflect cliodynamics operations (e.g., +`+cliodynamics_init+`, `+cliodynamics_free+`, `+cliodynamics_process+`). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +! grep -r "{{PROJECT}}" src/abi/ && \ +! grep -r "{{project}}" src/abi/ && \ +grep -q "Cliodynamics" src/abi/Types.idr && \ +grep -q "Cliodynamics" src/abi/Layout.idr && \ +grep -q "Cliodynamics" src/abi/Foreign.idr && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 14: Customize Zig FFI files for Cliodynamics.jl (LOW) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/src/main.zig+` +(lines 1, 12, 54, 73, 89, 113, 135, 148, 184, 198, 203, 215, 245, 256, +259, 263, 266, 271, 272) - +`+/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/build.zig+` (lines 1, 12, 34, +37) - +`+/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/test/integration_test.zig+` +(lines 1, 10-17, 24-25, 31-32, 34, 39, 48-49, 51, 56, 65-66, 68-69, 75, +84, 96-97, 99, 110, 118, 129-130, 131, 138-139, 143, 145-146, 149, +158-159, 168, 174) + +*Problem:* Every Zig file has `+{{project}}+` and `+{{PROJECT}}+` +template placeholders. Function names like `+{{project}}_init()+`, +library name `+"{{project}}"+`, etc. These files will not compile. + +*What to do:* 1. In all three `+.zig+` files, replace `+{{project}}+` +with `+cliodynamics+` (lowercase). 2. Replace `+{{PROJECT}}+` with +`+Cliodynamics+` (where used as display name). 3. In `+build.zig+` line +34: The header reference `+include/{{project}}.h+` should become +`+include/cliodynamics.h+`. Note: this header file does not exist yet – +that is acceptable for template infrastructure. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +! grep -r "{{project}}" ffi/ && \ +! grep -r "{{PROJECT}}" ffi/ && \ +grep -q "cliodynamics" ffi/zig/src/main.zig && \ +grep -q "cliodynamics" ffi/zig/build.zig && \ +grep -q "cliodynamics" ffi/zig/test/integration_test.zig && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 15: Update AGENTIC.scm with Cliodynamics.jl specifics (LOW) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/AGENTIC.scm+` + +*Problem:* Line 7 references `+claude-opus-4-5-20251101+` (outdated +model ID). The `+languages+` constraint on line 15 is empty. The file +should reflect Julia-specific patterns. + +*What to do:* 1. Update model to `+"claude-opus-4-6"+` (current model +per system info). 2. Set `+languages+` to `+("julia")+`. 3. Add +constraint `+(primary-runtime . "julia")+`. 4. Keep `+banned+` languages +list as is. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable +grep -q "julia" AGENTIC.scm && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 16: Update PLAYBOOK.scm with Julia procedures (LOW) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/PLAYBOOK.scm+` + +*Problem:* Lines 7-9 reference `+just build+`, `+just test+`, +`+just release+` but there is no `+justfile+` in the repository. The +correct Julia commands should be used. + +*What to do:* 1. Change build procedure to +`+"julia --project=. -e 'using Pkg; Pkg.instantiate()'"+`. 2. Change +test procedure to `+"julia --project=. -e 'using Pkg; Pkg.test()'"+`. 3. +Change release procedure to +`+"julia --project=. -e 'using Pkg; Pkg.build()'"+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable +grep -q "Pkg.test" PLAYBOOK.scm && \ +! grep -q "just " PLAYBOOK.scm && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 17: Remove sync report file (LOW) + +*Files:* - +`+/var$REPOS_DIR/Cliodynamics.jl/sync_report_20260210_160611.txt+` + +*Problem:* This appears to be a generated sync report that should not be +tracked in git. It is not part of the project. + +*What to do:* 1. Delete `+sync_report_20260210_160611.txt+`. 2. Add +`+sync_report_*.txt+` to `+.gitignore+` to prevent future occurrences. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +! test -f sync_report_20260210_160611.txt && \ +grep -q "sync_report" .gitignore && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 18: Add `+.claude/CLAUDE.md+` for project-specific instructions (LOW) + +*Files:* - `+/var$REPOS_DIR/Cliodynamics.jl/.claude/CLAUDE.md+` (new +file) + +*Problem:* No project-specific CLAUDE.md exists. This file should +describe how to work with this Julia package. + +*What to do:* 1. Create `+.claude/+` directory. 2. Create +`+.claude/CLAUDE.md+` with: - Project description: Julia package for +cliodynamic modeling - Build command: +`+julia --project=. -e 'using Pkg; Pkg.instantiate()'+` - Test command: +`+julia --project=. -e 'using Pkg; Pkg.test()'+` - Code style: Julia +conventions, docstrings on all exports, `+@testset+` structure - +Architecture note: single-file module in `+src/Cliodynamics.jl+` - +Dependencies: DifferentialEquations.jl, DataFrames.jl, Optim.jl, +Statistics, LinearAlgebra + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl +test -f .claude/CLAUDE.md && \ +grep -q "Cliodynamics" .claude/CLAUDE.md && \ +grep -q "Pkg.test" .claude/CLAUDE.md && \ +echo "PASS" || echo "FAIL" +---- + +''''' + +=== FINAL VERIFICATION + +After all tasks are complete, run this comprehensive check: + +[source,bash] +---- +cd /var$REPOS_DIR/Cliodynamics.jl + +echo "=== 1. SCM directory structure ===" +ls -la .machine_readable/ && ! test -d .machines_readable && echo "OK" || echo "FAIL" + +echo "" +echo "=== 2. No AGPL references ===" +grep -r "AGPL" .machine_readable/ ffi/ src/abi/ && echo "FAIL" || echo "OK" + +echo "" +echo "=== 3. No template placeholders ===" +grep -r "{{project}}\|{{PROJECT}}\|\[YOUR-REPO-NAME\]\|\[TODO\]" \ + .machine_readable/ src/abi/ ffi/ 0-AI-MANIFEST.a2ml ROADMAP.adoc && echo "FAIL" || echo "OK" + +echo "" +echo "=== 4. No rsr-template-repo references in SCM ===" +grep -r "rsr-template-repo" .machine_readable/ && echo "FAIL" || echo "OK" + +echo "" +echo "=== 5. No ReScript/Deno examples ===" +! test -f examples/SafeDOMExample.res && ! test -f examples/web-project-deno.json && echo "OK" || echo "FAIL" + +echo "" +echo "=== 6. Julia examples exist ===" +test -f examples/basic_usage.jl && test -f examples/historical_analysis.jl && echo "OK" || echo "FAIL" + +echo "" +echo "=== 7. No Plots in Project.toml ===" +! grep -q "Plots" Project.toml && echo "OK" || echo "FAIL" + +echo "" +echo "=== 8. No sync report ===" +! test -f sync_report_20260210_160611.txt && echo "OK" || echo "FAIL" + +echo "" +echo "=== 9. CLAUDE.md exists ===" +test -f .claude/CLAUDE.md && echo "OK" || echo "FAIL" +---- + +[source,julia] +---- +# Full Julia test suite +cd("/var$REPOS_DIR/Cliodynamics.jl") +using Pkg +Pkg.activate(".") +Pkg.instantiate() +Pkg.test() +println("ALL JULIA TESTS PASSED") +---- + +After final verification passes, update `+.machine_readable/STATE.scm+` +to set `+overall-completion+` to `+95+` (the remaining 5% is for +Documenter.jl setup, CI/CD Julia workflow, and package registration). diff --git a/packages/Cliodynamics.jl/SONNET-TASKS.md b/packages/Cliodynamics.jl/SONNET-TASKS.md deleted file mode 100644 index 43fd2c748..000000000 --- a/packages/Cliodynamics.jl/SONNET-TASKS.md +++ /dev/null @@ -1,636 +0,0 @@ -# SONNET-TASKS.md — Cliodynamics.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 35% - -The Julia source code (`src/Cliodynamics.jl`) and tests (`test/runtests.jl`) are genuinely -complete -- all 16 exported functions have real implementations, all types are defined, and -the test suite covers every public API. That part is solid. - -However, the repository was cloned from `rsr-template-repo` and the vast majority of -infrastructure files were never customized. SCM files describe "rsr-template-repo" at 5% -completion. ABI/FFI files are raw `{{project}}` templates. Examples are ReScript/Deno -leftovers from the template, not Julia. The AI manifest, ROADMAP, and README.adoc still -have placeholder text. SPDX headers in SCM files are wrong. The SCM directory is named -incorrectly. A phantom `Plots` dependency sits in Project.toml unused by source code. - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update `.machine_readable/STATE.scm` with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/Cliodynamics.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix SCM directory name (CRITICAL) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machines_readable/` (entire directory) - -**Problem:** The SCM directory is named `.machines_readable/6scm/` but the standard requires -`.machine_readable/` (no trailing "s", no `6scm/` subdirectory). The AI manifest at line 16 -and CLAUDE.md both state SCM files MUST be in `.machine_readable/` ONLY. - -**What to do:** -1. Create directory `.machine_readable/` in repository root. -2. Move all 6 `.scm` files from `.machines_readable/6scm/` to `.machine_readable/`: - - `STATE.scm` - - `META.scm` - - `ECOSYSTEM.scm` - - `AGENTIC.scm` - - `NEUROSYM.scm` - - `PLAYBOOK.scm` -3. Remove the empty `.machines_readable/6scm/` directory. -4. Remove the empty `.machines_readable/` directory. -5. Update `.gitignore` if it references the old path. - -**Verification:** -```bash -# All 6 SCM files exist in correct location -test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/STATE.scm && \ -test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/META.scm && \ -test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/ECOSYSTEM.scm && \ -test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/AGENTIC.scm && \ -test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/NEUROSYM.scm && \ -test -f /var$REPOS_DIR/Cliodynamics.jl/.machine_readable/PLAYBOOK.scm && \ -! test -d /var$REPOS_DIR/Cliodynamics.jl/.machines_readable && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 2: Fix SPDX headers in all SCM files (CRITICAL) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/STATE.scm` (line 1) -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/META.scm` (line 1) -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/ECOSYSTEM.scm` (line 1) - -**Problem:** STATE.scm, META.scm, and ECOSYSTEM.scm all have `AGPL-3.0-or-later` as their -SPDX identifier. Per CLAUDE.md license policy, AGPL-3.0 must NEVER be used. All hyperpolymath -original code uses `MPL-2.0`. AGENTIC.scm, NEUROSYM.scm, and PLAYBOOK.scm already -have the correct header. - -**What to do:** -1. In `STATE.scm` line 1: change `AGPL-3.0-or-later` to `MPL-2.0`. -2. In `META.scm` line 1: change `AGPL-3.0-or-later` to `MPL-2.0`. -3. In `ECOSYSTEM.scm` line 1: change `AGPL-3.0-or-later` to `MPL-2.0`. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable -grep -c "MPL-2.0" STATE.scm META.scm ECOSYSTEM.scm AGENTIC.scm NEUROSYM.scm PLAYBOOK.scm | \ - awk -F: '{sum += $2} END {if (sum == 6) print "PASS"; else print "FAIL: only " sum " of 6 files have correct SPDX"}' -``` - ---- - -## TASK 3: Fix SPDX headers in Zig and Idris2 template files (CRITICAL) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/src/main.zig` (line 6) -- `/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/build.zig` (line 2) -- `/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/test/integration_test.zig` (line 2) - -**Problem:** All three Zig files have `SPDX-License-Identifier: CC-BY-SA-4.0`. -Must be `MPL-2.0`. - -**What to do:** -1. In `ffi/zig/src/main.zig` line 6: change `AGPL-3.0-or-later` to `MPL-2.0`. -2. In `ffi/zig/build.zig` line 2: change `AGPL-3.0-or-later` to `MPL-2.0`. -3. In `ffi/zig/test/integration_test.zig` line 2: change `AGPL-3.0-or-later` to `MPL-2.0`. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -grep -r "AGPL" ffi/ src/abi/ .machine_readable/ && echo "FAIL: AGPL references remain" || echo "PASS: no AGPL references" -``` - ---- - -## TASK 4: Rewrite STATE.scm for Cliodynamics.jl (HIGH) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/STATE.scm` - -**Problem:** The entire file (lines 1-65) still describes "rsr-template-repo" with 5% -completion and generic milestones. The actual Julia source code is complete with 16 exported -functions and a full test suite. - -**What to do:** -1. Replace the entire contents of STATE.scm with a file that accurately describes Cliodynamics.jl. -2. Set `project` to `"Cliodynamics.jl"`. -3. Set `repo` to `"hyperpolymath/Cliodynamics.jl"`. -4. Set `tech-stack` to `("Julia" "DifferentialEquations.jl" "DataFrames.jl" "Optim.jl")`. -5. Set `overall-completion` to `90` (core Julia code is done, but infrastructure/metadata needs cleanup). -6. List working features: Malthusian model, DST model, elite overproduction index, PSI, - secular cycle analysis, phase detection, state capacity model, collective action problem, - utility functions (moving average, detrend, normalize, carrying capacity, crisis threshold, - instability events, conflict intensity, population pressure). -7. List remaining items: Julia examples needed, Project.toml cleanup, ABI/FFI template - customization, documentation polish. -8. Set `phase` to `"beta"`. -9. Keep the helper functions at the bottom. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable -grep -q "Cliodynamics" STATE.scm && \ -grep -q "90" STATE.scm && \ -! grep -q "rsr-template-repo" STATE.scm && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 5: Rewrite META.scm for Cliodynamics.jl (HIGH) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/META.scm` - -**Problem:** Lines 1-47 still describe "rsr-template-repo" with generic RSR-focused ADRs -and development practices. Should describe Cliodynamics.jl architectural decisions. - -**What to do:** -1. Change `define-meta` name from `rsr-template-repo` to `Cliodynamics.jl`. -2. Replace ADR-001 with a decision about using Julia + DifferentialEquations.jl for - cliodynamic modeling. -3. Add ADR-002 about the single-file module design (`src/Cliodynamics.jl`). -4. Update development practices to reference Julia conventions (docstrings, `@testset`, Pkg.test). -5. Update design rationale to explain why cliodynamics models benefit from Julia's ODE solvers. -6. Remove references to ReScript/Rust/Gleam in code-style (this is a Julia project). - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable -grep -q "Cliodynamics" META.scm && \ -! grep -q "rsr-template-repo" META.scm && \ -grep -q "Julia" META.scm && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 6: Rewrite ECOSYSTEM.scm for Cliodynamics.jl (HIGH) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/ECOSYSTEM.scm` - -**Problem:** Lines 1-29 still describe "rsr-template-repo" with `[TODO: Add specific description]` -on line 24. Must describe Cliodynamics.jl's position in the ecosystem. - -**What to do:** -1. Change `name` from `"rsr-template-repo"` to `"Cliodynamics.jl"`. -2. Set `type` to `"library"`. -3. Set `purpose` to describe cliodynamic modeling and historical dynamics analysis. -4. Update `position-in-ecosystem` to describe this as a Julia scientific computing library. -5. Add `related-projects`: sibling `Cliometrics.jl`, dependency `DifferentialEquations.jl`, - inspiration `Seshat Global History Databank`. -6. Replace the `[TODO: Add specific description]` in `what-this-is`. -7. Update `what-this-is-not` to clarify it is not a general-purpose statistics library. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable -grep -q "Cliodynamics" ECOSYSTEM.scm && \ -! grep -q "rsr-template-repo" ECOSYSTEM.scm && \ -! grep -q "TODO" ECOSYSTEM.scm && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 7: Remove unused Plots dependency from Project.toml (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/Project.toml` (lines 12, 20) - -**Problem:** `Plots` is listed as a dependency (line 12, UUID `91a5bcdd-55d7-5caf-9e0b-520d859cae80`) -and in compat (line 20), but it is never `using Plots` in `src/Cliodynamics.jl`. Plots is a -heavy dependency (~100+ transitive packages) and should not be a hard dependency. The README.md -shows Plots in example code, but that is user-side usage, not library code. - -**What to do:** -1. Remove the line `Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"` from `[deps]` (line 12). -2. Remove the line `Plots = "1"` from `[compat]` (line 20). -3. Do NOT add Plots to `[extras]` -- it is only used in README examples, not tests. - -**Verification:** -```julia -# Run from repo root -cd("/var$REPOS_DIR/Cliodynamics.jl") -toml = read("Project.toml", String) -@assert !occursin("Plots", toml) "FAIL: Plots still in Project.toml" -println("PASS: Plots removed from Project.toml") -``` - ---- - -## TASK 8: Add DataFrames and Statistics to test dependencies (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/Project.toml` (lines 22-26) - -**Problem:** `test/runtests.jl` uses `using DataFrames` (line 5) and `using Statistics` -(line 6), but neither is listed in `[extras]` or `[targets]`. Currently only `Test` is in -extras. While they are regular deps, best practice for Julia packages is to also list test -dependencies in `[extras]` if they are used in tests beyond the main package deps. However, -since DataFrames and Statistics ARE already in `[deps]`, they will be available during testing. -This task is about ensuring the test target is correct. - -Actually, the current setup works because `[deps]` packages are available during testing. -**Skip this task -- no changes needed.** The existing `[extras]` and `[targets]` are correct. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cliodynamics.jl") -using Pkg -Pkg.activate(".") -Pkg.test() -``` - ---- - -## TASK 9: Remove template ReScript/Deno examples (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/examples/SafeDOMExample.res` (entire file) -- `/var$REPOS_DIR/Cliodynamics.jl/examples/web-project-deno.json` (entire file) - -**Problem:** These files are leftover from `rsr-template-repo`. A Julia cliodynamics library -has no use for ReScript DOM mounting examples or Deno project config. They are confusing and -irrelevant. - -**What to do:** -1. Delete `examples/SafeDOMExample.res`. -2. Delete `examples/web-project-deno.json`. -3. Create `examples/basic_usage.jl` with a runnable Julia script demonstrating: - - Malthusian model simulation - - Demographic-structural model simulation - - Elite overproduction index calculation - - Political stress indicator calculation - - Secular cycle analysis - Use the examples from the module docstring (lines 48-66 of `src/Cliodynamics.jl`) and - the README.md Quick Start section as a guide. -4. Create `examples/historical_analysis.jl` demonstrating phase detection, instability events, - and conflict intensity with synthetic data. -5. Add `# SPDX-License-Identifier: CC-BY-SA-4.0` as the first line of each new file. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -! test -f examples/SafeDOMExample.res && \ -! test -f examples/web-project-deno.json && \ -test -f examples/basic_usage.jl && \ -test -f examples/historical_analysis.jl && \ -head -1 examples/basic_usage.jl | grep -q "PMPL" && \ -echo "PASS" || echo "FAIL" -``` - -```julia -# Verify examples are syntactically valid -cd("/var$REPOS_DIR/Cliodynamics.jl") -include("examples/basic_usage.jl") -include("examples/historical_analysis.jl") -println("PASS: examples run without error") -``` - ---- - -## TASK 10: Customize 0-AI-MANIFEST.a2ml (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/0-AI-MANIFEST.a2ml` - -**Problem:** Lines 7-8 still say `[YOUR-REPO-NAME]`. Lines 51-67 have generic placeholder -structure. Lines 112-114 have `[DATE]`, `[YOUR-NAME/ORG]`. The manifest does not describe -the actual Cliodynamics.jl repository. - -**What to do:** -1. Replace all `[YOUR-REPO-NAME]` with `Cliodynamics.jl` (lines 7, 56). -2. Replace the repository structure section (lines 55-68) with the actual structure: - ``` - Cliodynamics.jl/ - ├── 0-AI-MANIFEST.a2ml - ├── README.md - ├── Project.toml - ├── src/ - │ ├── Cliodynamics.jl # Main module (all code) - │ └── abi/ # Idris2 ABI definitions (template) - ├── test/ - │ └── runtests.jl # Test suite - ├── examples/ # Usage examples - ├── ffi/zig/ # Zig FFI (template) - ├── .machine_readable/ # SCM files (6 files) - └── .bot_directives/ # Bot instructions - ``` -3. Set `[DATE]` to `2026-02-07` (line 112). -4. Set `[YOUR-NAME/ORG]` to `Jonathan D.A. Jewell / hyperpolymath` (line 113). - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -! grep -q "\[YOUR-REPO-NAME\]" 0-AI-MANIFEST.a2ml && \ -! grep -q "\[DATE\]" 0-AI-MANIFEST.a2ml && \ -! grep -q "\[YOUR-NAME/ORG\]" 0-AI-MANIFEST.a2ml && \ -grep -q "Cliodynamics" 0-AI-MANIFEST.a2ml && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 11: Replace ROADMAP.adoc with Cliodynamics.jl-specific content (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/ROADMAP.adoc` - -**Problem:** Line 2 says "YOUR Template Repo Roadmap". All milestone items are generic -placeholders. The actual Julia code is at v0.1.0 with all core features implemented. - -**What to do:** -1. Replace the entire file with a roadmap specific to Cliodynamics.jl. -2. Add `// SPDX-License-Identifier: CC-BY-SA-4.0` as line 1 (already present). -3. Mark v0.1.0 milestones as complete: - - Core population dynamics models - - Elite dynamics analysis - - Political stress indicators - - Secular cycle analysis - - State formation models - - Utility functions - - Comprehensive test suite -4. Add v0.2.0 planned milestones: - - Empirical dataset integration (Seshat, CrisisDB) - - Plotting recipes for Plots.jl - - Model fitting to historical data - - Parameter estimation with Optim.jl -5. Add v1.0.0 goals: - - Bayesian inference support (Turing.jl integration) - - Spatial cliodynamic models - - Interactive documentation (Documenter.jl) - - Publication-quality examples - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -! grep -q "YOUR Template" ROADMAP.adoc && \ -grep -q "Cliodynamics" ROADMAP.adoc && \ -grep -q "v0.1.0" ROADMAP.adoc && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 12: Replace README.adoc with Cliodynamics.jl-specific content (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/README.adoc` - -**Problem:** The entire file (134 lines) is the RSR template README describing ReScript, -SafeDOM, Deno, and the ABI/FFI standard. It has nothing to do with cliodynamic modeling. -Line 1: "RSR template repo". Line 43: "Update `[YOUR-REPO-NAME]` placeholders". -Lines 79-133: ReScript SafeDOM documentation. - -**What to do:** -1. Replace the entire file with a brief AsciiDoc version of the Cliodynamics.jl description. -2. Since `README.md` already has the full project description, `README.adoc` should be a - concise pointer that says "See README.md for full documentation" plus a brief summary. -3. Alternatively, DELETE `README.adoc` entirely -- GitHub renders `README.md` by default, - and having both is confusing. If you keep it, make it Cliodynamics-specific. -4. Recommended: Delete `README.adoc` and let `README.md` be the single README. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -# If README.adoc was deleted: -! test -f README.adoc && echo "PASS: README.adoc deleted" || \ -# If README.adoc was kept: -(! grep -q "RSR template" README.adoc && grep -q "Cliodynamics" README.adoc && echo "PASS: README.adoc customized") -``` - ---- - -## TASK 13: Customize ABI Idris2 files for Cliodynamics.jl (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/src/abi/Types.idr` (lines 11, 172-175, 198-202) -- `/var$REPOS_DIR/Cliodynamics.jl/src/abi/Layout.idr` (line 8) -- `/var$REPOS_DIR/Cliodynamics.jl/src/abi/Foreign.idr` (lines 9, 23, 35, 49, 77, 98, 125, 152, 164, 185, 211) - -**Problem:** Every Idris2 file has `{{PROJECT}}` and `{{project}}` placeholders throughout. -Module names are `{{PROJECT}}.ABI.Types`, etc. FFI declarations reference `lib{{project}}`. -These files will not compile. - -**What to do:** -1. In all three `.idr` files, replace `{{PROJECT}}` with `Cliodynamics` (uppercase for module names). -2. Replace `{{project}}` with `cliodynamics` (lowercase for library names and function prefixes). -3. In `Types.idr`: Replace `ExampleStruct` with a cliodynamics-relevant struct, e.g., - `SimulationResult` with fields `time : Double`, `population : Double`, `elites : Double`. - Update the size proofs accordingly. -4. In `Foreign.idr`: Update the FFI function declarations to reflect cliodynamics operations - (e.g., `cliodynamics_init`, `cliodynamics_free`, `cliodynamics_process`). - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -! grep -r "{{PROJECT}}" src/abi/ && \ -! grep -r "{{project}}" src/abi/ && \ -grep -q "Cliodynamics" src/abi/Types.idr && \ -grep -q "Cliodynamics" src/abi/Layout.idr && \ -grep -q "Cliodynamics" src/abi/Foreign.idr && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 14: Customize Zig FFI files for Cliodynamics.jl (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/src/main.zig` (lines 1, 12, 54, 73, 89, 113, 135, 148, 184, 198, 203, 215, 245, 256, 259, 263, 266, 271, 272) -- `/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/build.zig` (lines 1, 12, 34, 37) -- `/var$REPOS_DIR/Cliodynamics.jl/ffi/zig/test/integration_test.zig` (lines 1, 10-17, 24-25, 31-32, 34, 39, 48-49, 51, 56, 65-66, 68-69, 75, 84, 96-97, 99, 110, 118, 129-130, 131, 138-139, 143, 145-146, 149, 158-159, 168, 174) - -**Problem:** Every Zig file has `{{project}}` and `{{PROJECT}}` template placeholders. -Function names like `{{project}}_init()`, library name `"{{project}}"`, etc. These files -will not compile. - -**What to do:** -1. In all three `.zig` files, replace `{{project}}` with `cliodynamics` (lowercase). -2. Replace `{{PROJECT}}` with `Cliodynamics` (where used as display name). -3. In `build.zig` line 34: The header reference `include/{{project}}.h` should become - `include/cliodynamics.h`. Note: this header file does not exist yet -- that is acceptable - for template infrastructure. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -! grep -r "{{project}}" ffi/ && \ -! grep -r "{{PROJECT}}" ffi/ && \ -grep -q "cliodynamics" ffi/zig/src/main.zig && \ -grep -q "cliodynamics" ffi/zig/build.zig && \ -grep -q "cliodynamics" ffi/zig/test/integration_test.zig && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 15: Update AGENTIC.scm with Cliodynamics.jl specifics (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/AGENTIC.scm` - -**Problem:** Line 7 references `claude-opus-4-5-20251101` (outdated model ID). The `languages` -constraint on line 15 is empty. The file should reflect Julia-specific patterns. - -**What to do:** -1. Update model to `"claude-opus-4-6"` (current model per system info). -2. Set `languages` to `("julia")`. -3. Add constraint `(primary-runtime . "julia")`. -4. Keep `banned` languages list as is. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable -grep -q "julia" AGENTIC.scm && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 16: Update PLAYBOOK.scm with Julia procedures (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.machine_readable/PLAYBOOK.scm` - -**Problem:** Lines 7-9 reference `just build`, `just test`, `just release` but there is no -`justfile` in the repository. The correct Julia commands should be used. - -**What to do:** -1. Change build procedure to `"julia --project=. -e 'using Pkg; Pkg.instantiate()'"`. -2. Change test procedure to `"julia --project=. -e 'using Pkg; Pkg.test()'"`. -3. Change release procedure to `"julia --project=. -e 'using Pkg; Pkg.build()'"`. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl/.machine_readable -grep -q "Pkg.test" PLAYBOOK.scm && \ -! grep -q "just " PLAYBOOK.scm && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 17: Remove sync report file (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/sync_report_20260210_160611.txt` - -**Problem:** This appears to be a generated sync report that should not be tracked in git. -It is not part of the project. - -**What to do:** -1. Delete `sync_report_20260210_160611.txt`. -2. Add `sync_report_*.txt` to `.gitignore` to prevent future occurrences. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -! test -f sync_report_20260210_160611.txt && \ -grep -q "sync_report" .gitignore && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 18: Add `.claude/CLAUDE.md` for project-specific instructions (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliodynamics.jl/.claude/CLAUDE.md` (new file) - -**Problem:** No project-specific CLAUDE.md exists. This file should describe how to work -with this Julia package. - -**What to do:** -1. Create `.claude/` directory. -2. Create `.claude/CLAUDE.md` with: - - Project description: Julia package for cliodynamic modeling - - Build command: `julia --project=. -e 'using Pkg; Pkg.instantiate()'` - - Test command: `julia --project=. -e 'using Pkg; Pkg.test()'` - - Code style: Julia conventions, docstrings on all exports, `@testset` structure - - Architecture note: single-file module in `src/Cliodynamics.jl` - - Dependencies: DifferentialEquations.jl, DataFrames.jl, Optim.jl, Statistics, LinearAlgebra - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliodynamics.jl -test -f .claude/CLAUDE.md && \ -grep -q "Cliodynamics" .claude/CLAUDE.md && \ -grep -q "Pkg.test" .claude/CLAUDE.md && \ -echo "PASS" || echo "FAIL" -``` - ---- - -## FINAL VERIFICATION - -After all tasks are complete, run this comprehensive check: - -```bash -cd /var$REPOS_DIR/Cliodynamics.jl - -echo "=== 1. SCM directory structure ===" -ls -la .machine_readable/ && ! test -d .machines_readable && echo "OK" || echo "FAIL" - -echo "" -echo "=== 2. No AGPL references ===" -grep -r "AGPL" .machine_readable/ ffi/ src/abi/ && echo "FAIL" || echo "OK" - -echo "" -echo "=== 3. No template placeholders ===" -grep -r "{{project}}\|{{PROJECT}}\|\[YOUR-REPO-NAME\]\|\[TODO\]" \ - .machine_readable/ src/abi/ ffi/ 0-AI-MANIFEST.a2ml ROADMAP.adoc && echo "FAIL" || echo "OK" - -echo "" -echo "=== 4. No rsr-template-repo references in SCM ===" -grep -r "rsr-template-repo" .machine_readable/ && echo "FAIL" || echo "OK" - -echo "" -echo "=== 5. No ReScript/Deno examples ===" -! test -f examples/SafeDOMExample.res && ! test -f examples/web-project-deno.json && echo "OK" || echo "FAIL" - -echo "" -echo "=== 6. Julia examples exist ===" -test -f examples/basic_usage.jl && test -f examples/historical_analysis.jl && echo "OK" || echo "FAIL" - -echo "" -echo "=== 7. No Plots in Project.toml ===" -! grep -q "Plots" Project.toml && echo "OK" || echo "FAIL" - -echo "" -echo "=== 8. No sync report ===" -! test -f sync_report_20260210_160611.txt && echo "OK" || echo "FAIL" - -echo "" -echo "=== 9. CLAUDE.md exists ===" -test -f .claude/CLAUDE.md && echo "OK" || echo "FAIL" -``` - -```julia -# Full Julia test suite -cd("/var$REPOS_DIR/Cliodynamics.jl") -using Pkg -Pkg.activate(".") -Pkg.instantiate() -Pkg.test() -println("ALL JULIA TESTS PASSED") -``` - -After final verification passes, update `.machine_readable/STATE.scm` to set -`overall-completion` to `95` (the remaining 5% is for Documenter.jl setup, -CI/CD Julia workflow, and package registration). diff --git a/packages/Cliodynamics.jl/TOPOLOGY.md b/packages/Cliodynamics.jl/TOPOLOGY.adoc similarity index 89% rename from packages/Cliodynamics.jl/TOPOLOGY.md rename to packages/Cliodynamics.jl/TOPOLOGY.adoc index 8b792ddd9..3e52e2d55 100644 --- a/packages/Cliodynamics.jl/TOPOLOGY.md +++ b/packages/Cliodynamics.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Cliodynamics.jl — Project Topology -# Cliodynamics.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml, Manifest.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE MODELS @@ -70,11 +66,11 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Production Release (v1.0.0) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Population Dynamics ───► Elite Dynamics ───► Political Stress │ Secular Cycles ◀─────────────────────────────────┘ @@ -82,16 +78,17 @@ Secular Cycles ◀──────────────────── Spatial Models ──────► Fitting Engine ──────► Bayesian Inference │ COMPLETE (v1.0.0) -``` +.... -## 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/packages/Cliodynamics.jl/docs/src/api.md b/packages/Cliodynamics.jl/docs/src/api.adoc similarity index 65% rename from packages/Cliodynamics.jl/docs/src/api.md rename to packages/Cliodynamics.jl/docs/src/api.adoc index 38bfc0345..ce428426e 100644 --- a/packages/Cliodynamics.jl/docs/src/api.md +++ b/packages/Cliodynamics.jl/docs/src/api.adoc @@ -1,27 +1,30 @@ -# API Reference +== API Reference -## Types +=== Types -```@docs +[source,@docs] +---- MalthusianParams DemographicStructuralParams StateCapacityParams SecularCyclePhase InstabilityEvent -``` +---- -## Models +=== Models -```@docs +[source,@docs] +---- malthusian_model demographic_structural_model state_capacity_model collective_action_problem -``` +---- -## Indicators +=== Indicators -```@docs +[source,@docs] +---- elite_overproduction_index political_stress_indicator instability_probability @@ -30,42 +33,47 @@ crisis_threshold instability_events population_pressure carrying_capacity_estimate -``` +---- -## Secular Cycles +=== Secular Cycles -```@docs +[source,@docs] +---- secular_cycle_analysis detect_cycle_phases -``` +---- -## Model Fitting +=== Model Fitting -```@docs +[source,@docs] +---- fit_malthusian fit_demographic_structural estimate_parameters -``` +---- -## Data Integration +=== Data Integration -```@docs +[source,@docs] +---- load_seshat_csv prepare_seshat_data -``` +---- -## Utilities +=== Utilities -```@docs +[source,@docs] +---- moving_average detrend normalize_timeseries -``` +---- -## Spatial Models +=== Spatial Models -```@docs +[source,@docs] +---- spatial_instability_diffusion territorial_competition_model frontier_formation_index -``` +---- diff --git a/packages/Cliodynamics.jl/docs/src/data.adoc b/packages/Cliodynamics.jl/docs/src/data.adoc new file mode 100644 index 000000000..02766c545 --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/data.adoc @@ -0,0 +1,57 @@ +== Data Integration + +=== Seshat Global History Databank + +https://seshatdatabank.info/[Seshat] is a large-scale, systematic +database of historical and archaeological data covering hundreds of +polities across millennia. Cliodynamics.jl provides functions to load +and prepare Seshat-format data for analysis. + +==== Loading Data + +[source,@docs] +---- +load_seshat_csv +---- + +==== Preparing Data + +[source,@docs] +---- +prepare_seshat_data +---- + +==== Example Pipeline + +[source,julia] +---- +using Cliodynamics +using DataFrames + +# Load raw data +raw = load_seshat_csv("data/seshat_sample.csv") + +# Filter to Roman polities +roman = prepare_seshat_data(raw) +roman = filter(row -> occursin("Rom", string(row.polity)), roman) +sort!(roman, :year) + +# Compute elite overproduction across Roman history +eoi = elite_overproduction_index(roman) + +# Fit population model to English data +english = filter(row -> occursin("Eng", string(row.polity)), prepare_seshat_data(raw)) +sort!(english, :year) +fit = fit_malthusian(Float64.(english.year), Float64.(english.population), + r_init=0.005, K_init=2_000_000.0) +---- + +=== Data Format + +Seshat CSV files support: - Comment lines starting with `+#+` - Standard +header row with column names - Automatic numeric type detection + +Required columns vary by analysis function. Common columns: - `+year+` — +Calendar year (negative for BCE) - `+polity+` — Polity identifier - +`+population+` — Population count - `+elites+` — Elite population count +- `+territory+` — Territorial extent diff --git a/packages/Cliodynamics.jl/docs/src/data.md b/packages/Cliodynamics.jl/docs/src/data.md deleted file mode 100644 index be31730b6..000000000 --- a/packages/Cliodynamics.jl/docs/src/data.md +++ /dev/null @@ -1,55 +0,0 @@ -# Data Integration - -## Seshat Global History Databank - -[Seshat](https://seshatdatabank.info/) is a large-scale, systematic database of historical and archaeological data covering hundreds of polities across millennia. Cliodynamics.jl provides functions to load and prepare Seshat-format data for analysis. - -### Loading Data - -```@docs -load_seshat_csv -``` - -### Preparing Data - -```@docs -prepare_seshat_data -``` - -### Example Pipeline - -```julia -using Cliodynamics -using DataFrames - -# Load raw data -raw = load_seshat_csv("data/seshat_sample.csv") - -# Filter to Roman polities -roman = prepare_seshat_data(raw) -roman = filter(row -> occursin("Rom", string(row.polity)), roman) -sort!(roman, :year) - -# Compute elite overproduction across Roman history -eoi = elite_overproduction_index(roman) - -# Fit population model to English data -english = filter(row -> occursin("Eng", string(row.polity)), prepare_seshat_data(raw)) -sort!(english, :year) -fit = fit_malthusian(Float64.(english.year), Float64.(english.population), - r_init=0.005, K_init=2_000_000.0) -``` - -## Data Format - -Seshat CSV files support: -- Comment lines starting with `#` -- Standard header row with column names -- Automatic numeric type detection - -Required columns vary by analysis function. Common columns: -- `year` — Calendar year (negative for BCE) -- `polity` — Polity identifier -- `population` — Population count -- `elites` — Elite population count -- `territory` — Territorial extent diff --git a/packages/Cliodynamics.jl/docs/src/fitting.md b/packages/Cliodynamics.jl/docs/src/fitting.adoc similarity index 77% rename from packages/Cliodynamics.jl/docs/src/fitting.md rename to packages/Cliodynamics.jl/docs/src/fitting.adoc index 050b0a59d..293654d32 100644 --- a/packages/Cliodynamics.jl/docs/src/fitting.md +++ b/packages/Cliodynamics.jl/docs/src/fitting.adoc @@ -1,32 +1,37 @@ -# Model Fitting +== Model Fitting -## Malthusian Fitting +=== Malthusian Fitting Recover growth rate and carrying capacity from observed population data: -```@docs +[source,@docs] +---- fit_malthusian -``` +---- -## Demographic-Structural Fitting +=== Demographic-Structural Fitting -Fit the full DST model to historical time series with population, elite, and state capacity data: +Fit the full DST model to historical time series with population, elite, +and state capacity data: -```@docs +[source,@docs] +---- fit_demographic_structural -``` +---- -## Generic Parameter Estimation +=== Generic Parameter Estimation Fit arbitrary models with bootstrap confidence intervals: -```@docs +[source,@docs] +---- estimate_parameters -``` +---- -### Example +==== Example -```julia +[source,julia] +---- using Cliodynamics # Define a custom growth model @@ -41,4 +46,4 @@ result = estimate_parameters(model_fn, observed, years, [80.0, 0.01], n_bootstra println("A = $(round(result.params[1], digits=1)) [$(round(result.ci_lower[1], digits=1)), $(round(result.ci_upper[1], digits=1))]") println("r = $(round(result.params[2], digits=5)) [$(round(result.ci_lower[2], digits=5)), $(round(result.ci_upper[2], digits=5))]") -``` +---- diff --git a/packages/Cliodynamics.jl/docs/src/index.adoc b/packages/Cliodynamics.jl/docs/src/index.adoc new file mode 100644 index 000000000..4f156c384 --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/index.adoc @@ -0,0 +1,67 @@ +== Cliodynamics.jl + +_Mathematical modeling and statistical analysis of historical dynamics._ + +=== What is Cliodynamics? + +Cliodynamics is the scientific study of historical dynamics — applying +mathematical models and quantitative methods to understand long-term +patterns in social complexity, state formation, demographic cycles, +elite dynamics, and political instability. + +This package implements frameworks from Peter Turchin’s cliodynamics +research program, providing Julia tools for: + +* *Population dynamics* — Malthusian models, demographic-structural +theory +* *Elite dynamics* — Overproduction indices, intra-elite competition +* *Political instability* — Stress indicators, conflict intensity, +instability probability +* *Secular cycles* — 150-300 year oscillation detection and phase +classification +* *State formation* — Capacity models, collective action problems +* *Spatial models* — Multi-region interaction, instability diffusion +* *Model fitting* — Parameter estimation with bootstrap confidence +intervals +* *Data integration* — Seshat Global History Databank support + +=== Installation + +[source,julia] +---- +using Pkg +Pkg.add("Cliodynamics") +---- + +=== Quick Start + +[source,julia] +---- +using Cliodynamics +using DataFrames + +# Model Malthusian population dynamics +params = MalthusianParams(r=0.02, K=1000.0, N0=100.0) +sol = malthusian_model(params, tspan=(0.0, 200.0)) +println("Population at t=200: ", round(sol(200.0)[1], digits=1)) + +# Calculate elite overproduction +data = DataFrame( + year = 1800:1900, + population = collect(100_000:1000:200_000), + elites = [1000 + 10*i + 5*i^1.5 for i in 0:100] +) +eoi = elite_overproduction_index(data) +println("Final EOI: ", round(eoi.eoi[end], digits=3)) +---- + +See the link:@ref[Tutorial] for a comprehensive walkthrough. + +=== References + +* Turchin, P. (2003). _Historical Dynamics: Why States Rise and Fall_. +Princeton University Press. +* Turchin, P. (2016). _Ages of Discord_. Beresta Books. +* Turchin, P. & Nefedov, S. A. (2009). _Secular Cycles_. Princeton +University Press. +* Turchin, P. (2023). _End Times_. Penguin Press. diff --git a/packages/Cliodynamics.jl/docs/src/index.md b/packages/Cliodynamics.jl/docs/src/index.md deleted file mode 100644 index 0d787e2ad..000000000 --- a/packages/Cliodynamics.jl/docs/src/index.md +++ /dev/null @@ -1,55 +0,0 @@ -# Cliodynamics.jl - -*Mathematical modeling and statistical analysis of historical dynamics.* - -## What is Cliodynamics? - -Cliodynamics is the scientific study of historical dynamics — applying mathematical models and quantitative methods to understand long-term patterns in social complexity, state formation, demographic cycles, elite dynamics, and political instability. - -This package implements frameworks from Peter Turchin's cliodynamics research program, providing Julia tools for: - -- **Population dynamics** — Malthusian models, demographic-structural theory -- **Elite dynamics** — Overproduction indices, intra-elite competition -- **Political instability** — Stress indicators, conflict intensity, instability probability -- **Secular cycles** — 150-300 year oscillation detection and phase classification -- **State formation** — Capacity models, collective action problems -- **Spatial models** — Multi-region interaction, instability diffusion -- **Model fitting** — Parameter estimation with bootstrap confidence intervals -- **Data integration** — Seshat Global History Databank support - -## Installation - -```julia -using Pkg -Pkg.add("Cliodynamics") -``` - -## Quick Start - -```julia -using Cliodynamics -using DataFrames - -# Model Malthusian population dynamics -params = MalthusianParams(r=0.02, K=1000.0, N0=100.0) -sol = malthusian_model(params, tspan=(0.0, 200.0)) -println("Population at t=200: ", round(sol(200.0)[1], digits=1)) - -# Calculate elite overproduction -data = DataFrame( - year = 1800:1900, - population = collect(100_000:1000:200_000), - elites = [1000 + 10*i + 5*i^1.5 for i in 0:100] -) -eoi = elite_overproduction_index(data) -println("Final EOI: ", round(eoi.eoi[end], digits=3)) -``` - -See the [Tutorial](@ref) for a comprehensive walkthrough. - -## References - -- Turchin, P. (2003). *Historical Dynamics: Why States Rise and Fall*. Princeton University Press. -- Turchin, P. (2016). *Ages of Discord*. Beresta Books. -- Turchin, P. & Nefedov, S. A. (2009). *Secular Cycles*. Princeton University Press. -- Turchin, P. (2023). *End Times*. Penguin Press. diff --git a/packages/Cliodynamics.jl/docs/src/models/cycles.adoc b/packages/Cliodynamics.jl/docs/src/models/cycles.adoc new file mode 100644 index 000000000..5cbe12a42 --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/models/cycles.adoc @@ -0,0 +1,33 @@ +== Secular Cycles + +=== Overview + +Secular cycles are long-term oscillations (150-300 years) identified by +Turchin and Nefedov in agrarian societies. Each cycle passes through +four phases: + +[arabic] +. *Expansion*: Low population pressure, state strengthening, prosperity +. *Stagflation*: Rising pressure, elite overproduction begins +. *Crisis*: Political instability, state breakdown, conflict +. *Depression/Intercycle*: Population decline, elite winnowing, recovery + +=== Cycle Analysis + +Detect secular cycles in time series data using trend-cycle +decomposition: + +[source,@docs] +---- +secular_cycle_analysis +---- + +=== Phase Detection + +Classify each time point into one of the four secular cycle phases: + +[source,@docs] +---- +SecularCyclePhase +detect_cycle_phases +---- diff --git a/packages/Cliodynamics.jl/docs/src/models/cycles.md b/packages/Cliodynamics.jl/docs/src/models/cycles.md deleted file mode 100644 index e567f40e7..000000000 --- a/packages/Cliodynamics.jl/docs/src/models/cycles.md +++ /dev/null @@ -1,27 +0,0 @@ -# Secular Cycles - -## Overview - -Secular cycles are long-term oscillations (150-300 years) identified by Turchin and Nefedov in agrarian societies. Each cycle passes through four phases: - -1. **Expansion**: Low population pressure, state strengthening, prosperity -2. **Stagflation**: Rising pressure, elite overproduction begins -3. **Crisis**: Political instability, state breakdown, conflict -4. **Depression/Intercycle**: Population decline, elite winnowing, recovery - -## Cycle Analysis - -Detect secular cycles in time series data using trend-cycle decomposition: - -```@docs -secular_cycle_analysis -``` - -## Phase Detection - -Classify each time point into one of the four secular cycle phases: - -```@docs -SecularCyclePhase -detect_cycle_phases -``` diff --git a/packages/Cliodynamics.jl/docs/src/models/elites.md b/packages/Cliodynamics.jl/docs/src/models/elites.adoc similarity index 53% rename from packages/Cliodynamics.jl/docs/src/models/elites.md rename to packages/Cliodynamics.jl/docs/src/models/elites.adoc index 5f9938d14..1380db4d5 100644 --- a/packages/Cliodynamics.jl/docs/src/models/elites.md +++ b/packages/Cliodynamics.jl/docs/src/models/elites.adoc @@ -1,24 +1,31 @@ -# Elite Dynamics +== Elite Dynamics -## Elite Overproduction Index +=== Elite Overproduction Index -The EOI measures when the supply of elite aspirants exceeds available elite positions: +The EOI measures when the supply of elite aspirants exceeds available +elite positions: -```math +[source,math] +---- \text{EOI} = \frac{E/N}{(E/N)_{\text{baseline}}} - 1 -``` +---- -Positive values indicate overproduction — more elite aspirants than the system can absorb, leading to intra-elite competition and political instability. +Positive values indicate overproduction — more elite aspirants than the +system can absorb, leading to intra-elite competition and political +instability. -```@docs +[source,@docs] +---- elite_overproduction_index -``` +---- -## Instability Events +=== Instability Events -Extract discrete instability events from continuous indicator time series: +Extract discrete instability events from continuous indicator time +series: -```@docs +[source,@docs] +---- InstabilityEvent instability_events -``` +---- diff --git a/packages/Cliodynamics.jl/docs/src/models/instability.adoc b/packages/Cliodynamics.jl/docs/src/models/instability.adoc new file mode 100644 index 000000000..5b7d648f0 --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/models/instability.adoc @@ -0,0 +1,47 @@ +== Political Instability + +=== Political Stress Indicator + +The PSI is a composite index combining three destabilizing forces: + +[source,math] +---- +\text{PSI} = 0.4 \cdot \text{MMP} + 0.4 \cdot \text{EMP} + 0.2 \cdot \text{SFD} +---- + +where: - *MMP* (Mass Mobilization Potential): Popular immiseration from +wage decline - *EMP* (Elite Mobilization Potential): Elite +overproduction and competition - *SFD* (State Fiscal Distress): Revenue +crisis undermining state capacity + +[source,@docs] +---- +political_stress_indicator +---- + +=== Instability Probability + +Convert continuous stress indicators into event probabilities using a +sigmoid function: + +[source,@docs] +---- +instability_probability +---- + +=== Conflict Intensity + +Aggregate discrete instability events into a continuous conflict +intensity measure over time: + +[source,@docs] +---- +conflict_intensity +---- + +=== Crisis Detection + +[source,@docs] +---- +crisis_threshold +---- diff --git a/packages/Cliodynamics.jl/docs/src/models/instability.md b/packages/Cliodynamics.jl/docs/src/models/instability.md deleted file mode 100644 index a8e30cfb4..000000000 --- a/packages/Cliodynamics.jl/docs/src/models/instability.md +++ /dev/null @@ -1,40 +0,0 @@ -# Political Instability - -## Political Stress Indicator - -The PSI is a composite index combining three destabilizing forces: - -```math -\text{PSI} = 0.4 \cdot \text{MMP} + 0.4 \cdot \text{EMP} + 0.2 \cdot \text{SFD} -``` - -where: -- **MMP** (Mass Mobilization Potential): Popular immiseration from wage decline -- **EMP** (Elite Mobilization Potential): Elite overproduction and competition -- **SFD** (State Fiscal Distress): Revenue crisis undermining state capacity - -```@docs -political_stress_indicator -``` - -## Instability Probability - -Convert continuous stress indicators into event probabilities using a sigmoid function: - -```@docs -instability_probability -``` - -## Conflict Intensity - -Aggregate discrete instability events into a continuous conflict intensity measure over time: - -```@docs -conflict_intensity -``` - -## Crisis Detection - -```@docs -crisis_threshold -``` diff --git a/packages/Cliodynamics.jl/docs/src/models/population.adoc b/packages/Cliodynamics.jl/docs/src/models/population.adoc new file mode 100644 index 000000000..9b106dfef --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/models/population.adoc @@ -0,0 +1,45 @@ +== Population Dynamics + +=== Malthusian Model + +The Malthusian logistic growth model describes population dynamics +constrained by carrying capacity: + +[source,math] +---- +\frac{dN}{dt} = rN\left(1 - \frac{N}{K}\right) +---- + +where: - `+N+` = population size - `+r+` = intrinsic growth rate - `+K+` += carrying capacity (resource-limited maximum) + +[source,@docs] +---- +MalthusianParams +malthusian_model +---- + +=== Demographic-Structural Theory + +The DST model couples three state variables in a system of ODEs: + +* *Population* (`+N+`): Grows logistically, modulated by state capacity +* *Elites* (`+E+`): Produced from population, subject to competition +* *State capacity* (`+S+`): Revenue from taxation, eroded by elite +demands + +[source,@docs] +---- +DemographicStructuralParams +demographic_structural_model +---- + +=== Population Pressure + +Measure demographic stress relative to carrying capacity: + +[source,@docs] +---- +population_pressure +carrying_capacity_estimate +---- diff --git a/packages/Cliodynamics.jl/docs/src/models/population.md b/packages/Cliodynamics.jl/docs/src/models/population.md deleted file mode 100644 index efe3cd7b9..000000000 --- a/packages/Cliodynamics.jl/docs/src/models/population.md +++ /dev/null @@ -1,41 +0,0 @@ -# Population Dynamics - -## Malthusian Model - -The Malthusian logistic growth model describes population dynamics constrained by carrying capacity: - -```math -\frac{dN}{dt} = rN\left(1 - \frac{N}{K}\right) -``` - -where: -- ``N`` = population size -- ``r`` = intrinsic growth rate -- ``K`` = carrying capacity (resource-limited maximum) - -```@docs -MalthusianParams -malthusian_model -``` - -## Demographic-Structural Theory - -The DST model couples three state variables in a system of ODEs: - -- **Population** (``N``): Grows logistically, modulated by state capacity -- **Elites** (``E``): Produced from population, subject to competition -- **State capacity** (``S``): Revenue from taxation, eroded by elite demands - -```@docs -DemographicStructuralParams -demographic_structural_model -``` - -## Population Pressure - -Measure demographic stress relative to carrying capacity: - -```@docs -population_pressure -carrying_capacity_estimate -``` diff --git a/packages/Cliodynamics.jl/docs/src/models/spatial.adoc b/packages/Cliodynamics.jl/docs/src/models/spatial.adoc new file mode 100644 index 000000000..a6b243888 --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/models/spatial.adoc @@ -0,0 +1,36 @@ +== Spatial Models + +Spatial cliodynamic models extend single-polity analysis to multi-region +systems where instability, population pressure, and elite competition +diffuse across borders. + +!!! note "`v1.0.0 Feature`" Spatial models are available from +Cliodynamics.jl v1.0.0 onwards. + +=== Multi-Region Interaction + +Model how instability in one region propagates to neighbors: + +[source,@docs] +---- +spatial_instability_diffusion +---- + +=== Territorial Competition + +Model state competition over territory and resources: + +[source,@docs] +---- +territorial_competition_model +---- + +=== Frontier Effects + +Model the meta-ethnic frontier thesis — states form most readily at +boundaries between culturally distinct groups: + +[source,@docs] +---- +frontier_formation_index +---- diff --git a/packages/Cliodynamics.jl/docs/src/models/spatial.md b/packages/Cliodynamics.jl/docs/src/models/spatial.md deleted file mode 100644 index b4e15ae08..000000000 --- a/packages/Cliodynamics.jl/docs/src/models/spatial.md +++ /dev/null @@ -1,30 +0,0 @@ -# Spatial Models - -Spatial cliodynamic models extend single-polity analysis to multi-region systems where instability, population pressure, and elite competition diffuse across borders. - -!!! note "v1.0.0 Feature" - Spatial models are available from Cliodynamics.jl v1.0.0 onwards. - -## Multi-Region Interaction - -Model how instability in one region propagates to neighbors: - -```@docs -spatial_instability_diffusion -``` - -## Territorial Competition - -Model state competition over territory and resources: - -```@docs -territorial_competition_model -``` - -## Frontier Effects - -Model the meta-ethnic frontier thesis — states form most readily at boundaries between culturally distinct groups: - -```@docs -frontier_formation_index -``` diff --git a/packages/Cliodynamics.jl/docs/src/models/state.adoc b/packages/Cliodynamics.jl/docs/src/models/state.adoc new file mode 100644 index 000000000..2b6d45100 --- /dev/null +++ b/packages/Cliodynamics.jl/docs/src/models/state.adoc @@ -0,0 +1,31 @@ +== State Formation + +=== State Capacity Model + +Models state capacity as a function of population size (tax base) and +elite demands: + +[source,math] +---- +S = \tau \cdot \alpha \cdot N^\beta - \gamma \cdot E +---- + +where: - `+\tau+` = tax rate - `+\alpha+` = administrative efficiency - +`+N+` = population, `+\beta+` = returns to scale - `+\gamma+` = elite +cost coefficient, `+E+` = elite population + +[source,@docs] +---- +StateCapacityParams +state_capacity_model +---- + +=== Collective Action + +Models the probability of successful collective action as a function of +group size, benefit, and cost: + +[source,@docs] +---- +collective_action_problem +---- diff --git a/packages/Cliodynamics.jl/docs/src/models/state.md b/packages/Cliodynamics.jl/docs/src/models/state.md deleted file mode 100644 index 40a1d8f0d..000000000 --- a/packages/Cliodynamics.jl/docs/src/models/state.md +++ /dev/null @@ -1,28 +0,0 @@ -# State Formation - -## State Capacity Model - -Models state capacity as a function of population size (tax base) and elite demands: - -```math -S = \tau \cdot \alpha \cdot N^\beta - \gamma \cdot E -``` - -where: -- ``\tau`` = tax rate -- ``\alpha`` = administrative efficiency -- ``N`` = population, ``\beta`` = returns to scale -- ``\gamma`` = elite cost coefficient, ``E`` = elite population - -```@docs -StateCapacityParams -state_capacity_model -``` - -## Collective Action - -Models the probability of successful collective action as a function of group size, benefit, and cost: - -```@docs -collective_action_problem -``` diff --git a/packages/Cliodynamics.jl/docs/src/plotting.md b/packages/Cliodynamics.jl/docs/src/plotting.adoc similarity index 62% rename from packages/Cliodynamics.jl/docs/src/plotting.md rename to packages/Cliodynamics.jl/docs/src/plotting.adoc index 91488b825..837ecdac6 100644 --- a/packages/Cliodynamics.jl/docs/src/plotting.md +++ b/packages/Cliodynamics.jl/docs/src/plotting.adoc @@ -1,57 +1,65 @@ -# Plotting +== Plotting -Cliodynamics.jl provides plot recipes via a package extension that loads automatically when `Plots.jl` (or `RecipesBase`) is available. +Cliodynamics.jl provides plot recipes via a package extension that loads +automatically when `+Plots.jl+` (or `+RecipesBase+`) is available. -## Usage +=== Usage -```julia +[source,julia] +---- using Cliodynamics using Plots # Triggers extension loading -``` +---- -## Available Recipes +=== Available Recipes -### Political Stress Indicator +==== Political Stress Indicator -```julia +[source,julia] +---- psi_result = political_stress_indicator(data) plot(psi_result, Val(:psi)) -``` +---- Shows PSI composite line with MMP, EMP, and SFD component breakdown. -### Elite Overproduction Index +==== Elite Overproduction Index -```julia +[source,julia] +---- eoi_result = elite_overproduction_index(data) plot(eoi_result, Val(:eoi)) -``` +---- Shows EOI with zero baseline and filled area. -### Secular Cycle Decomposition +==== Secular Cycle Decomposition -```julia +[source,julia] +---- analysis = secular_cycle_analysis(timeseries, window=30) plot(analysis, Val(:secular_cycle)) -``` +---- Two-panel layout showing trend and cycle components. -### Cycle Phase Timeline +==== Cycle Phase Timeline -```julia +[source,julia] +---- phases = detect_cycle_phases(data) plot(phases, Val(:phases)) -``` +---- -Scatter plot with phases color-coded: green (Expansion), yellow (Stagflation), red (Crisis), blue (Depression). +Scatter plot with phases color-coded: green (Expansion), yellow +(Stagflation), red (Crisis), blue (Depression). -### Conflict Intensity +==== Conflict Intensity -```julia +[source,julia] +---- intensity = conflict_intensity(events, window=10) plot(intensity, Val(:conflict)) -``` +---- Filled area plot of conflict intensity over time. diff --git a/packages/Cliodynamics.jl/docs/src/tutorial.md b/packages/Cliodynamics.jl/docs/src/tutorial.adoc similarity index 84% rename from packages/Cliodynamics.jl/docs/src/tutorial.md rename to packages/Cliodynamics.jl/docs/src/tutorial.adoc index 656947005..64481ea1c 100644 --- a/packages/Cliodynamics.jl/docs/src/tutorial.md +++ b/packages/Cliodynamics.jl/docs/src/tutorial.adoc @@ -1,12 +1,14 @@ -# Tutorial +== Tutorial -This tutorial walks through the core features of Cliodynamics.jl, from basic population models to full historical analysis pipelines. +This tutorial walks through the core features of Cliodynamics.jl, from +basic population models to full historical analysis pipelines. -## Population Dynamics +=== Population Dynamics The simplest model is Malthusian logistic growth: -```julia +[source,julia] +---- using Cliodynamics params = MalthusianParams(r=0.02, K=1000.0, N0=100.0) @@ -16,13 +18,15 @@ sol = malthusian_model(params, tspan=(0.0, 200.0)) println("t=0: ", round(sol(0.0)[1], digits=1)) println("t=100: ", round(sol(100.0)[1], digits=1)) println("t=200: ", round(sol(200.0)[1], digits=1)) -``` +---- -## Demographic-Structural Theory +=== Demographic-Structural Theory -The DST model couples population, elites, and state capacity in a system of ODEs: +The DST model couples population, elites, and state capacity in a system +of ODEs: -```julia +[source,julia] +---- params = DemographicStructuralParams( r=0.015, K=1000.0, w=2.0, δ=0.03, ε=0.001, N0=500.0, E0=10.0, S0=100.0 @@ -32,13 +36,14 @@ sol = demographic_structural_model(params, tspan=(0.0, 300.0)) # Three state variables: Population, Elites, State capacity state = sol(150.0) println("N=$(round(state[1],digits=1)), E=$(round(state[2],digits=1)), S=$(round(state[3],digits=1))") -``` +---- -## Elite Overproduction +=== Elite Overproduction Compute when elite numbers outpace available positions: -```julia +[source,julia] +---- using DataFrames data = DataFrame( @@ -49,13 +54,14 @@ data = DataFrame( eoi = elite_overproduction_index(data) # eoi.eoi contains the index values (positive = overproduction) -``` +---- -## Political Stress Indicator +=== Political Stress Indicator The PSI combines three destabilizing forces: -```julia +[source,julia] +---- stress_data = DataFrame( year = 1800:1900, real_wages = 100.0 .- collect(0:100).^1.2 ./ 10, @@ -65,25 +71,28 @@ stress_data = DataFrame( psi = political_stress_indicator(stress_data) # psi.psi = composite, psi.mmp, psi.emp, psi.sfd = components -``` +---- -## Secular Cycle Analysis +=== Secular Cycle Analysis Detect long-term oscillations and classify phases: -```julia +[source,julia] +---- # Detect cycles in time series data timeseries = 100.0 .+ 50.0 .* sin.(2π .* (1:300) ./ 100) .+ 2 .* randn(300) analysis = secular_cycle_analysis(Float64.(timeseries), window=30) println("Period: ", analysis.period, " years") println("Amplitude: ", round(analysis.amplitude, digits=2)) -``` +---- -## Seshat Data Integration +=== Seshat Data Integration -Load and analyze historical data from the Seshat Global History Databank: +Load and analyze historical data from the Seshat Global History +Databank: -```julia +[source,julia] +---- raw = load_seshat_csv("data/seshat_sample.csv") roman = prepare_seshat_data(raw, polity="RomPrinworlds") @@ -91,13 +100,14 @@ roman = prepare_seshat_data(raw, polity="RomPrinworlds") roman_all = filter(row -> occursin("Rom", string(row.polity)), prepare_seshat_data(raw)) sort!(roman_all, :year) eoi = elite_overproduction_index(roman_all) -``` +---- -## Model Fitting +=== Model Fitting Recover parameters from observed data: -```julia +[source,julia] +---- # Fit Malthusian model years = collect(0.0:10.0:100.0) population = [50.0 * exp(0.03 * t) for t in years] @@ -108,13 +118,14 @@ println("Fitted r=$(round(result.params.r, digits=4))") model_fn(p, t) = p[1] .* exp.(p[2] .* (t .- t[1])) est = estimate_parameters(model_fn, population, years, [50.0, 0.02], n_bootstrap=200) println("95% CI for r: [$(round(est.ci_lower[2], digits=5)), $(round(est.ci_upper[2], digits=5))]") -``` +---- -## Plotting +=== Plotting When Plots.jl is loaded, plot recipes activate automatically: -```julia +[source,julia] +---- using Plots # PSI with component breakdown @@ -125,4 +136,4 @@ plot(eoi, Val(:eoi)) # Secular cycle decomposition plot(analysis, Val(:secular_cycle)) -``` +---- diff --git a/packages/Cliometrics.jl/ABI-FFI-README.md b/packages/Cliometrics.jl/ABI-FFI-README.adoc similarity index 74% rename from packages/Cliometrics.jl/ABI-FFI-README.md rename to packages/Cliometrics.jl/ABI-FFI-README.adoc index 9c680aef3..feb49a2ad 100644 --- a/packages/Cliometrics.jl/ABI-FFI-README.md +++ b/packages/Cliometrics.jl/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# Cliometrics ABI/FFI Documentation +== Cliometrics ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... cliometrics/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ cliometrics/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/cliometrics.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "cliometrics.h" int main() { @@ -237,16 +253,19 @@ int main() { cliometrics_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -lcliometrics -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import Cliometrics.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "cliometrics")] extern "C" { fn cliometrics_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { cliometrics_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const libcliometrics = "libcliometrics" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/cliometrics.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/cliometrics.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/Cliometrics.jl/CODE_OF_CONDUCT.adoc b/packages/Cliometrics.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..615e12135 --- /dev/null +++ b/packages/Cliometrics.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/Cliometrics.jl/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Cliometrics.jl/CODE_OF_CONDUCT.md b/packages/Cliometrics.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index ff4956c2a..000000000 --- a/packages/Cliometrics.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/Cliometrics.jl/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/Cliometrics.jl/CONTRIBUTING.adoc b/packages/Cliometrics.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..3da485fb0 --- /dev/null +++ b/packages/Cliometrics.jl/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/Cliometrics.jl.git cd +Cliometrics.jl + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create Cliometrics.jl-dev toolbox enter Cliometrics.jl-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +Cliometrics.jl/ ├── 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_BRANCH}}` +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/Cliometrics.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/Cliometrics.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/Cliometrics.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/Cliometrics.jl/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/packages/Cliometrics.jl/CONTRIBUTING.md b/packages/Cliometrics.jl/CONTRIBUTING.md deleted file mode 100644 index 137ec31b0..000000000 --- a/packages/Cliometrics.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/Cliometrics.jl.git -cd Cliometrics.jl - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create Cliometrics.jl-dev -toolbox enter Cliometrics.jl-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -Cliometrics.jl/ -├── 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_BRANCH}}` -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/Cliometrics.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/Cliometrics.jl/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/Cliometrics.jl/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/Cliometrics.jl/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/packages/Cliometrics.jl/README.adoc b/packages/Cliometrics.jl/README.adoc new file mode 100644 index 000000000..b053d24f7 --- /dev/null +++ b/packages/Cliometrics.jl/README.adoc @@ -0,0 +1,221 @@ +== Cliometrics.jl + +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-85%25-green[Completion +Status]] + +link:LICENSE[image:https://img.shields.io/badge/license-PMPL--1.0--or--later-blue.svg[License]] +https://julialang.org[image:https://img.shields.io/badge/julia-1.6+-purple.svg[Julia]] + +A Julia library for quantitative economic history analysis. + +=== Overview + +Cliometrics applies economic theory and quantitative methods to the +study of historical economic phenomena. This package provides tools for: + +* *Historical Data Analysis*: Load, clean, and analyze historical +economic datasets +* *Growth Accounting*: Decompose economic growth into capital, labor, +and TFP contributions +* *Convergence Analysis*: Test for economic convergence across regions +and time periods +* *Institutional Analysis*: Quantify and analyze the role of +institutions in economic development +* *Counterfactual Modeling*: Estimate treatment effects and alternative +historical scenarios + +=== Installation + +[source,julia] +---- +using Pkg +Pkg.add("Cliometrics") +---- + +=== Quick Start + +[source,julia] +---- +using Cliometrics +using DataFrames + +# Load historical GDP data +data = load_historical_data("maddison_historical_gdp.csv") + +# Calculate growth rates +growth_rates = calculate_growth_rates(data, :real_gdp_per_capita) + +# Perform growth decomposition +decomposition = decompose_growth( + data, + output=:gdp, + capital=:capital_stock, + labor=:labor_force, + alpha=0.35 # Capital share +) + +# Test for convergence +convergence = convergence_analysis( + country_data, + :initial_gdp_1950, + :growth_rate_1950_2000 +) + +# Create institutional quality index +quality_index = institutional_quality_index( + institutions_data, + [:rule_of_law, :property_rights, :contract_enforcement], + weights=[0.4, 0.3, 0.3] +) +---- + +=== Features + +==== Growth Analysis ✅ + +* Geometric and arithmetic growth rate calculations +* Solow residual (TFP) estimation +* Growth accounting decomposition +* Long-run growth trend analysis _(planned for v0.2.0)_ + +==== Convergence Testing ✅ + +* Beta-convergence analysis +* Sigma-convergence testing _(planned for v0.2.0)_ +* Conditional convergence estimation _(planned for v0.2.0)_ +* Half-life calculations + +==== Institutional Analysis ✅ + +* Composite institutional quality indices +* Institutional change measurement +* Relationship between institutions and growth + +==== Data Tools ✅ + +* Historical time series cleaning +* Missing value interpolation +* Outlier detection and handling _(planned for v0.2.0)_ +* Cross-country data alignment _(planned for v0.2.0)_ + +==== Causal Inference ✅ + +* Counterfactual scenario modeling +* Difference-in-differences estimation (DiD) +* Treatment effect analysis + +=== Examples + +==== Example 1: Industrial Revolution Growth Analysis + +[source,julia] +---- +using Cliometrics + +# Load data from Broadberry et al. British Economic Growth 1270-1870 +uk_data = load_historical_data("broadberry_uk_gdp.csv") + +# Calculate pre and post-industrial revolution growth +pre_industrial = filter(row -> 1700 <= row.year < 1780, uk_data) +industrial = filter(row -> 1780 <= row.year <= 1870, uk_data) + +pre_growth = mean(calculate_growth_rates(pre_industrial, :gdp_per_capita)) +post_growth = mean(calculate_growth_rates(industrial, :gdp_per_capita)) + +println("Pre-Industrial Revolution: $(round(pre_growth*100, digits=2))% per year") +println("Industrial Revolution: $(round(post_growth*100, digits=2))% per year") +---- + +==== Example 2: Great Divergence Analysis + +[source,julia] +---- +# Compare Western Europe vs China 1500-1800 +divergence_data = DataFrame( + year = 1500:50:1800, + western_europe_gdp = [1200, 1300, 1450, 1650, 1900, 2200, 2600], + china_gdp = [1100, 1150, 1200, 1250, 1280, 1300, 1320] +) + +comparison = compare_historical_trajectories( + divergence_data, + ["Western Europe", "China"], + variable=:gdp_per_capita +) +---- + +==== Example 3: Institutions and Growth + +[source,julia] +---- +# Acemoglu & Robinson Why Nations Fail analysis +institutions = DataFrame( + country = ["USA", "Haiti", "South Korea", "North Korea"], + inclusive_institutions = [0.9, 0.3, 0.8, 0.1], + gdp_per_capita_1960 = [15000, 2000, 1200, 1100], + gdp_per_capita_2020 = [65000, 1800, 42000, 1300] +) + +institutions.growth_rate = (institutions.gdp_per_capita_2020 ./ + institutions.gdp_per_capita_1960) .^ (1/60) .- 1 + +# Regression of growth on institutions +using GLM +model = lm(@formula(growth_rate ~ inclusive_institutions), institutions) +---- + +=== Methodology + +This package implements standard cliometric methods including: + +* *Growth Accounting*: Following Solow (1957) and subsequent literature +* *Convergence Tests*: Based on Barro & Sala-i-Martin (1992) +* *Institutional Indices*: Inspired by Acemoglu et al. (2001) +* *Historical National Accounts*: Compatible with Maddison Project +format + +=== Data Sources + +Compatible with major historical datasets: - Maddison Project Database - +Penn World Table (historical extensions) - Broadberry et al. historical +national accounts - Polity IV (institutional data) - V-Dem +(institutional indicators) + +=== Citation + +If you use this package in research, please cite: + +[source,bibtex] +---- +@software{cliometrics_jl, + author = {Jewell, Jonathan D.A.}, + title = {Cliometrics.jl: Quantitative Economic History in Julia}, + year = {2026}, + url = {https://github.com/hyperpolymath/Cliometrics.jl} +} +---- + +=== Contributing + +See CONTRIBUTING.md for guidelines. + +=== License + +This project is licensed under the Palimpsest License (MPL-2.0). See +LICENSE for details. + +=== References + +* Solow, R. M. (1957). "`Technical Change and the Aggregate Production +Function.`" _Review of Economics and Statistics_, 39(3), 312-320. +* Barro, R. J., & Sala-i-Martin, X. (1992). "`Convergence.`" _Journal of +Political Economy_, 100(2), 223-251. +* Acemoglu, D., Johnson, S., & Robinson, J. A. (2001). "`The Colonial +Origins of Comparative Development.`" _American Economic Review_, 91(5), +1369-1401. +* Crafts, N., & Toniolo, G. (Eds.). (1996). _Economic Growth in Europe +Since 1945_. Cambridge University Press. +* Maddison, A. (2007). _Contours of the World Economy 1-2030 AD: Essays +in Macro-Economic History_. Oxford University Press. diff --git a/packages/Cliometrics.jl/README.md b/packages/Cliometrics.jl/README.md deleted file mode 100644 index a50af428e..000000000 --- a/packages/Cliometrics.jl/README.md +++ /dev/null @@ -1,196 +0,0 @@ -# Cliometrics.jl - -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-85%25-green)](TOPOLOGY.md) - -[![License](https://img.shields.io/badge/license-PMPL--1.0--or--later-blue.svg)](LICENSE) -[![Julia](https://img.shields.io/badge/julia-1.6+-purple.svg)](https://julialang.org) - -A Julia library for quantitative economic history analysis. - -## Overview - -Cliometrics applies economic theory and quantitative methods to the study of historical economic phenomena. This package provides tools for: - -- **Historical Data Analysis**: Load, clean, and analyze historical economic datasets -- **Growth Accounting**: Decompose economic growth into capital, labor, and TFP contributions -- **Convergence Analysis**: Test for economic convergence across regions and time periods -- **Institutional Analysis**: Quantify and analyze the role of institutions in economic development -- **Counterfactual Modeling**: Estimate treatment effects and alternative historical scenarios - -## Installation - -```julia -using Pkg -Pkg.add("Cliometrics") -``` - -## Quick Start - -```julia -using Cliometrics -using DataFrames - -# Load historical GDP data -data = load_historical_data("maddison_historical_gdp.csv") - -# Calculate growth rates -growth_rates = calculate_growth_rates(data, :real_gdp_per_capita) - -# Perform growth decomposition -decomposition = decompose_growth( - data, - output=:gdp, - capital=:capital_stock, - labor=:labor_force, - alpha=0.35 # Capital share -) - -# Test for convergence -convergence = convergence_analysis( - country_data, - :initial_gdp_1950, - :growth_rate_1950_2000 -) - -# Create institutional quality index -quality_index = institutional_quality_index( - institutions_data, - [:rule_of_law, :property_rights, :contract_enforcement], - weights=[0.4, 0.3, 0.3] -) -``` - -## Features - -### Growth Analysis ✅ -- Geometric and arithmetic growth rate calculations -- Solow residual (TFP) estimation -- Growth accounting decomposition -- Long-run growth trend analysis *(planned for v0.2.0)* - -### Convergence Testing ✅ -- Beta-convergence analysis -- Sigma-convergence testing *(planned for v0.2.0)* -- Conditional convergence estimation *(planned for v0.2.0)* -- Half-life calculations - -### Institutional Analysis ✅ -- Composite institutional quality indices -- Institutional change measurement -- Relationship between institutions and growth - -### Data Tools ✅ -- Historical time series cleaning -- Missing value interpolation -- Outlier detection and handling *(planned for v0.2.0)* -- Cross-country data alignment *(planned for v0.2.0)* - -### Causal Inference ✅ -- Counterfactual scenario modeling -- Difference-in-differences estimation (DiD) -- Treatment effect analysis - -## Examples - -### Example 1: Industrial Revolution Growth Analysis - -```julia -using Cliometrics - -# Load data from Broadberry et al. British Economic Growth 1270-1870 -uk_data = load_historical_data("broadberry_uk_gdp.csv") - -# Calculate pre and post-industrial revolution growth -pre_industrial = filter(row -> 1700 <= row.year < 1780, uk_data) -industrial = filter(row -> 1780 <= row.year <= 1870, uk_data) - -pre_growth = mean(calculate_growth_rates(pre_industrial, :gdp_per_capita)) -post_growth = mean(calculate_growth_rates(industrial, :gdp_per_capita)) - -println("Pre-Industrial Revolution: $(round(pre_growth*100, digits=2))% per year") -println("Industrial Revolution: $(round(post_growth*100, digits=2))% per year") -``` - -### Example 2: Great Divergence Analysis - -```julia -# Compare Western Europe vs China 1500-1800 -divergence_data = DataFrame( - year = 1500:50:1800, - western_europe_gdp = [1200, 1300, 1450, 1650, 1900, 2200, 2600], - china_gdp = [1100, 1150, 1200, 1250, 1280, 1300, 1320] -) - -comparison = compare_historical_trajectories( - divergence_data, - ["Western Europe", "China"], - variable=:gdp_per_capita -) -``` - -### Example 3: Institutions and Growth - -```julia -# Acemoglu & Robinson Why Nations Fail analysis -institutions = DataFrame( - country = ["USA", "Haiti", "South Korea", "North Korea"], - inclusive_institutions = [0.9, 0.3, 0.8, 0.1], - gdp_per_capita_1960 = [15000, 2000, 1200, 1100], - gdp_per_capita_2020 = [65000, 1800, 42000, 1300] -) - -institutions.growth_rate = (institutions.gdp_per_capita_2020 ./ - institutions.gdp_per_capita_1960) .^ (1/60) .- 1 - -# Regression of growth on institutions -using GLM -model = lm(@formula(growth_rate ~ inclusive_institutions), institutions) -``` - -## Methodology - -This package implements standard cliometric methods including: - -- **Growth Accounting**: Following Solow (1957) and subsequent literature -- **Convergence Tests**: Based on Barro & Sala-i-Martin (1992) -- **Institutional Indices**: Inspired by Acemoglu et al. (2001) -- **Historical National Accounts**: Compatible with Maddison Project format - -## Data Sources - -Compatible with major historical datasets: -- Maddison Project Database -- Penn World Table (historical extensions) -- Broadberry et al. historical national accounts -- Polity IV (institutional data) -- V-Dem (institutional indicators) - -## Citation - -If you use this package in research, please cite: - -```bibtex -@software{cliometrics_jl, - author = {Jewell, Jonathan D.A.}, - title = {Cliometrics.jl: Quantitative Economic History in Julia}, - year = {2026}, - url = {https://github.com/hyperpolymath/Cliometrics.jl} -} -``` - -## Contributing - -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. - -## License - -This project is licensed under the Palimpsest License (MPL-2.0). See [LICENSE](LICENSE) for details. - -## References - -- Solow, R. M. (1957). "Technical Change and the Aggregate Production Function." *Review of Economics and Statistics*, 39(3), 312-320. -- Barro, R. J., & Sala-i-Martin, X. (1992). "Convergence." *Journal of Political Economy*, 100(2), 223-251. -- Acemoglu, D., Johnson, S., & Robinson, J. A. (2001). "The Colonial Origins of Comparative Development." *American Economic Review*, 91(5), 1369-1401. -- Crafts, N., & Toniolo, G. (Eds.). (1996). *Economic Growth in Europe Since 1945*. Cambridge University Press. -- Maddison, A. (2007). *Contours of the World Economy 1-2030 AD: Essays in Macro-Economic History*. Oxford University Press. diff --git a/packages/Cliometrics.jl/SECURITY.adoc b/packages/Cliometrics.jl/SECURITY.adoc new file mode 100644 index 000000000..444399c00 --- /dev/null +++ b/packages/Cliometrics.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/Cliometrics.jl/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |jonathan.jewell@open.ac.uk +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint jonathan.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient jonathan.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/Cliometrics.jl+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/Cliometrics.jl/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/hyperpolymath/Cliometrics.jl/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/Cliometrics.jl/security/advisories/new[Report +via GitHub] or jonathan.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/Cliometrics.jl/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Cliometrics.jl/SECURITY.md b/packages/Cliometrics.jl/SECURITY.md deleted file mode 100644 index 9d4571975..000000000 --- a/packages/Cliometrics.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/Cliometrics.jl/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | jonathan.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint jonathan.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient jonathan.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/Cliometrics.jl`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/Cliometrics.jl/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/hyperpolymath/Cliometrics.jl/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/Cliometrics.jl/security/advisories/new) or jonathan.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/Cliometrics.jl/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/Cliometrics.jl/SONNET-TASKS.adoc b/packages/Cliometrics.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..006fbef03 --- /dev/null +++ b/packages/Cliometrics.jl/SONNET-TASKS.adoc @@ -0,0 +1,730 @@ +== SONNET-TASKS.md — Cliometrics.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 35% +____ + +The Julia source code (`+src/Cliometrics.jl+`) has 7 implemented +functions out of 11 exported symbols. Four exported functions have NO +implementation at all: `+interpolate_missing_years+`, +`+quantify_institutions+`, `+counterfactual_scenario+`, and +`+estimate_treatment_effect+`. The README claims features +(sigma-convergence, outlier detection, cross-country alignment, long-run +trend analysis) that have zero code behind them. The entire RSR template +layer (Idris2 ABI, Zig FFI, contractiles, SCM files) is uncustomized +boilerplate with `+{{PROJECT}}+` placeholders throughout. The SCM +directory is misspelled (`+.machines_readable/6scm/+` instead of +`+.machine_readable/+`). Multiple files still use AGPL-3.0-or-later +instead of MPL-2.0. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update `+.machines_readable/6scm/STATE.scm+` with honest completion +percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/Cliometrics.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Implement `+interpolate_missing_years+` (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* The function `+interpolate_missing_years+` is exported on +line 44 but has NO implementation anywhere in the codebase. Any call to +it will throw `+UndefVarError+`. + +*What to do:* 1. Add the function implementation after the +`+clean_historical_series+` function (after line 361), before the +`+compare_historical_trajectories+` function. 2. The function should +accept a `+DataFrame+` with a `+:year+` column and a +`+variable::Symbol+` column. 3. It should identify gaps in the year +sequence (e.g., years 1950, 1952 missing 1951). 4. It should insert rows +for missing years and linearly interpolate the specified variable’s +values. 5. Return the expanded DataFrame with no year gaps. 6. Add a +proper docstring following the existing style (see lines 63-81 for +reference). + +*Implementation signature:* + +[source,julia] +---- +function interpolate_missing_years(data::DataFrame, variable::Symbol; method::Symbol=:linear) +---- + +*Verification:* + +[source,julia] +---- +using Cliometrics, DataFrames +df = DataFrame(year=[2000, 2002, 2005], gdp=[100.0, 110.0, 130.0]) +result = interpolate_missing_years(df, :gdp) +@assert nrow(result) == 6 "Expected 6 rows (2000-2005), got $(nrow(result))" +@assert result.year == 2000:2005 "Years should be continuous 2000:2005" +@assert result.gdp[2] ≈ 105.0 atol=1e-6 "Year 2001 should interpolate to 105.0" +@assert result.gdp[4] ≈ (110.0 + (130.0-110.0)*1/3) atol=1e-6 "Year 2003 should interpolate correctly" +println("TASK 1 PASSED") +---- + +''''' + +=== TASK 2: Implement `+quantify_institutions+` (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* The function `+quantify_institutions+` is exported on line 52 +but has NO implementation anywhere. This is distinct from +`+institutional_quality_index+` which IS implemented (lines 285-308). +`+quantify_institutions+` should provide a different capability: +measuring institutional change over time, not just a static composite +index. + +*What to do:* 1. Add the function after `+institutional_quality_index+` +(after line 308). 2. It should measure how institutional indicators +change over time for a given entity (country/region). 3. Accept a panel +DataFrame with `+:year+`, `+:entity+`, and multiple indicator columns. +4. For each entity, calculate: rate of institutional change per year, +volatility of change, direction (improving/deteriorating). 5. Return a +DataFrame with entity-level summary statistics. 6. Add a proper +docstring. + +*Implementation signature:* + +[source,julia] +---- +function quantify_institutions(data::DataFrame, entity::Symbol, indicators::Vector{Symbol}; + period::Union{Tuple{Int,Int},Nothing}=nothing) +---- + +*Verification:* + +[source,julia] +---- +using Cliometrics, DataFrames, Statistics +df = DataFrame( + year = repeat(2000:2004, 2), + country = repeat(["A", "B"], inner=5), + rule_of_law = [0.5, 0.55, 0.6, 0.65, 0.7, 0.8, 0.78, 0.76, 0.74, 0.72], + corruption = [0.3, 0.35, 0.4, 0.45, 0.5, 0.6, 0.58, 0.55, 0.52, 0.50] +) +result = quantify_institutions(df, :country, [:rule_of_law, :corruption]) +@assert nrow(result) == 2 "Should have 2 rows (one per country)" +@assert "country" in names(result) "Should have entity column" +@assert "avg_change_rate" in names(result) "Should have avg_change_rate column" +# Country A is improving (positive change), B is deteriorating (negative change) +row_a = result[result.country .== "A", :] +row_b = result[result.country .== "B", :] +@assert row_a.avg_change_rate[1] > 0 "Country A should show positive institutional change" +@assert row_b.avg_change_rate[1] < 0 "Country B should show negative institutional change" +println("TASK 2 PASSED") +---- + +''''' + +=== TASK 3: Implement `+counterfactual_scenario+` (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* The function `+counterfactual_scenario+` is exported on line +60 but has NO implementation. The README (line 16) claims +"`Counterfactual Modeling`" as a feature. Zero code exists for it. + +*What to do:* 1. Add the function before the closing +`+end # module Cliometrics+` (before line 411). 2. It should create a +counterfactual time series by modifying a parameter at a specific point +in time. 3. Accept: the actual historical data, a `+break_year+` (when +the counterfactual diverges), a `+variable+` to modify, and an +`+adjustment+` (multiplicative factor or additive shift). 4. From +`+break_year+` onward, apply the adjustment and propagate forward using +the original growth rates. 5. Return a DataFrame with both actual and +counterfactual series for comparison. 6. Add a proper docstring. + +*Implementation signature:* + +[source,julia] +---- +function counterfactual_scenario(data::DataFrame, variable::Symbol, break_year::Int; + adjustment::Float64=1.0, + method::Symbol=:multiplicative) +---- + +*Verification:* + +[source,julia] +---- +using Cliometrics, DataFrames +df = DataFrame(year=2000:2004, gdp=[100.0, 110.0, 121.0, 133.1, 146.41]) +result = counterfactual_scenario(df, :gdp, 2002, adjustment=0.9, method=:multiplicative) +@assert "actual" in names(result) "Should have actual column" +@assert "counterfactual" in names(result) "Should have counterfactual column" +@assert nrow(result) == 5 "Should have same number of rows" +@assert result.actual[1] ≈ 100.0 "Actual should be unchanged" +@assert result.counterfactual[1] ≈ 100.0 "Before break_year, counterfactual equals actual" +@assert result.counterfactual[2] ≈ 110.0 "Year 2001 (before break) unchanged" +@assert result.counterfactual[3] ≈ 121.0 * 0.9 atol=1e-6 "Break year gets adjustment" +# After break year, growth rates from actual applied to counterfactual base +println("TASK 3 PASSED") +---- + +''''' + +=== TASK 4: Implement `+estimate_treatment_effect+` (CRITICAL) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* The function `+estimate_treatment_effect+` is exported on +line 61 but has NO implementation. This is the second part of the +counterfactual modeling feature claimed in the README. + +*What to do:* 1. Add the function after `+counterfactual_scenario+`. 2. +Implement a simple difference-in-differences (DiD) estimator, which is +the standard cliometric method for estimating treatment effects in +historical data. 3. Accept: a DataFrame with `+:year+`, a group +indicator (`+:treated+` boolean), a `+:variable+` column, and a +`+treatment_year+`. 4. Calculate the DiD estimate: (post_treated - +pre_treated) - (post_control - pre_control). 5. Return a NamedTuple with +the treatment effect, pre/post means, and a simple t-statistic. 6. Add a +proper docstring referencing the DiD methodology. + +*Implementation signature:* + +[source,julia] +---- +function estimate_treatment_effect(data::DataFrame, variable::Symbol, + group::Symbol, treatment_year::Int) +---- + +*Verification:* + +[source,julia] +---- +using Cliometrics, DataFrames, Statistics +df = DataFrame( + year = repeat(1990:1999, 2), + country = repeat(["treated", "control"], inner=10), + treated = repeat([true, false], inner=10), + gdp = vcat( + [100, 102, 104, 106, 108, 115, 120, 125, 130, 135], # treated: jump at 1995 + [100, 102, 104, 106, 108, 110, 112, 114, 116, 118] # control: steady + ) .* 1.0 +) +result = estimate_treatment_effect(df, :gdp, :treated, 1995) +@assert haskey(result, :treatment_effect) "Must return treatment_effect" +@assert result.treatment_effect > 0 "Treatment effect should be positive (treated grew faster)" +@assert haskey(result, :pre_treatment_diff) "Must return pre_treatment_diff" +@assert haskey(result, :post_treatment_diff) "Must return post_treatment_diff" +println("TASK 4 PASSED") +---- + +''''' + +=== TASK 5: Add tests for the four new functions (HIGH) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/test/runtests.jl+` + +*Problem:* The test file only tests the 7 originally implemented +functions. The 4 new functions from Tasks 1-4 have no test coverage. + +*What to do:* 1. Add a `+@testset "Interpolate Missing Years"+` block +after the "`Historical Series Cleaning`" testset (after line 107). 2. +Add a `+@testset "Quantify Institutions"+` block after the +"`Institutional Quality Index`" testset (after line 93). 3. Add a +`+@testset "Counterfactual Scenario"+` block after the "`Compare +Historical Trajectories`" testset (after line 150). 4. Add a +`+@testset "Estimate Treatment Effect"+` block after the counterfactual +testset. 5. Each testset should have at least 3 `+@test+` assertions +covering: normal case, edge case, and expected properties. 6. Use the +verification code from Tasks 1-4 as a starting point but convert +assertions to `+@test+` macros. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Cliometrics.jl") +using Pkg; Pkg.test() +# All tests including the 4 new testsets must pass +---- + +''''' + +=== TASK 6: Fix SPDX license headers — replace AGPL-3.0-or-later with MPL-2.0 (HIGH) + +*Files:* - +`+/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/STATE.scm+` +(line 1) - +`+/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/META.scm+` (line +1) - +`+/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/ECOSYSTEM.scm+` +(line 1) - `+/var$REPOS_DIR/Cliometrics.jl/.gitignore+` (line 1) - +`+/var$REPOS_DIR/Cliometrics.jl/.gitattributes+` (line 1) - +`+/var$REPOS_DIR/Cliometrics.jl/ffi/zig/build.zig+` (line 2) - +`+/var$REPOS_DIR/Cliometrics.jl/ffi/zig/src/main.zig+` (line 6) - +`+/var$REPOS_DIR/Cliometrics.jl/ffi/zig/test/integration_test.zig+` +(line 2) - `+/var$REPOS_DIR/Cliometrics.jl/examples/SafeDOMExample.res+` +(line 1) - `+/var$REPOS_DIR/Cliometrics.jl/docs/CITATIONS.adoc+` (line +13, inside bibtex block) + +*Problem:* These files use `+AGPL-3.0-or-later+` which is the OLD +license. Per CLAUDE.md, the primary license is MPL-2.0 and AGPL-3.0 must +NEVER be used. + +*What to do:* 1. In each file listed above, replace +`+AGPL-3.0-or-later+` with `+MPL-2.0+`. 2. For `+docs/CITATIONS.adoc+` +line 13, also update the bibtex `+license+` field value. 3. Do NOT +change the SPDX headers in `+src/Cliometrics.jl+` or +`+test/runtests.jl+` (they already use MPL-2.0 correctly). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && grep -rn "AGPL-3.0" --include="*.scm" --include="*.zig" --include="*.res" --include="*.adoc" . | grep -v ".git/" +# Should return zero lines +---- + +''''' + +=== TASK 7: Replace `+{{PROJECT}}+` / `+{{REPO}}+` / `+{{OWNER}}+` / `+{{FORGE}}+` template placeholders (HIGH) + +*Files:* - `+/var$REPOS_DIR/Cliometrics.jl/src/abi/Types.idr+` (lines 6, +7, 11) - `+/var$REPOS_DIR/Cliometrics.jl/src/abi/Layout.idr+` (lines 8, +10) - `+/var$REPOS_DIR/Cliometrics.jl/src/abi/Foreign.idr+` (lines 9, +11, 12, and all `+{{project}}+` on lines 23, 35, 49, 72, 77, 98, 125, +152, 164, 185, 211) - +`+/var$REPOS_DIR/Cliometrics.jl/ffi/zig/build.zig+` (lines 1, 12, 23, +35, 36, 82) - `+/var$REPOS_DIR/Cliometrics.jl/ffi/zig/src/main.zig+` +(lines 1, 12, and all `+{{project}}_+` function names) - +`+/var$REPOS_DIR/Cliometrics.jl/ffi/zig/test/integration_test.zig+` +(line 1 and all `+{{project}}_+` references) - +`+/var$REPOS_DIR/Cliometrics.jl/ABI-FFI-README.md+` (all `+{{PROJECT}}+` +and `+{{project}}+` occurrences) - +`+/var$REPOS_DIR/Cliometrics.jl/CODE_OF_CONDUCT.md+` (lines 9, 10, 313) +- `+/var$REPOS_DIR/Cliometrics.jl/CONTRIBUTING.md+` (lines 2, 3, 9, 10, +20, 89-92) - `+/var$REPOS_DIR/Cliometrics.jl/SECURITY.md+` (lines 9, 10, +43, 206, 325, 374, 386, 387) - +`+/var$REPOS_DIR/Cliometrics.jl/0-AI-MANIFEST.a2ml+` (line 7, 56) + +*Problem:* The entire RSR template layer was never customized. Every +`+{{PROJECT}}+`, `+{{project}}+`, `+{{OWNER}}+`, `+{{REPO}}+`, and +`+{{FORGE}}+` placeholder is still present, making the Idris2 ABI, Zig +FFI, and community files non-functional. + +*What to do:* 1. Replace `+{{PROJECT}}+` with `+Cliometrics+` +(capitalized, for module/display names). 2. Replace `+{{project}}+` with +`+cliometrics+` (lowercase, for C symbols and file names). 3. Replace +`+{{OWNER}}+` with `+hyperpolymath+`. 4. Replace `+{{REPO}}+` with +`+Cliometrics.jl+`. 5. Replace `+{{FORGE}}+` with `+github.com+`. 6. +Replace `+[YOUR-REPO-NAME]+` with `+Cliometrics.jl+` in +`+0-AI-MANIFEST.a2ml+`. 7. Replace `+{{SECURITY_EMAIL}}+` with +`+jonathan.jewell@open.ac.uk+` in SECURITY.md if present. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && grep -rn '{{PROJECT}}\|{{project}}\|{{OWNER}}\|{{REPO}}\|{{FORGE}}\|\[YOUR-REPO-NAME\]' . --include="*.idr" --include="*.zig" --include="*.md" --include="*.a2ml" --include="*.adoc" | grep -v ".git/" | grep -v "SONNET-TASKS" +# Should return zero lines +---- + +''''' + +=== TASK 8: Update SCM files to reflect Cliometrics.jl accurately (MEDIUM) + +*Files:* - +`+/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/STATE.scm+` - +`+/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/ECOSYSTEM.scm+` +- `+/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/META.scm+` + +*Problem:* All three SCM files still reference `+rsr-template-repo+` +(STATE.scm lines 5, 11, 12; ECOSYSTEM.scm lines 6, 7; META.scm line 5). +STATE.scm claims 5% completion (line 22) and empty tech-stack (line 17). +ECOSYSTEM.scm has `+[TODO: Add specific description]+` on line 24. + +*What to do:* + +[arabic] +. *STATE.scm:* +* Line 5: Change `+rsr-template-repo+` to `+Cliometrics.jl+` +* Line 11: Change `+"rsr-template-repo"+` to `+"Cliometrics.jl"+` +* Line 12: Change `+"hyperpolymath/rsr-template-repo"+` to +`+"hyperpolymath/Cliometrics.jl"+` +* Line 15: Change `+"rsr-template-repo"+` to `+"Cliometrics.jl"+` +* Line 16: Set tagline to +`+"Quantitative economic history analysis in Julia"+` +* Line 17: Set tech-stack to +`+("Julia" "Statistics" "DataFrames" "CSV")+` +* Line 22: Update overall-completion to an honest percentage based on +work done +* Add working features list: +`+("load_historical_data" "calculate_growth_rates" "solow_residual" "decompose_growth" "convergence_analysis" "institutional_quality_index" "clean_historical_series" "compare_historical_trajectories")+` +. *ECOSYSTEM.scm:* +* Line 6: Change name to `+"Cliometrics.jl"+` +* Line 24: Replace `+"[TODO: Add specific description]"+` with +`+"A Julia library for quantitative economic history analysis, providing growth accounting, convergence testing, and institutional analysis tools."+` +. *META.scm:* +* Line 5: Change `+rsr-template-repo+` to `+Cliometrics.jl+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && grep -c "rsr-template-repo" .machines_readable/6scm/STATE.scm .machines_readable/6scm/ECOSYSTEM.scm .machines_readable/6scm/META.scm +# All three should show 0 +grep "TODO" .machines_readable/6scm/ECOSYSTEM.scm +# Should return nothing +---- + +''''' + +=== TASK 9: Update ROADMAP.adoc from template to project-specific content (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/ROADMAP.adoc+` + +*Problem:* The ROADMAP.adoc is still the raw template text. Line 2 says +`+= YOUR Template Repo Roadmap+`. All milestones are generic +placeholders (`+Core functionality+`, `+Basic documentation+`). There is +no mention of Cliometrics.jl or any of its actual features. + +*What to do:* 1. Change the title on line 2 to +`+= Cliometrics.jl Roadmap+`. 2. Update the current status section to +reflect actual state: 7 core functions implemented, 4 pending (or +complete after Tasks 1-4). 3. Replace v0.1.0 milestone items with actual +Cliometrics.jl features: - Growth accounting (done) - Convergence +analysis (done) - Institutional quality index (done) - Data cleaning and +interpolation (done/in-progress) - Counterfactual modeling +(done/in-progress) 4. Add a v0.2.0 milestone with planned features: - +Sigma-convergence testing (claimed in README but not implemented) - +Long-run growth trend analysis (claimed in README but not implemented) - +Outlier detection and handling (claimed in README but not implemented) - +Cross-country data alignment (claimed in README but not implemented) 5. +Keep the SPDX header on line 1. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && head -5 ROADMAP.adoc | grep -c "YOUR Template" +# Should return 0 +grep -c "Cliometrics" ROADMAP.adoc +# Should return at least 1 +---- + +''''' + +=== TASK 10: Update docs/CITATIONS.adoc from template to project-specific (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/docs/CITATIONS.adoc+` + +*Problem:* The entire citations file references `+rsr-template-repo+` +and uses author `+Polymath, Hyper+` instead of the correct +`+Jewell, Jonathan D.A.+`. The year is 2025 instead of 2026. The license +field says AGPL-3.0-or-later. + +*What to do:* 1. Replace the title on line 1: `+RSR-template-repo+` to +`+Cliometrics.jl+`. 2. Update the BibTeX block (lines 8-15): - +`+author+`: `+{Jewell, Jonathan D.A.}+` - `+title+`: +`+{Cliometrics.jl: Quantitative Economic History in Julia}+` - `+year+`: +`+{2026}+` - `+url+`: +`+{https://github.com/hyperpolymath/Cliometrics.jl}+` - `+license+`: +`+{MPL-2.0}+` 3. Update Harvard, OSCOLA, MLA, and APA sections +similarly: - Author: `+Jewell, J.D.A.+` / `+Jonathan D.A. Jewell+` - +Title: `+Cliometrics.jl+` - Year: `+2026+` - URL: +`+github.com/hyperpolymath/Cliometrics.jl+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && grep -c "rsr-template-repo\|RSR-template-repo\|Polymath, Hyper" docs/CITATIONS.adoc +# Should return 0 +grep -c "Cliometrics.jl" docs/CITATIONS.adoc +# Should return at least 4 +grep -c "Jewell" docs/CITATIONS.adoc +# Should return at least 4 +---- + +''''' + +=== TASK 11: Remove irrelevant RSR template example files (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Cliometrics.jl/examples/SafeDOMExample.res+` +- `+/var$REPOS_DIR/Cliometrics.jl/examples/web-project-deno.json+` + +*Problem:* These are ReScript/Deno web project examples from the RSR +template. They have nothing to do with a Julia cliometrics library. +`+SafeDOMExample.res+` is a ReScript DOM mounting example. +`+web-project-deno.json+` is a Deno configuration file. Neither is +relevant. + +*What to do:* 1. Delete both files. 2. Create a new +`+examples/growth_decomposition.jl+` example file that demonstrates the +core Cliometrics.jl workflow (loading data, calculating growth rates, +decomposing growth, convergence analysis). 3. Add SPDX header +`+# SPDX-License-Identifier: CC-BY-SA-4.0+` and author line. 4. The +example should be runnable (use synthetic data since we have no bundled +CSV files). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && test ! -f examples/SafeDOMExample.res && test ! -f examples/web-project-deno.json && test -f examples/growth_decomposition.jl && echo "PASS" || echo "FAIL" +---- + +[source,julia] +---- +# Verify the example is valid Julia +include("/var$REPOS_DIR/Cliometrics.jl/examples/growth_decomposition.jl") +println("TASK 11 PASSED") +---- + +''''' + +=== TASK 12: Fix `+clean_historical_series+` to handle `+missing+` values correctly (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* On line 329, `+float.(data)+` will fail on a +`+Vector{Union{Float64, Missing}}+` because `+float(missing)+` throws a +`+MethodError+`. The test on lines 97-98 passes +`+[100.0, 105.0, missing, 115.0, 120.0]+` which creates a +`+Vector{Union{Float64, Missing}}+`. The function signature on line 327 +accepts `+data::Vector+` which includes this type, but `+float.(data)+` +on line 329 cannot convert `+missing+` to a float. + +Additionally, on line 334, `+ismissing(cleaned[i])+` after +`+float.(data)+` is inconsistent – if `+float.+` succeeded (which it +would not with missing), the values would all be Float64 and +`+ismissing+` would never be true. + +*What to do:* 1. On line 329, replace `+cleaned = float.(data)+` with a +version that preserves missing values: +`+julia cleaned = Vector{Union{Float64,Missing}}(data)+` 2. On line +334, the `+isnan+` check should also handle the case where +`+cleaned[i]+` is missing. Use +`+ismissing(cleaned[i]) || (!ismissing(cleaned[i]) && isnan(cleaned[i]))+` +or restructure the condition. 3. At the end (line 360), convert the +result to `+Vector{Float64}+` by replacing any remaining missing values +with NaN, or by requiring all missing values were filled. 4. Update the +return type in the docstring (line 311) to clarify behavior. + +*Verification:* + +[source,julia] +---- +using Cliometrics +# Test with missing values +data = [100.0, 105.0, missing, 115.0, 120.0] +cleaned = clean_historical_series(data, method=:linear) +@assert length(cleaned) == 5 +@assert !any(ismissing, cleaned) "No missing values should remain" +@assert cleaned[3] ≈ 110.0 atol=1e-6 +# Test with NaN values +data2 = [100.0, 105.0, NaN, 115.0, 120.0] +cleaned2 = clean_historical_series(data2, method=:linear) +@assert !any(isnan, cleaned2) "No NaN values should remain" +# Test forward fill with missing +data3 = [100.0, missing, missing, 115.0, 120.0] +cleaned3 = clean_historical_series(data3, method=:forward_fill) +@assert cleaned3[2] ≈ 100.0 +@assert cleaned3[3] ≈ 100.0 +println("TASK 12 PASSED") +---- + +''''' + +=== TASK 13: Fix `+compare_historical_trajectories+` to handle `+push!+` correctly (LOW) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* On line 389, `+results = DataFrame()+` creates an empty +DataFrame with no columns. Then on line 398, `+push!(results, (...))+` +tries to push a NamedTuple into an empty DataFrame. In DataFrames.jl, +`+push!+` on an empty DataFrame with a NamedTuple does work (it creates +columns from the NamedTuple field names), BUT only if the DataFrame +truly has no columns. This is fragile and version-dependent. A more +robust approach initializes the DataFrame with column types. + +*What to do:* 1. Replace line 389 with a properly typed empty DataFrame: +`+julia results = DataFrame( region = String[], initial_level = Float64[], final_level = Float64[], avg_growth = Float64[], std_growth = Float64[], cumulative_growth = Float64[] )+` +2. This makes the function robust across DataFrames.jl versions. + +*Verification:* + +[source,julia] +---- +using Cliometrics, DataFrames +data = DataFrame( + year = repeat(1950:1960, 2), + region = repeat(["Europe", "Asia"], inner=11), + gdp_per_capita = vcat( + [1000, 1100, 1210, 1331, 1464, 1610, 1771, 1948, 2143, 2357, 2593], + [500, 525, 551, 579, 608, 638, 670, 703, 738, 775, 814] + ) .* 1.0 +) +result = compare_historical_trajectories(data, ["Europe", "Asia"]) +@assert nrow(result) == 2 +@assert eltype(result.region) <: AbstractString +@assert eltype(result.avg_growth) <: AbstractFloat +println("TASK 13 PASSED") +---- + +''''' + +=== TASK 14: Add `+:spline+` method to `+clean_historical_series+` (LOW) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl+` + +*Problem:* The docstring on line 313 lists `+:spline+` as a valid method +option, but the implementation (lines 327-361) only handles `+:linear+` +and `+:forward_fill+`. If a user calls +`+clean_historical_series(data, method=:spline)+`, it silently returns +the uncleaned data since neither branch matches. + +*What to do:* 1. Either implement a simple spline interpolation (cubic), +or 2. Add an `+else+` clause that throws an informative error: +`+error("Unknown method: $method. Use :linear, :spline, or :forward_fill")+` +3. If implementing spline: use a natural cubic spline between known +points. You may use `+StatsBase+` or implement a basic version. Given +that the package already depends on `+StatsBase+`, check if it provides +interpolation utilities. 4. If spline is too complex to implement +cleanly, remove `+:spline+` from the docstring on line 313 and add the +error clause. + +*Verification:* + +[source,julia] +---- +using Cliometrics +# If spline is implemented: +data = [100.0, 105.0, NaN, NaN, 120.0] +cleaned = clean_historical_series(data, method=:spline) +@assert length(cleaned) == 5 +@assert all(isfinite.(cleaned)) +println("TASK 14 PASSED") + +# OR if spline is removed, verify error: +try + clean_historical_series([1.0, 2.0], method=:spline) + error("Should have thrown") +catch e + @assert occursin("Unknown method", e.msg) "Should throw informative error" + println("TASK 14 PASSED (spline removed, error added)") +end +---- + +''''' + +=== TASK 15: Fix Dustfile and Intentfile SPDX typo (LOW) + +*Files:* - `+/var$REPOS_DIR/Cliometrics.jl/contractiles/dust/Dustfile+` +(line 1) - +`+/var$REPOS_DIR/Cliometrics.jl/contractiles/lust/Intentfile+` (line 1) +- `+/var$REPOS_DIR/Cliometrics.jl/contractiles/must/Mustfile+` (line 1) +- `+/var$REPOS_DIR/Cliometrics.jl/contractiles/trust/Trustfile.hs+` +(line 1) + +*Problem:* These files use `+PLMP-1.0-or-later+` which is a typo. The +correct identifier is `+MPL-2.0+` (Palimpsest License). + +*What to do:* 1. In each file, replace `+PLMP-1.0-or-later+` with +`+MPL-2.0+` on line 1. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl && grep -rn "PLMP" contractiles/ +# Should return zero lines +grep -rn "PMPL" contractiles/dust/Dustfile contractiles/lust/Intentfile contractiles/must/Mustfile contractiles/trust/Trustfile.hs +# Should return 4 lines, one per file +---- + +''''' + +=== TASK 16: Add README claim reconciliation — remove or implement claimed features (LOW) + +*Files:* `+/var$REPOS_DIR/Cliometrics.jl/README.md+` + +*Problem:* The README.md (lines 69-84) claims the following features +that have NO implementation: - "`Sigma-convergence testing`" (line 71) – +only beta-convergence exists - "`Conditional convergence estimation`" +(line 72) – not implemented - "`Long-run growth trend analysis`" (line +67) – not implemented - "`Institutional change measurement`" (line 78) – +partially addressed by Task 2 - "`Outlier detection and handling`" (line +83) – not implemented - "`Cross-country data alignment`" (line 84) – not +implemented + +*What to do:* 1. For features completed by Tasks 1-4, verify they are +accurately described. 2. For features NOT implemented +(sigma-convergence, conditional convergence, long-run trends, outlier +detection, cross-country alignment), either: a. Mark them as "`Planned`" +or "`Coming in v0.2.0`" in the README, or b. Remove them from the +feature list entirely. 3. Do NOT claim features that do not exist in the +code. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl +# Manually verify: every feature listed in README.md has a corresponding exported function +grep -oP '(?<=- ).*' README.md | head -20 +# Cross-reference with: +grep "^ " src/Cliometrics.jl | head -20 # exported functions +---- + +''''' + +=== FINAL VERIFICATION + +After all tasks are complete, run the following sequence: + +[source,bash] +---- +cd /var$REPOS_DIR/Cliometrics.jl + +# 1. Full test suite +julia --project=. -e 'using Pkg; Pkg.test()' + +# 2. No AGPL references remain +grep -rn "AGPL-3.0" . --include="*.scm" --include="*.zig" --include="*.res" --include="*.adoc" --include="*.jl" | grep -v ".git/" | grep -v "SONNET-TASKS" + +# 3. No template placeholders remain +grep -rn '{{PROJECT}}\|{{project}}\|{{OWNER}}\|{{REPO}}\|{{FORGE}}\|\[YOUR-REPO-NAME\]' . --include="*.idr" --include="*.zig" --include="*.md" --include="*.a2ml" --include="*.adoc" | grep -v ".git/" | grep -v "SONNET-TASKS" + +# 4. No PLMP typos remain +grep -rn "PLMP" . --include="*" | grep -v ".git/" | grep -v "SONNET-TASKS" + +# 5. No rsr-template-repo references in SCM files +grep -rn "rsr-template-repo" .machines_readable/ + +# 6. All exported functions have implementations +julia --project=. -e ' +using Cliometrics +for name in names(Cliometrics) + fn = getfield(Cliometrics, name) + if fn isa Function + println("OK: $name is defined") + end +end +' + +# 7. Verify the example runs +julia --project=. examples/growth_decomposition.jl +---- + +All 7 checks must pass with zero errors. If any fail, fix the root cause +before declaring completion. diff --git a/packages/Cliometrics.jl/SONNET-TASKS.md b/packages/Cliometrics.jl/SONNET-TASKS.md deleted file mode 100644 index 915fdef09..000000000 --- a/packages/Cliometrics.jl/SONNET-TASKS.md +++ /dev/null @@ -1,598 +0,0 @@ -# SONNET-TASKS.md — Cliometrics.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 35% - -The Julia source code (`src/Cliometrics.jl`) has 7 implemented functions out of 11 exported symbols. Four exported functions have NO implementation at all: `interpolate_missing_years`, `quantify_institutions`, `counterfactual_scenario`, and `estimate_treatment_effect`. The README claims features (sigma-convergence, outlier detection, cross-country alignment, long-run trend analysis) that have zero code behind them. The entire RSR template layer (Idris2 ABI, Zig FFI, contractiles, SCM files) is uncustomized boilerplate with `{{PROJECT}}` placeholders throughout. The SCM directory is misspelled (`.machines_readable/6scm/` instead of `.machine_readable/`). Multiple files still use AGPL-3.0-or-later instead of MPL-2.0. - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update `.machines_readable/6scm/STATE.scm` with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/Cliometrics.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Implement `interpolate_missing_years` (CRITICAL) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** The function `interpolate_missing_years` is exported on line 44 but has NO implementation anywhere in the codebase. Any call to it will throw `UndefVarError`. - -**What to do:** -1. Add the function implementation after the `clean_historical_series` function (after line 361), before the `compare_historical_trajectories` function. -2. The function should accept a `DataFrame` with a `:year` column and a `variable::Symbol` column. -3. It should identify gaps in the year sequence (e.g., years 1950, 1952 missing 1951). -4. It should insert rows for missing years and linearly interpolate the specified variable's values. -5. Return the expanded DataFrame with no year gaps. -6. Add a proper docstring following the existing style (see lines 63-81 for reference). - -**Implementation signature:** -```julia -function interpolate_missing_years(data::DataFrame, variable::Symbol; method::Symbol=:linear) -``` - -**Verification:** -```julia -using Cliometrics, DataFrames -df = DataFrame(year=[2000, 2002, 2005], gdp=[100.0, 110.0, 130.0]) -result = interpolate_missing_years(df, :gdp) -@assert nrow(result) == 6 "Expected 6 rows (2000-2005), got $(nrow(result))" -@assert result.year == 2000:2005 "Years should be continuous 2000:2005" -@assert result.gdp[2] ≈ 105.0 atol=1e-6 "Year 2001 should interpolate to 105.0" -@assert result.gdp[4] ≈ (110.0 + (130.0-110.0)*1/3) atol=1e-6 "Year 2003 should interpolate correctly" -println("TASK 1 PASSED") -``` - ---- - -## TASK 2: Implement `quantify_institutions` (CRITICAL) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** The function `quantify_institutions` is exported on line 52 but has NO implementation anywhere. This is distinct from `institutional_quality_index` which IS implemented (lines 285-308). `quantify_institutions` should provide a different capability: measuring institutional change over time, not just a static composite index. - -**What to do:** -1. Add the function after `institutional_quality_index` (after line 308). -2. It should measure how institutional indicators change over time for a given entity (country/region). -3. Accept a panel DataFrame with `:year`, `:entity`, and multiple indicator columns. -4. For each entity, calculate: rate of institutional change per year, volatility of change, direction (improving/deteriorating). -5. Return a DataFrame with entity-level summary statistics. -6. Add a proper docstring. - -**Implementation signature:** -```julia -function quantify_institutions(data::DataFrame, entity::Symbol, indicators::Vector{Symbol}; - period::Union{Tuple{Int,Int},Nothing}=nothing) -``` - -**Verification:** -```julia -using Cliometrics, DataFrames, Statistics -df = DataFrame( - year = repeat(2000:2004, 2), - country = repeat(["A", "B"], inner=5), - rule_of_law = [0.5, 0.55, 0.6, 0.65, 0.7, 0.8, 0.78, 0.76, 0.74, 0.72], - corruption = [0.3, 0.35, 0.4, 0.45, 0.5, 0.6, 0.58, 0.55, 0.52, 0.50] -) -result = quantify_institutions(df, :country, [:rule_of_law, :corruption]) -@assert nrow(result) == 2 "Should have 2 rows (one per country)" -@assert "country" in names(result) "Should have entity column" -@assert "avg_change_rate" in names(result) "Should have avg_change_rate column" -# Country A is improving (positive change), B is deteriorating (negative change) -row_a = result[result.country .== "A", :] -row_b = result[result.country .== "B", :] -@assert row_a.avg_change_rate[1] > 0 "Country A should show positive institutional change" -@assert row_b.avg_change_rate[1] < 0 "Country B should show negative institutional change" -println("TASK 2 PASSED") -``` - ---- - -## TASK 3: Implement `counterfactual_scenario` (CRITICAL) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** The function `counterfactual_scenario` is exported on line 60 but has NO implementation. The README (line 16) claims "Counterfactual Modeling" as a feature. Zero code exists for it. - -**What to do:** -1. Add the function before the closing `end # module Cliometrics` (before line 411). -2. It should create a counterfactual time series by modifying a parameter at a specific point in time. -3. Accept: the actual historical data, a `break_year` (when the counterfactual diverges), a `variable` to modify, and an `adjustment` (multiplicative factor or additive shift). -4. From `break_year` onward, apply the adjustment and propagate forward using the original growth rates. -5. Return a DataFrame with both actual and counterfactual series for comparison. -6. Add a proper docstring. - -**Implementation signature:** -```julia -function counterfactual_scenario(data::DataFrame, variable::Symbol, break_year::Int; - adjustment::Float64=1.0, - method::Symbol=:multiplicative) -``` - -**Verification:** -```julia -using Cliometrics, DataFrames -df = DataFrame(year=2000:2004, gdp=[100.0, 110.0, 121.0, 133.1, 146.41]) -result = counterfactual_scenario(df, :gdp, 2002, adjustment=0.9, method=:multiplicative) -@assert "actual" in names(result) "Should have actual column" -@assert "counterfactual" in names(result) "Should have counterfactual column" -@assert nrow(result) == 5 "Should have same number of rows" -@assert result.actual[1] ≈ 100.0 "Actual should be unchanged" -@assert result.counterfactual[1] ≈ 100.0 "Before break_year, counterfactual equals actual" -@assert result.counterfactual[2] ≈ 110.0 "Year 2001 (before break) unchanged" -@assert result.counterfactual[3] ≈ 121.0 * 0.9 atol=1e-6 "Break year gets adjustment" -# After break year, growth rates from actual applied to counterfactual base -println("TASK 3 PASSED") -``` - ---- - -## TASK 4: Implement `estimate_treatment_effect` (CRITICAL) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** The function `estimate_treatment_effect` is exported on line 61 but has NO implementation. This is the second part of the counterfactual modeling feature claimed in the README. - -**What to do:** -1. Add the function after `counterfactual_scenario`. -2. Implement a simple difference-in-differences (DiD) estimator, which is the standard cliometric method for estimating treatment effects in historical data. -3. Accept: a DataFrame with `:year`, a group indicator (`:treated` boolean), a `:variable` column, and a `treatment_year`. -4. Calculate the DiD estimate: (post_treated - pre_treated) - (post_control - pre_control). -5. Return a NamedTuple with the treatment effect, pre/post means, and a simple t-statistic. -6. Add a proper docstring referencing the DiD methodology. - -**Implementation signature:** -```julia -function estimate_treatment_effect(data::DataFrame, variable::Symbol, - group::Symbol, treatment_year::Int) -``` - -**Verification:** -```julia -using Cliometrics, DataFrames, Statistics -df = DataFrame( - year = repeat(1990:1999, 2), - country = repeat(["treated", "control"], inner=10), - treated = repeat([true, false], inner=10), - gdp = vcat( - [100, 102, 104, 106, 108, 115, 120, 125, 130, 135], # treated: jump at 1995 - [100, 102, 104, 106, 108, 110, 112, 114, 116, 118] # control: steady - ) .* 1.0 -) -result = estimate_treatment_effect(df, :gdp, :treated, 1995) -@assert haskey(result, :treatment_effect) "Must return treatment_effect" -@assert result.treatment_effect > 0 "Treatment effect should be positive (treated grew faster)" -@assert haskey(result, :pre_treatment_diff) "Must return pre_treatment_diff" -@assert haskey(result, :post_treatment_diff) "Must return post_treatment_diff" -println("TASK 4 PASSED") -``` - ---- - -## TASK 5: Add tests for the four new functions (HIGH) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/test/runtests.jl` - -**Problem:** The test file only tests the 7 originally implemented functions. The 4 new functions from Tasks 1-4 have no test coverage. - -**What to do:** -1. Add a `@testset "Interpolate Missing Years"` block after the "Historical Series Cleaning" testset (after line 107). -2. Add a `@testset "Quantify Institutions"` block after the "Institutional Quality Index" testset (after line 93). -3. Add a `@testset "Counterfactual Scenario"` block after the "Compare Historical Trajectories" testset (after line 150). -4. Add a `@testset "Estimate Treatment Effect"` block after the counterfactual testset. -5. Each testset should have at least 3 `@test` assertions covering: normal case, edge case, and expected properties. -6. Use the verification code from Tasks 1-4 as a starting point but convert assertions to `@test` macros. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Cliometrics.jl") -using Pkg; Pkg.test() -# All tests including the 4 new testsets must pass -``` - ---- - -## TASK 6: Fix SPDX license headers — replace AGPL-3.0-or-later with MPL-2.0 (HIGH) - -**Files:** -- `/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/STATE.scm` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/META.scm` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/ECOSYSTEM.scm` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/.gitignore` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/.gitattributes` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/ffi/zig/build.zig` (line 2) -- `/var$REPOS_DIR/Cliometrics.jl/ffi/zig/src/main.zig` (line 6) -- `/var$REPOS_DIR/Cliometrics.jl/ffi/zig/test/integration_test.zig` (line 2) -- `/var$REPOS_DIR/Cliometrics.jl/examples/SafeDOMExample.res` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/docs/CITATIONS.adoc` (line 13, inside bibtex block) - -**Problem:** These files use `AGPL-3.0-or-later` which is the OLD license. Per CLAUDE.md, the primary license is MPL-2.0 and AGPL-3.0 must NEVER be used. - -**What to do:** -1. In each file listed above, replace `AGPL-3.0-or-later` with `MPL-2.0`. -2. For `docs/CITATIONS.adoc` line 13, also update the bibtex `license` field value. -3. Do NOT change the SPDX headers in `src/Cliometrics.jl` or `test/runtests.jl` (they already use MPL-2.0 correctly). - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && grep -rn "AGPL-3.0" --include="*.scm" --include="*.zig" --include="*.res" --include="*.adoc" . | grep -v ".git/" -# Should return zero lines -``` - ---- - -## TASK 7: Replace `{{PROJECT}}` / `{{REPO}}` / `{{OWNER}}` / `{{FORGE}}` template placeholders (HIGH) - -**Files:** -- `/var$REPOS_DIR/Cliometrics.jl/src/abi/Types.idr` (lines 6, 7, 11) -- `/var$REPOS_DIR/Cliometrics.jl/src/abi/Layout.idr` (lines 8, 10) -- `/var$REPOS_DIR/Cliometrics.jl/src/abi/Foreign.idr` (lines 9, 11, 12, and all `{{project}}` on lines 23, 35, 49, 72, 77, 98, 125, 152, 164, 185, 211) -- `/var$REPOS_DIR/Cliometrics.jl/ffi/zig/build.zig` (lines 1, 12, 23, 35, 36, 82) -- `/var$REPOS_DIR/Cliometrics.jl/ffi/zig/src/main.zig` (lines 1, 12, and all `{{project}}_` function names) -- `/var$REPOS_DIR/Cliometrics.jl/ffi/zig/test/integration_test.zig` (line 1 and all `{{project}}_` references) -- `/var$REPOS_DIR/Cliometrics.jl/ABI-FFI-README.md` (all `{{PROJECT}}` and `{{project}}` occurrences) -- `/var$REPOS_DIR/Cliometrics.jl/CODE_OF_CONDUCT.md` (lines 9, 10, 313) -- `/var$REPOS_DIR/Cliometrics.jl/CONTRIBUTING.md` (lines 2, 3, 9, 10, 20, 89-92) -- `/var$REPOS_DIR/Cliometrics.jl/SECURITY.md` (lines 9, 10, 43, 206, 325, 374, 386, 387) -- `/var$REPOS_DIR/Cliometrics.jl/0-AI-MANIFEST.a2ml` (line 7, 56) - -**Problem:** The entire RSR template layer was never customized. Every `{{PROJECT}}`, `{{project}}`, `{{OWNER}}`, `{{REPO}}`, and `{{FORGE}}` placeholder is still present, making the Idris2 ABI, Zig FFI, and community files non-functional. - -**What to do:** -1. Replace `{{PROJECT}}` with `Cliometrics` (capitalized, for module/display names). -2. Replace `{{project}}` with `cliometrics` (lowercase, for C symbols and file names). -3. Replace `{{OWNER}}` with `hyperpolymath`. -4. Replace `{{REPO}}` with `Cliometrics.jl`. -5. Replace `{{FORGE}}` with `github.com`. -6. Replace `[YOUR-REPO-NAME]` with `Cliometrics.jl` in `0-AI-MANIFEST.a2ml`. -7. Replace `{{SECURITY_EMAIL}}` with `jonathan.jewell@open.ac.uk` in SECURITY.md if present. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && grep -rn '{{PROJECT}}\|{{project}}\|{{OWNER}}\|{{REPO}}\|{{FORGE}}\|\[YOUR-REPO-NAME\]' . --include="*.idr" --include="*.zig" --include="*.md" --include="*.a2ml" --include="*.adoc" | grep -v ".git/" | grep -v "SONNET-TASKS" -# Should return zero lines -``` - ---- - -## TASK 8: Update SCM files to reflect Cliometrics.jl accurately (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/STATE.scm` -- `/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/ECOSYSTEM.scm` -- `/var$REPOS_DIR/Cliometrics.jl/.machines_readable/6scm/META.scm` - -**Problem:** All three SCM files still reference `rsr-template-repo` (STATE.scm lines 5, 11, 12; ECOSYSTEM.scm lines 6, 7; META.scm line 5). STATE.scm claims 5% completion (line 22) and empty tech-stack (line 17). ECOSYSTEM.scm has `[TODO: Add specific description]` on line 24. - -**What to do:** - -1. **STATE.scm:** - - Line 5: Change `rsr-template-repo` to `Cliometrics.jl` - - Line 11: Change `"rsr-template-repo"` to `"Cliometrics.jl"` - - Line 12: Change `"hyperpolymath/rsr-template-repo"` to `"hyperpolymath/Cliometrics.jl"` - - Line 15: Change `"rsr-template-repo"` to `"Cliometrics.jl"` - - Line 16: Set tagline to `"Quantitative economic history analysis in Julia"` - - Line 17: Set tech-stack to `("Julia" "Statistics" "DataFrames" "CSV")` - - Line 22: Update overall-completion to an honest percentage based on work done - - Add working features list: `("load_historical_data" "calculate_growth_rates" "solow_residual" "decompose_growth" "convergence_analysis" "institutional_quality_index" "clean_historical_series" "compare_historical_trajectories")` - -2. **ECOSYSTEM.scm:** - - Line 6: Change name to `"Cliometrics.jl"` - - Line 24: Replace `"[TODO: Add specific description]"` with `"A Julia library for quantitative economic history analysis, providing growth accounting, convergence testing, and institutional analysis tools."` - -3. **META.scm:** - - Line 5: Change `rsr-template-repo` to `Cliometrics.jl` - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && grep -c "rsr-template-repo" .machines_readable/6scm/STATE.scm .machines_readable/6scm/ECOSYSTEM.scm .machines_readable/6scm/META.scm -# All three should show 0 -grep "TODO" .machines_readable/6scm/ECOSYSTEM.scm -# Should return nothing -``` - ---- - -## TASK 9: Update ROADMAP.adoc from template to project-specific content (MEDIUM) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/ROADMAP.adoc` - -**Problem:** The ROADMAP.adoc is still the raw template text. Line 2 says `= YOUR Template Repo Roadmap`. All milestones are generic placeholders (`Core functionality`, `Basic documentation`). There is no mention of Cliometrics.jl or any of its actual features. - -**What to do:** -1. Change the title on line 2 to `= Cliometrics.jl Roadmap`. -2. Update the current status section to reflect actual state: 7 core functions implemented, 4 pending (or complete after Tasks 1-4). -3. Replace v0.1.0 milestone items with actual Cliometrics.jl features: - - Growth accounting (done) - - Convergence analysis (done) - - Institutional quality index (done) - - Data cleaning and interpolation (done/in-progress) - - Counterfactual modeling (done/in-progress) -4. Add a v0.2.0 milestone with planned features: - - Sigma-convergence testing (claimed in README but not implemented) - - Long-run growth trend analysis (claimed in README but not implemented) - - Outlier detection and handling (claimed in README but not implemented) - - Cross-country data alignment (claimed in README but not implemented) -5. Keep the SPDX header on line 1. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && head -5 ROADMAP.adoc | grep -c "YOUR Template" -# Should return 0 -grep -c "Cliometrics" ROADMAP.adoc -# Should return at least 1 -``` - ---- - -## TASK 10: Update docs/CITATIONS.adoc from template to project-specific (MEDIUM) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/docs/CITATIONS.adoc` - -**Problem:** The entire citations file references `rsr-template-repo` and uses author `Polymath, Hyper` instead of the correct `Jewell, Jonathan D.A.`. The year is 2025 instead of 2026. The license field says AGPL-3.0-or-later. - -**What to do:** -1. Replace the title on line 1: `RSR-template-repo` to `Cliometrics.jl`. -2. Update the BibTeX block (lines 8-15): - - `author`: `{Jewell, Jonathan D.A.}` - - `title`: `{Cliometrics.jl: Quantitative Economic History in Julia}` - - `year`: `{2026}` - - `url`: `{https://github.com/hyperpolymath/Cliometrics.jl}` - - `license`: `{MPL-2.0}` -3. Update Harvard, OSCOLA, MLA, and APA sections similarly: - - Author: `Jewell, J.D.A.` / `Jonathan D.A. Jewell` - - Title: `Cliometrics.jl` - - Year: `2026` - - URL: `github.com/hyperpolymath/Cliometrics.jl` - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && grep -c "rsr-template-repo\|RSR-template-repo\|Polymath, Hyper" docs/CITATIONS.adoc -# Should return 0 -grep -c "Cliometrics.jl" docs/CITATIONS.adoc -# Should return at least 4 -grep -c "Jewell" docs/CITATIONS.adoc -# Should return at least 4 -``` - ---- - -## TASK 11: Remove irrelevant RSR template example files (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Cliometrics.jl/examples/SafeDOMExample.res` -- `/var$REPOS_DIR/Cliometrics.jl/examples/web-project-deno.json` - -**Problem:** These are ReScript/Deno web project examples from the RSR template. They have nothing to do with a Julia cliometrics library. `SafeDOMExample.res` is a ReScript DOM mounting example. `web-project-deno.json` is a Deno configuration file. Neither is relevant. - -**What to do:** -1. Delete both files. -2. Create a new `examples/growth_decomposition.jl` example file that demonstrates the core Cliometrics.jl workflow (loading data, calculating growth rates, decomposing growth, convergence analysis). -3. Add SPDX header `# SPDX-License-Identifier: CC-BY-SA-4.0` and author line. -4. The example should be runnable (use synthetic data since we have no bundled CSV files). - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && test ! -f examples/SafeDOMExample.res && test ! -f examples/web-project-deno.json && test -f examples/growth_decomposition.jl && echo "PASS" || echo "FAIL" -``` -```julia -# Verify the example is valid Julia -include("/var$REPOS_DIR/Cliometrics.jl/examples/growth_decomposition.jl") -println("TASK 11 PASSED") -``` - ---- - -## TASK 12: Fix `clean_historical_series` to handle `missing` values correctly (MEDIUM) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** On line 329, `float.(data)` will fail on a `Vector{Union{Float64, Missing}}` because `float(missing)` throws a `MethodError`. The test on lines 97-98 passes `[100.0, 105.0, missing, 115.0, 120.0]` which creates a `Vector{Union{Float64, Missing}}`. The function signature on line 327 accepts `data::Vector` which includes this type, but `float.(data)` on line 329 cannot convert `missing` to a float. - -Additionally, on line 334, `ismissing(cleaned[i])` after `float.(data)` is inconsistent -- if `float.` succeeded (which it would not with missing), the values would all be Float64 and `ismissing` would never be true. - -**What to do:** -1. On line 329, replace `cleaned = float.(data)` with a version that preserves missing values: - ```julia - cleaned = Vector{Union{Float64,Missing}}(data) - ``` -2. On line 334, the `isnan` check should also handle the case where `cleaned[i]` is missing. Use `ismissing(cleaned[i]) || (!ismissing(cleaned[i]) && isnan(cleaned[i]))` or restructure the condition. -3. At the end (line 360), convert the result to `Vector{Float64}` by replacing any remaining missing values with NaN, or by requiring all missing values were filled. -4. Update the return type in the docstring (line 311) to clarify behavior. - -**Verification:** -```julia -using Cliometrics -# Test with missing values -data = [100.0, 105.0, missing, 115.0, 120.0] -cleaned = clean_historical_series(data, method=:linear) -@assert length(cleaned) == 5 -@assert !any(ismissing, cleaned) "No missing values should remain" -@assert cleaned[3] ≈ 110.0 atol=1e-6 -# Test with NaN values -data2 = [100.0, 105.0, NaN, 115.0, 120.0] -cleaned2 = clean_historical_series(data2, method=:linear) -@assert !any(isnan, cleaned2) "No NaN values should remain" -# Test forward fill with missing -data3 = [100.0, missing, missing, 115.0, 120.0] -cleaned3 = clean_historical_series(data3, method=:forward_fill) -@assert cleaned3[2] ≈ 100.0 -@assert cleaned3[3] ≈ 100.0 -println("TASK 12 PASSED") -``` - ---- - -## TASK 13: Fix `compare_historical_trajectories` to handle `push!` correctly (LOW) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** On line 389, `results = DataFrame()` creates an empty DataFrame with no columns. Then on line 398, `push!(results, (...))` tries to push a NamedTuple into an empty DataFrame. In DataFrames.jl, `push!` on an empty DataFrame with a NamedTuple does work (it creates columns from the NamedTuple field names), BUT only if the DataFrame truly has no columns. This is fragile and version-dependent. A more robust approach initializes the DataFrame with column types. - -**What to do:** -1. Replace line 389 with a properly typed empty DataFrame: - ```julia - results = DataFrame( - region = String[], - initial_level = Float64[], - final_level = Float64[], - avg_growth = Float64[], - std_growth = Float64[], - cumulative_growth = Float64[] - ) - ``` -2. This makes the function robust across DataFrames.jl versions. - -**Verification:** -```julia -using Cliometrics, DataFrames -data = DataFrame( - year = repeat(1950:1960, 2), - region = repeat(["Europe", "Asia"], inner=11), - gdp_per_capita = vcat( - [1000, 1100, 1210, 1331, 1464, 1610, 1771, 1948, 2143, 2357, 2593], - [500, 525, 551, 579, 608, 638, 670, 703, 738, 775, 814] - ) .* 1.0 -) -result = compare_historical_trajectories(data, ["Europe", "Asia"]) -@assert nrow(result) == 2 -@assert eltype(result.region) <: AbstractString -@assert eltype(result.avg_growth) <: AbstractFloat -println("TASK 13 PASSED") -``` - ---- - -## TASK 14: Add `:spline` method to `clean_historical_series` (LOW) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/src/Cliometrics.jl` - -**Problem:** The docstring on line 313 lists `:spline` as a valid method option, but the implementation (lines 327-361) only handles `:linear` and `:forward_fill`. If a user calls `clean_historical_series(data, method=:spline)`, it silently returns the uncleaned data since neither branch matches. - -**What to do:** -1. Either implement a simple spline interpolation (cubic), or -2. Add an `else` clause that throws an informative error: `error("Unknown method: $method. Use :linear, :spline, or :forward_fill")` -3. If implementing spline: use a natural cubic spline between known points. You may use `StatsBase` or implement a basic version. Given that the package already depends on `StatsBase`, check if it provides interpolation utilities. -4. If spline is too complex to implement cleanly, remove `:spline` from the docstring on line 313 and add the error clause. - -**Verification:** -```julia -using Cliometrics -# If spline is implemented: -data = [100.0, 105.0, NaN, NaN, 120.0] -cleaned = clean_historical_series(data, method=:spline) -@assert length(cleaned) == 5 -@assert all(isfinite.(cleaned)) -println("TASK 14 PASSED") - -# OR if spline is removed, verify error: -try - clean_historical_series([1.0, 2.0], method=:spline) - error("Should have thrown") -catch e - @assert occursin("Unknown method", e.msg) "Should throw informative error" - println("TASK 14 PASSED (spline removed, error added)") -end -``` - ---- - -## TASK 15: Fix Dustfile and Intentfile SPDX typo (LOW) - -**Files:** -- `/var$REPOS_DIR/Cliometrics.jl/contractiles/dust/Dustfile` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/contractiles/lust/Intentfile` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/contractiles/must/Mustfile` (line 1) -- `/var$REPOS_DIR/Cliometrics.jl/contractiles/trust/Trustfile.hs` (line 1) - -**Problem:** These files use `PLMP-1.0-or-later` which is a typo. The correct identifier is `MPL-2.0` (Palimpsest License). - -**What to do:** -1. In each file, replace `PLMP-1.0-or-later` with `MPL-2.0` on line 1. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl && grep -rn "PLMP" contractiles/ -# Should return zero lines -grep -rn "PMPL" contractiles/dust/Dustfile contractiles/lust/Intentfile contractiles/must/Mustfile contractiles/trust/Trustfile.hs -# Should return 4 lines, one per file -``` - ---- - -## TASK 16: Add README claim reconciliation — remove or implement claimed features (LOW) - -**Files:** `/var$REPOS_DIR/Cliometrics.jl/README.md` - -**Problem:** The README.md (lines 69-84) claims the following features that have NO implementation: -- "Sigma-convergence testing" (line 71) -- only beta-convergence exists -- "Conditional convergence estimation" (line 72) -- not implemented -- "Long-run growth trend analysis" (line 67) -- not implemented -- "Institutional change measurement" (line 78) -- partially addressed by Task 2 -- "Outlier detection and handling" (line 83) -- not implemented -- "Cross-country data alignment" (line 84) -- not implemented - -**What to do:** -1. For features completed by Tasks 1-4, verify they are accurately described. -2. For features NOT implemented (sigma-convergence, conditional convergence, long-run trends, outlier detection, cross-country alignment), either: - a. Mark them as "Planned" or "Coming in v0.2.0" in the README, or - b. Remove them from the feature list entirely. -3. Do NOT claim features that do not exist in the code. - -**Verification:** -```bash -cd /var$REPOS_DIR/Cliometrics.jl -# Manually verify: every feature listed in README.md has a corresponding exported function -grep -oP '(?<=- ).*' README.md | head -20 -# Cross-reference with: -grep "^ " src/Cliometrics.jl | head -20 # exported functions -``` - ---- - -## FINAL VERIFICATION - -After all tasks are complete, run the following sequence: - -```bash -cd /var$REPOS_DIR/Cliometrics.jl - -# 1. Full test suite -julia --project=. -e 'using Pkg; Pkg.test()' - -# 2. No AGPL references remain -grep -rn "AGPL-3.0" . --include="*.scm" --include="*.zig" --include="*.res" --include="*.adoc" --include="*.jl" | grep -v ".git/" | grep -v "SONNET-TASKS" - -# 3. No template placeholders remain -grep -rn '{{PROJECT}}\|{{project}}\|{{OWNER}}\|{{REPO}}\|{{FORGE}}\|\[YOUR-REPO-NAME\]' . --include="*.idr" --include="*.zig" --include="*.md" --include="*.a2ml" --include="*.adoc" | grep -v ".git/" | grep -v "SONNET-TASKS" - -# 4. No PLMP typos remain -grep -rn "PLMP" . --include="*" | grep -v ".git/" | grep -v "SONNET-TASKS" - -# 5. No rsr-template-repo references in SCM files -grep -rn "rsr-template-repo" .machines_readable/ - -# 6. All exported functions have implementations -julia --project=. -e ' -using Cliometrics -for name in names(Cliometrics) - fn = getfield(Cliometrics, name) - if fn isa Function - println("OK: $name is defined") - end -end -' - -# 7. Verify the example runs -julia --project=. examples/growth_decomposition.jl -``` - -All 7 checks must pass with zero errors. If any fail, fix the root cause before declaring completion. diff --git a/packages/Cliometrics.jl/TOPOLOGY.md b/packages/Cliometrics.jl/TOPOLOGY.adoc similarity index 89% rename from packages/Cliometrics.jl/TOPOLOGY.md rename to packages/Cliometrics.jl/TOPOLOGY.adoc index d936152bb..a91b9021a 100644 --- a/packages/Cliometrics.jl/TOPOLOGY.md +++ b/packages/Cliometrics.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Cliometrics.jl — Project Topology -# Cliometrics.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ANALYSIS @@ -68,24 +64,25 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~85% Beta Phase (Refining Docs) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Historical Data ──────► Growth Accounting ──────► Convergence Analysis │ Institutional Analysis ──────► Causal Inference ◀─────┘ -``` +.... -## 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/packages/Exnovation.jl/CODE_OF_CONDUCT.adoc b/packages/Exnovation.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..e3d9f0f6f --- /dev/null +++ b/packages/Exnovation.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,340 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Exnovation.jl a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |jonathan.jewell@open.ac.uk |Detailed reports, sensitive +matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *72 hours* +. The Exnovation.jl Maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a Exnovation.jl Maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The Exnovation.jl Maintainers will follow these guidelines in +determining consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* jonathan.jewell@open.ac.uk with subject line "`Appeal: +[Original Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different Exnovation.jl Maintainers member +than the original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/Exnovation.jl/discussions[Discussion] +(for general questions) +* Email jonathan.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/Exnovation.jl/CODE_OF_CONDUCT.md b/packages/Exnovation.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index daca61525..000000000 --- a/packages/Exnovation.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,307 +0,0 @@ -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Exnovation.jl a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | jonathan.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **72 hours** -2. The Exnovation.jl Maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a Exnovation.jl Maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The Exnovation.jl Maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** jonathan.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different Exnovation.jl Maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/Exnovation.jl/discussions) (for general questions) -- Email jonathan.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/Exnovation.jl/CONTRIBUTING.adoc b/packages/Exnovation.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..acbd7d9e5 --- /dev/null +++ b/packages/Exnovation.jl/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/Exnovation.jl.git cd +Exnovation.jl + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create Exnovation.jl-dev toolbox enter Exnovation.jl-dev # +Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +Exnovation.jl/ ├── 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/Exnovation.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/Exnovation.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/Exnovation.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/Exnovation.jl/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/packages/Exnovation.jl/CONTRIBUTING.md b/packages/Exnovation.jl/CONTRIBUTING.md deleted file mode 100644 index 97f11a2d4..000000000 --- a/packages/Exnovation.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/Exnovation.jl.git -cd Exnovation.jl - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create Exnovation.jl-dev -toolbox enter Exnovation.jl-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -Exnovation.jl/ -├── 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/Exnovation.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/Exnovation.jl/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/Exnovation.jl/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/Exnovation.jl/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/packages/Exnovation.jl/README.adoc b/packages/Exnovation.jl/README.adoc index e883b4c01..cdfeb0d18 100644 --- a/packages/Exnovation.jl/README.adoc +++ b/packages/Exnovation.jl/README.adoc @@ -1,155 +1,165 @@ -= Exnovation.jl -:toc: macro +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +PMPL-1.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] -image:https://img.shields.io/badge/Project-Topology-9558B2[Topology,link="TOPOLOGY.md"] -image:https://img.shields.io/badge/Completion-100%25-green[100%,link="TOPOLOGY.md"] +== Exnovation.jl -A Julia framework for modeling **exnovation decisions**—phasing out legacy practices to enable innovation. +Exnovation.jl is a Julia framework for modeling exnovation decisions: +phasing out legacy practices, products, or routines to make room for new +innovation. It is inspired by the conceptual treatment in Holbek & +Knudsen (2020) and is structured to capture drivers, barriers, and +decision criteria in a transparent way. -toc::[] +This package does *not* embed proprietary content; it provides a clean +model and simple scoring helpers so you can encode your own +organizational context. -== What is Exnovation.jl? - -Exnovation.jl is a **decision modeling framework** designed to help organizations and researchers systematically analyze, plan, and execute the phase-out of outdated technologies, processes, or practices. It provides tools to: - -- **Model legacy systems** and their dependencies -- **Simulate phase-out scenarios** and their impacts -- **Optimize transition paths** to minimize disruption -- **Validate exnovation strategies** with formal guarantees +=== Installation -=== Example: Modeling a Legacy Phase-Out +==== From Julia REPL [source,julia] ---- -using Exnovation - -@exnovate LegacySystem begin - legacy_process :: Process(legacy=true, cost=1000, risk=0.8) - new_process :: Process(legacy=false, cost=500, risk=0.2) +using Pkg +Pkg.add("Exnovation") +---- - transition = legacy_process --> new_process - @ensure transition.cost < 1500 - @ensure transition.risk < 0.5 -end +==== From Git (Development) -strategy = LegacySystem() -result = simulate(strategy, horizon=5) +[source,julia] +---- +using Pkg +Pkg.add(url="https://github.com/hyperpolymath/Exnovation.jl") ---- -== Features +=== Core Concepts + +* *Exnovation item*: a practice, product, or routine being considered +for phase-out. +* *Drivers*: forces pushing toward exnovation (e.g., regulatory +pressure, obsolete technology, sustainability targets). +* *Barriers*: cognitive, emotional, behavioral, or structural +resistance. +* *Intelligent failure*: planned experimentation with bounded risk and +deliberate learning checkpoints. +* *Decision criteria*: weighted factors such as sunk cost bias, +strategic fit, performance, and risk. +* *Debiasing actions*: prompts to counter sunk-cost and status-quo +effects. +* *Stage-gates*: thresholds that stop or advance exnovation decisions. +* *Impact model*: capex/opex savings plus public value. -=== Scenario Simulation -Simulate the impact of phasing out legacy systems over time, with support for: -- Cost-benefit analysis -- Risk assessment -- Resource allocation +=== Quick Start [source,julia] ---- -@exnovate EnergyTransition begin - coal :: EnergySource(legacy=true, emissions=1000) - solar :: EnergySource(legacy=false, emissions=0) +using Exnovation - transition = coal --> solar - @ensure transition.emissions_reduction > 90% -end ----- +item = ExnovationItem(:LegacyCRM, "Legacy CRM system", "Sales operations") -=== Dependency Mapping -Visualize and analyze dependencies between legacy and new systems to identify critical path dependencies and bottlenecks. +drivers = [ + Driver(:SecurityRisk, 0.7, "Legacy stack has known vulnerabilities"), + Driver(:Sustainability, 0.4, "Cloud move reduces footprint"), +] -[source,julia] ----- -dependencies = map_dependencies(legacy_system, new_system) -plot(dependencies) ----- +barriers = [ + Barrier(Cognitive, 0.5, "Sunk-cost framing in past investments"), + Barrier(Behavioral, 0.3, "Habits and routines tied to old workflows"), +] -=== Formal Validation -Ensure that exnovation strategies meet organizational constraints and regulatory requirements. +criteria = DecisionCriteria(0.3, 0.3, 0.2, 0.2) -[source,julia] ----- -@exnovate ComplianceCheck begin - old_policy :: Policy(legacy=true, compliance_risk=0.9) - new_policy :: Policy(legacy=false, compliance_risk=0.1) +assessment = ExnovationAssessment( + item, + drivers, + barriers, + criteria, + 1_200_000.0, # sunk_cost + 350_000.0, # forward_value + 900_000.0, # replacement_value + 0.4, # strategic_fit (lower is worse) + 0.6, # performance (lower is worse) + 0.7, # risk (higher is worse) +) - transition = old_policy --> new_policy - @prove transition.compliance_risk < 0.2 -end +score = exnovation_score(assessment) +println(score) +println(recommendation(assessment)) ---- -=== Integration with Julia Ecosystem -Leverage Julia’s data science and optimization tools for advanced analysis. - [source,julia] ---- -using DataFrames, Plots +# Intelligent failure readiness +criteria = IntelligentFailureCriteria( + 0.9, # planned_action + 0.7, # outcome_uncertainty + 0.8, # modest_scale + 0.9, # rapid_response + 0.8, # familiar_context + 0.7, # explicit_assumptions + 0.8, # checkpoint_learning +) -results = simulate(exnovation_strategy, iterations=1000) -df = DataFrame(results) -plot(df, x=:time, y=:cost, group=:scenario) +failure = FailureAssessment(Intelligent, criteria, 0.6, 0.7) +summary = failure_summary(failure) +println(summary.intelligent_failure_score) ---- -== Quick Start - -=== Installation [source,julia] ---- -using Pkg -Pkg.add("Exnovation") +# Decision pipeline and JSON report +case = ExnovationCase( + assessment, + failure, + RiskGovernance(0.5, 0.7, :govern), +) + +report = decision_pipeline(case) +write_report_json("exnovation_report.json", report) ---- -=== Hello World [source,julia] ---- -using Exnovation +# Portfolio scoring and budget allocation +impact = ImpactModel(100.0, 50.0, 0.9) +item = PortfolioItem(case, impact) -@exnovate SimpleTransition begin - old :: System(legacy=true, cost=100) - new :: System(legacy=false, cost=50) +scores = portfolio_scores([item]) +allocation = allocate_budget([item]; capex_budget=120.0) +---- - transition = old --> new - @ensure transition.cost < 120 -end +=== API Snapshot -strategy = SimpleTransition() -result = simulate(strategy) +[source,julia] ---- +BarrierType, Cognitive, Emotional, Behavioral, Structural, Political +FailureType, Preventable, Unavoidable, Intelligent +ExnovationItem, Driver, Barrier, DecisionCriteria +ExnovationAssessment, ExnovationSummary +IntelligentFailureCriteria, FailureAssessment, FailureSummary +RiskGovernance, ExnovationCase, DecisionReport +ImpactModel, PortfolioItem, StageGate +sunk_cost_bias_index, exnovation_score, recommendation +debiasing_actions, intelligent_failure_score, failure_summary +decision_pipeline, write_report_json +barrier_templates, run_stage_gates +portfolio_scores, allocate_budget +---- + +=== Conceptual Alignment -== Why Exnovation.jl? +The model is aligned with ideas from the Holbek & Knudsen manuscript on +exnovation: exnovation as making space for innovation, the role of +sunk-cost bias, and the impact of cognitive, emotional, and behavioral +barriers. -=== The Problem -Organizations often struggle to retire legacy systems due to: -- Complex dependencies -- Uncertain costs and risks -- Resistance to change +It also integrates the Hartley & Knell article on innovation, +intelligent failure, and exnovation by modeling intelligent failure +criteria and making them explicit in the decision flow. -=== The Solution -Exnovation.jl provides a **structured, data-driven approach** to exnovation, enabling: -- Evidence-based decision-making -- Transparent impact analysis -- Formal validation of transition plans +=== Development -== Project Structure -[source] +[source,bash] ---- -Exnovation.jl/ -├── src/ -│ ├── Exnovation.jl # Main module -│ ├── models/ # Exnovation models and DSL -│ ├── simulation/ # Scenario simulation tools -│ ├── validation/ # Formal validation framework -│ └── visualization/ # Dependency and impact visualization -├── test/ # Test suite -├── examples/ # Example exnovation scenarios -└── docs/ # Documentation +julia --project=. -e 'using Pkg; Pkg.instantiate()' +julia --project=. -e 'using Pkg; Pkg.test()' ---- - -== Roadmap -- ✓ **v0.1**: Core framework, basic simulation, and validation -- ❏ **v0.2**: Advanced dependency mapping and optimization -- ❏ **v0.3**: Integration with external data sources -- ❏ **v1.0**: Production-ready, with industry case studies - -== Acknowledgments -Exnovation.jl is inspired by research in sustainability, innovation management, and formal methods. Special thanks to the Julia community for their foundational work. diff --git a/packages/Exnovation.jl/README.md b/packages/Exnovation.jl/README.md deleted file mode 100644 index 78a8f6255..000000000 --- a/packages/Exnovation.jl/README.md +++ /dev/null @@ -1,153 +0,0 @@ -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] - -# Exnovation.jl - - - - -Exnovation.jl is a Julia framework for modeling exnovation decisions: phasing -out legacy practices, products, or routines to make room for new innovation. -It is inspired by the conceptual treatment in Holbek & Knudsen (2020) and is -structured to capture drivers, barriers, and decision criteria in a transparent -way. - -This package does **not** embed proprietary content; it provides a clean model -and simple scoring helpers so you can encode your own organizational context. - -## Installation - -### From Julia REPL -```julia -using Pkg -Pkg.add("Exnovation") -``` - -### From Git (Development) -```julia -using Pkg -Pkg.add(url="https://github.com/hyperpolymath/Exnovation.jl") -``` - -## Core Concepts - -- **Exnovation item**: a practice, product, or routine being considered for - phase-out. -- **Drivers**: forces pushing toward exnovation (e.g., regulatory pressure, - obsolete technology, sustainability targets). -- **Barriers**: cognitive, emotional, behavioral, or structural resistance. -- **Intelligent failure**: planned experimentation with bounded risk and - deliberate learning checkpoints. -- **Decision criteria**: weighted factors such as sunk cost bias, strategic fit, - performance, and risk. -- **Debiasing actions**: prompts to counter sunk-cost and status-quo effects. -- **Stage-gates**: thresholds that stop or advance exnovation decisions. -- **Impact model**: capex/opex savings plus public value. - -## Quick Start - -```julia -using Exnovation - -item = ExnovationItem(:LegacyCRM, "Legacy CRM system", "Sales operations") - -drivers = [ - Driver(:SecurityRisk, 0.7, "Legacy stack has known vulnerabilities"), - Driver(:Sustainability, 0.4, "Cloud move reduces footprint"), -] - -barriers = [ - Barrier(Cognitive, 0.5, "Sunk-cost framing in past investments"), - Barrier(Behavioral, 0.3, "Habits and routines tied to old workflows"), -] - -criteria = DecisionCriteria(0.3, 0.3, 0.2, 0.2) - -assessment = ExnovationAssessment( - item, - drivers, - barriers, - criteria, - 1_200_000.0, # sunk_cost - 350_000.0, # forward_value - 900_000.0, # replacement_value - 0.4, # strategic_fit (lower is worse) - 0.6, # performance (lower is worse) - 0.7, # risk (higher is worse) -) - -score = exnovation_score(assessment) -println(score) -println(recommendation(assessment)) -``` - -```julia -# Intelligent failure readiness -criteria = IntelligentFailureCriteria( - 0.9, # planned_action - 0.7, # outcome_uncertainty - 0.8, # modest_scale - 0.9, # rapid_response - 0.8, # familiar_context - 0.7, # explicit_assumptions - 0.8, # checkpoint_learning -) - -failure = FailureAssessment(Intelligent, criteria, 0.6, 0.7) -summary = failure_summary(failure) -println(summary.intelligent_failure_score) -``` - -```julia -# Decision pipeline and JSON report -case = ExnovationCase( - assessment, - failure, - RiskGovernance(0.5, 0.7, :govern), -) - -report = decision_pipeline(case) -write_report_json("exnovation_report.json", report) -``` - -```julia -# Portfolio scoring and budget allocation -impact = ImpactModel(100.0, 50.0, 0.9) -item = PortfolioItem(case, impact) - -scores = portfolio_scores([item]) -allocation = allocate_budget([item]; capex_budget=120.0) -``` - -## API Snapshot - -```julia -BarrierType, Cognitive, Emotional, Behavioral, Structural, Political -FailureType, Preventable, Unavoidable, Intelligent -ExnovationItem, Driver, Barrier, DecisionCriteria -ExnovationAssessment, ExnovationSummary -IntelligentFailureCriteria, FailureAssessment, FailureSummary -RiskGovernance, ExnovationCase, DecisionReport -ImpactModel, PortfolioItem, StageGate -sunk_cost_bias_index, exnovation_score, recommendation -debiasing_actions, intelligent_failure_score, failure_summary -decision_pipeline, write_report_json -barrier_templates, run_stage_gates -portfolio_scores, allocate_budget -``` - -## Conceptual Alignment - -The model is aligned with ideas from the Holbek & Knudsen manuscript on -exnovation: exnovation as making space for innovation, the role of sunk-cost -bias, and the impact of cognitive, emotional, and behavioral barriers. - -It also integrates the Hartley & Knell article on innovation, intelligent -failure, and exnovation by modeling intelligent failure criteria and making -them explicit in the decision flow. - -## Development - -```bash -julia --project=. -e 'using Pkg; Pkg.instantiate()' -julia --project=. -e 'using Pkg; Pkg.test()' -``` diff --git a/packages/Exnovation.jl/ROADMAP.adoc b/packages/Exnovation.jl/ROADMAP.adoc index 6cf5a10dd..5715f53f5 100644 --- a/packages/Exnovation.jl/ROADMAP.adoc +++ b/packages/Exnovation.jl/ROADMAP.adoc @@ -1,18 +1,165 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Roadmap -:revdate: 2026-02-17 - -== Release Baseline (Must) -- Package installs from a clean Julia environment (`Pkg.add`). -- Precompile, build, test, and module load smoke are gated in CI. -- Versioning stays semver and aligned with release refs/tags. - -== V2 Backlog (Should) -- Expand CI matrix (OS + Julia versions + optional dependency modes). -- Add performance baselines and regression checks. -- Improve machine-readable evidence and release artifact metadata. - -== V2 Backlog (Could) -- Add deeper formal verification evidence exports. -- Add optional accelerator/hardware strategy tracks where relevant. -- Add richer diagnostics and fault-recovery instrumentation. +== Exnovation.jl Development Roadmap + +=== Current State (v1.0) + +Production-ready exnovation decision framework: - Driver/barrier +analysis with cognitive bias detection - Sunk cost bias quantification - +Intelligent failure assessment (Edmondson framework) - Stage-gate +decision processes - Portfolio optimization with budget allocation - +Risk governance integration + +*Status:* Complete with 29 tests, examples, and comprehensive scoring +algorithms. + +''''' + +=== v1.0 → v1.2 Roadmap (Near-term) + +==== v1.1 - Decision Support & Reporting (3-6 months) + +*MUST:* - [ ] *Decision dashboards* - Interactive visualizations for +exnovation portfolios (Makie.jl/PlotlyLight.jl) - [ ] *Comparative +analysis* - Side-by-side comparison of multiple exnovation candidates - +[ ] *Temporal tracking* - Monitor exnovation decisions over time +(before/after analysis) - [ ] *Stakeholder impact analysis* - Assess +effects on teams, customers, partners + +*SHOULD:* - [ ] *Scenario modeling* - "`What-if`" simulations for +different market/regulatory conditions - [ ] *Bias mitigation playbooks* +- Structured debiasing interventions for each barrier type - [ ] +*Integration with financial systems* - Import cost data from +ERP/accounting tools - [ ] *Regulatory compliance tracking* - Map +exnovation to compliance requirements (GDPR, SOX, etc.) + +*COULD:* - [ ] *Gamification* - Points/badges for teams practicing +intelligent failure - [ ] *Social network analysis* - Identify political +barriers through organizational network mapping - [ ] *Natural language +processing* - Extract drivers/barriers from meeting transcripts + +==== v1.2 - Organizational Learning & AI (6-12 months) + +*MUST:* - [x] *Just Sustainability Index (JSI)* - Evaluate +equity/environment tradeoffs in exnovation decisions. - [ ] *Failure +knowledge base* - Structured repository of intelligent failures with +searchable lessons - [ ] *Recommendation engine* - ML-based suggestions +for exnovation candidates (analyze historical patterns) - [ ] +*Post-mortem automation* - Guided failure retrospectives with automatic +classification - [ ] *Integration with Causals.jl* - Causal analysis of +why exnovations succeeded/failed + +*SHOULD:* - [ ] *Organizational network effects* - Model how exnovation +decisions cascade through the org - [ ] *Cultural assessment* - +Psychological safety metrics, innovation climate surveys - [ ] +*Benchmarking database* - Compare exnovation rates against industry +peers - [ ] *Integration with BowtieRisk.jl* - Risk-weighted exnovation +prioritization + +*COULD:* - [ ] *Predictive analytics* - Forecast which legacy systems +are exnovation candidates (usage trends, tech debt) - [ ] *A/B testing +framework* - Structured experiments for pilot exnovations - [ ] +*Real-time decision support* - Slack/Teams bot that prompts exnovation +questions during planning + +''''' + +=== v1.3+ Roadmap (Speculative) + +==== Research Frontiers + +*Behavioral Economics & AI:* - Large language model integration +(GPT-based bias detection in written rationales) - Reinforcement +learning for optimal exnovation timing (learn from historical outcomes) +- Emotion AI (sentiment analysis of team reactions to exnovation +proposals) - Neuroeconomics (fMRI-informed models of sunk cost fallacy) + +*Organizational Dynamics:* - Agent-based modeling of exnovation +diffusion in organizations (tipping points, champions) - Network theory +for political barrier analysis (influence maximization, coalition +building) - Evolutionary game theory (survival of the fittest +products/processes) - Complex adaptive systems (emergent exnovation +patterns) + +*Formal Methods:* - Proof-carrying exnovation decisions (verified +compliance with governance rules) - Temporal logic for stage-gate +constraints (must complete A before B) - Integration with Axiom.jl for +decision audit trails + +*Global Innovation Systems:* - Cross-organizational exnovation networks +(shared learning across competitors) - Open innovation platforms +(crowdsource exnovation ideas) - Policy impact modeling (how regulation +shapes exnovation rates) + +==== Ecosystem Integration + +* *DataFrames.jl/Tidier.jl:* Advanced portfolio analytics +* *Turing.jl:* Bayesian inference for uncertainty in driver/barrier +scores +* *Agents.jl:* Simulate organizational dynamics of exnovation adoption +* *MLJ.jl:* Machine learning for failure classification and prediction + +==== Ambitious Features + +* *Exnovation foundation model* - Pre-trained on 10K+ real exnovation +cases (startups, enterprises, governments) +* *Autonomous exnovation advisor* - AI agent that monitors org and +proposes exnovation candidates +* *Global exnovation index* - Public dataset of exnovation rates by +industry/region +* *Virtual exnovation lab* - Safe sandbox for testing high-risk +exnovations (digital twin + simulation) + +''''' + +=== Future Horizons (v2.0+) + +==== AI-Driven Cognitive Debiaser + +* [ ] *Real-time Bias Intervention*: Integration with LLMs to analyze +meeting transcripts or project documentation and flag specific cognitive +biases (Sunk Cost, Loss Aversion, Status Quo) as they occur. +* [ ] *Adversarial Red-Teaming*: Use AI agents to generate +"`Counter-Arguments`" for every exnovation decision to ensure robust +reasoning and avoid groupthink. + +==== Exnovation Digital Twins + +* [ ] *Dependency Graph Simulation*: Map the "`Process Ecosystem`" of an +organization and simulate the downstream impact of removing a specific +product or practice before it happens. +* [ ] *Systemic Fragility Assessment*: Quantify how exnovating a +specific legacy component affects the overall resilience of the +organization. + +==== Recursive & Meta-Exnovation + +* [ ] *Process Exnovation*: Tools to model and phase out the +"`Exnovation Process`" itself when it becomes bureaucratic or +ineffective. +* [ ] *Automated Weight Tuning*: Use historical outcome data to +automatically optimize the weights in the `+DecisionCriteria+` model. + +==== Ethical & Social Exnovation + +* [ ] *Impact Equity Verification*: Link with `+Axiology.jl+` to +formally verify that phasing out a legacy system (e.g., cash payments or +old UI) doesn’t disproportionately harm vulnerable populations. +* [ ] *Cultural Legacy Preservation*: Frameworks for "`Digital +Archiving`" of exnovated practices to preserve organizational knowledge +and heritage. + +''''' + +=== Migration Path + +*v1.0 → v1.1:* Backward compatible (new visualization/reporting +features) *v1.1 → v1.2:* Mostly compatible (ML features may require +additional data collection) *v1.2 → v1.3+:* Breaking changes possible +(AI integration may redesign core data structures) + +=== Community Goals + +* *10 corporate adoptions* by v1.2 +* *Academic publication* in Organization Science or similar by v1.2 +* *Workshop at Academy of Management conference* by v1.2 +* *Partnership with management consultancy* (BCG, McKinsey, Bain) for +real-world validation diff --git a/packages/Exnovation.jl/ROADMAP.md b/packages/Exnovation.jl/ROADMAP.md deleted file mode 100644 index 5bbf7018b..000000000 --- a/packages/Exnovation.jl/ROADMAP.md +++ /dev/null @@ -1,133 +0,0 @@ -# Exnovation.jl Development Roadmap - -## Current State (v1.0) - -Production-ready exnovation decision framework: -- Driver/barrier analysis with cognitive bias detection -- Sunk cost bias quantification -- Intelligent failure assessment (Edmondson framework) -- Stage-gate decision processes -- Portfolio optimization with budget allocation -- Risk governance integration - -**Status:** Complete with 29 tests, examples, and comprehensive scoring algorithms. - ---- - -## v1.0 → v1.2 Roadmap (Near-term) - -### v1.1 - Decision Support & Reporting (3-6 months) - -**MUST:** -- [ ] **Decision dashboards** - Interactive visualizations for exnovation portfolios (Makie.jl/PlotlyLight.jl) -- [ ] **Comparative analysis** - Side-by-side comparison of multiple exnovation candidates -- [ ] **Temporal tracking** - Monitor exnovation decisions over time (before/after analysis) -- [ ] **Stakeholder impact analysis** - Assess effects on teams, customers, partners - -**SHOULD:** -- [ ] **Scenario modeling** - "What-if" simulations for different market/regulatory conditions -- [ ] **Bias mitigation playbooks** - Structured debiasing interventions for each barrier type -- [ ] **Integration with financial systems** - Import cost data from ERP/accounting tools -- [ ] **Regulatory compliance tracking** - Map exnovation to compliance requirements (GDPR, SOX, etc.) - -**COULD:** -- [ ] **Gamification** - Points/badges for teams practicing intelligent failure -- [ ] **Social network analysis** - Identify political barriers through organizational network mapping -- [ ] **Natural language processing** - Extract drivers/barriers from meeting transcripts - -### v1.2 - Organizational Learning & AI (6-12 months) - -**MUST:** -- [x] **Just Sustainability Index (JSI)** - Evaluate equity/environment tradeoffs in exnovation decisions. -- [ ] **Failure knowledge base** - Structured repository of intelligent failures with searchable lessons -- [ ] **Recommendation engine** - ML-based suggestions for exnovation candidates (analyze historical patterns) -- [ ] **Post-mortem automation** - Guided failure retrospectives with automatic classification -- [ ] **Integration with Causals.jl** - Causal analysis of why exnovations succeeded/failed - -**SHOULD:** -- [ ] **Organizational network effects** - Model how exnovation decisions cascade through the org -- [ ] **Cultural assessment** - Psychological safety metrics, innovation climate surveys -- [ ] **Benchmarking database** - Compare exnovation rates against industry peers -- [ ] **Integration with BowtieRisk.jl** - Risk-weighted exnovation prioritization - -**COULD:** -- [ ] **Predictive analytics** - Forecast which legacy systems are exnovation candidates (usage trends, tech debt) -- [ ] **A/B testing framework** - Structured experiments for pilot exnovations -- [ ] **Real-time decision support** - Slack/Teams bot that prompts exnovation questions during planning - ---- - -## v1.3+ Roadmap (Speculative) - -### Research Frontiers - -**Behavioral Economics & AI:** -- Large language model integration (GPT-based bias detection in written rationales) -- Reinforcement learning for optimal exnovation timing (learn from historical outcomes) -- Emotion AI (sentiment analysis of team reactions to exnovation proposals) -- Neuroeconomics (fMRI-informed models of sunk cost fallacy) - -**Organizational Dynamics:** -- Agent-based modeling of exnovation diffusion in organizations (tipping points, champions) -- Network theory for political barrier analysis (influence maximization, coalition building) -- Evolutionary game theory (survival of the fittest products/processes) -- Complex adaptive systems (emergent exnovation patterns) - -**Formal Methods:** -- Proof-carrying exnovation decisions (verified compliance with governance rules) -- Temporal logic for stage-gate constraints (must complete A before B) -- Integration with Axiom.jl for decision audit trails - -**Global Innovation Systems:** -- Cross-organizational exnovation networks (shared learning across competitors) -- Open innovation platforms (crowdsource exnovation ideas) -- Policy impact modeling (how regulation shapes exnovation rates) - -### Ecosystem Integration - -- **DataFrames.jl/Tidier.jl:** Advanced portfolio analytics -- **Turing.jl:** Bayesian inference for uncertainty in driver/barrier scores -- **Agents.jl:** Simulate organizational dynamics of exnovation adoption -- **MLJ.jl:** Machine learning for failure classification and prediction - -### Ambitious Features - -- **Exnovation foundation model** - Pre-trained on 10K+ real exnovation cases (startups, enterprises, governments) -- **Autonomous exnovation advisor** - AI agent that monitors org and proposes exnovation candidates -- **Global exnovation index** - Public dataset of exnovation rates by industry/region -- **Virtual exnovation lab** - Safe sandbox for testing high-risk exnovations (digital twin + simulation) - ---- - -## Future Horizons (v2.0+) - -### AI-Driven Cognitive Debiaser -- [ ] **Real-time Bias Intervention**: Integration with LLMs to analyze meeting transcripts or project documentation and flag specific cognitive biases (Sunk Cost, Loss Aversion, Status Quo) as they occur. -- [ ] **Adversarial Red-Teaming**: Use AI agents to generate "Counter-Arguments" for every exnovation decision to ensure robust reasoning and avoid groupthink. - -### Exnovation Digital Twins -- [ ] **Dependency Graph Simulation**: Map the "Process Ecosystem" of an organization and simulate the downstream impact of removing a specific product or practice before it happens. -- [ ] **Systemic Fragility Assessment**: Quantify how exnovating a specific legacy component affects the overall resilience of the organization. - -### Recursive & Meta-Exnovation -- [ ] **Process Exnovation**: Tools to model and phase out the "Exnovation Process" itself when it becomes bureaucratic or ineffective. -- [ ] **Automated Weight Tuning**: Use historical outcome data to automatically optimize the weights in the `DecisionCriteria` model. - -### Ethical & Social Exnovation -- [ ] **Impact Equity Verification**: Link with `Axiology.jl` to formally verify that phasing out a legacy system (e.g., cash payments or old UI) doesn't disproportionately harm vulnerable populations. -- [ ] **Cultural Legacy Preservation**: Frameworks for "Digital Archiving" of exnovated practices to preserve organizational knowledge and heritage. - ---- - -## Migration Path - -**v1.0 → v1.1:** Backward compatible (new visualization/reporting features) -**v1.1 → v1.2:** Mostly compatible (ML features may require additional data collection) -**v1.2 → v1.3+:** Breaking changes possible (AI integration may redesign core data structures) - -## Community Goals - -- **10 corporate adoptions** by v1.2 -- **Academic publication** in Organization Science or similar by v1.2 -- **Workshop at Academy of Management conference** by v1.2 -- **Partnership with management consultancy** (BCG, McKinsey, Bain) for real-world validation diff --git a/packages/Exnovation.jl/SECURITY.adoc b/packages/Exnovation.jl/SECURITY.adoc new file mode 100644 index 000000000..e5674531f --- /dev/null +++ b/packages/Exnovation.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/Exnovation.jl/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |jonathan.jewell@open.ac.uk +|*PGP Key* |link:(not%20yet%20configured)[Download Public Key] +|*Fingerprint* |`+(not yet configured)+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL (not yet configured) | gpg --import + +# Verify fingerprint +gpg --fingerprint jonathan.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient jonathan.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/Exnovation.jl+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/Exnovation.jl/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Exnovation.jl, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:(not%20yet%20configured)[Our PGP Public Key] +* https://github.com/hyperpolymath/Exnovation.jl/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/Exnovation.jl/security/advisories/new[Report +via GitHub] or jonathan.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/Exnovation.jl/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Exnovation.jl and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/packages/Exnovation.jl/SECURITY.md b/packages/Exnovation.jl/SECURITY.md deleted file mode 100644 index 7676e06d6..000000000 --- a/packages/Exnovation.jl/SECURITY.md +++ /dev/null @@ -1,388 +0,0 @@ -# Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/Exnovation.jl/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | jonathan.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key]((not yet configured)) | -| **Fingerprint** | `(not yet configured)` | - -```bash -# Import our PGP key -curl -sSL (not yet configured) | gpg --import - -# Verify fingerprint -gpg --fingerprint jonathan.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient jonathan.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/Exnovation.jl`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/Exnovation.jl/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Exnovation.jl, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]((not yet configured)) -- [Security Advisories](https://github.com/hyperpolymath/Exnovation.jl/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/Exnovation.jl/security/advisories/new) or jonathan.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/Exnovation.jl/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Exnovation.jl and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/packages/Exnovation.jl/SONNET-TASKS.adoc b/packages/Exnovation.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..2c948e2d4 --- /dev/null +++ b/packages/Exnovation.jl/SONNET-TASKS.adoc @@ -0,0 +1,605 @@ +== SONNET-TASKS.md — Exnovation.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 72% +____ + +The Julia core library (`+src/Exnovation.jl+`) is genuinely complete: 14 +exported functions, 12 exported types, 2 enums, all with implementations +and docstrings, and a test suite with 29+ assertions. However, the repo +is littered with uncustomized RSR template files, wrong license headers, +a missing documentation page, a missing `+.machine_readable/+` +directory, a version mismatch, and a `+debiasing_actions+` gap. The +ABI/FFI scaffolding (Idris2 + Zig) is entirely boilerplate with +`+{{PROJECT}}+` placeholders – these template files add no value for a +pure-Julia package. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update STATE.scm with honest completion percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/Exnovation.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix Version Mismatch Between Project.toml and Manifest.toml (HIGH) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/Project.toml+` (line 4), +`+/var$REPOS_DIR/Exnovation.jl/Manifest.toml+` (line 16) + +*Problem:* `+Project.toml+` declares `+version = "1.0.0"+` but +`+Manifest.toml+` records the package as `+version = "0.1.0"+`. The +`+Manifest.toml+` is stale from an older `+Project.toml+` version. This +means anyone running `+Pkg.instantiate()+` will get a mismatched +manifest. + +*What to do:* 1. Delete `+Manifest.toml+` entirely. It will be +regenerated from `+Project.toml+`. 2. Run +`+julia --project=. -e 'using Pkg; Pkg.instantiate()'+` to regenerate +it. 3. Verify the regenerated `+Manifest.toml+` shows +`+version = "1.0.0"+` for Exnovation. + +*Verification:* + +[source,julia] +---- +cd("/var$REPOS_DIR/Exnovation.jl") +toml = Pkg.TOML.parsefile("Project.toml") +manifest = Pkg.TOML.parsefile("Manifest.toml") +@assert toml["version"] == "1.0.0" "Project.toml version must be 1.0.0" +# Find Exnovation entry in manifest deps +exnov_entry = manifest["deps"]["Exnovation"][1] +@assert exnov_entry["version"] == "1.0.0" "Manifest must match Project.toml version" +println("PASS: versions match") +---- + +''''' + +=== TASK 2: Add Missing `+Political+` Case to `+debiasing_actions+` (HIGH) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/src/Exnovation.jl+` (lines +234-249) + +*Problem:* The `+debiasing_actions+` function handles `+Cognitive+`, +`+Emotional+`, `+Behavioral+`, and `+Structural+` barriers but silently +ignores `+Political+` barriers. The `+BarrierType+` enum (line 19) +includes `+Political+`, and `+barrier_templates()+` (line 342) creates +`+Political+` barriers. Passing a `+Political+` barrier to +`+debiasing_actions+` produces an empty result with no warning. + +*What to do:* 1. Add an `+elseif barrier.kind == Political+` branch +after the `+Structural+` branch (after line 245). 2. Push two debiasing +actions for Political barriers: - +`+"Map stakeholder influence and build coalition support for the transition."+` +- +`+"Communicate reputational benefits and de-risk through staged rollout."+` +3. Add a test in `+test/runtests.jl+` that passes a `+Political+` +barrier and asserts the result is non-empty. + +*Verification:* + +[source,julia] +---- +using Exnovation +political_barriers = [Barrier(Political, 0.5, "Stakeholder resistance")] +actions = debiasing_actions(political_barriers) +@assert length(actions) >= 1 "Political barriers must produce debiasing actions" +@assert any(contains(a, "stakeholder") || contains(a, "Stakeholder") for a in actions) "Must mention stakeholders" +println("PASS: Political debiasing actions work") +---- + +''''' + +=== TASK 3: Create Missing `+docs/src/api.md+` (HIGH) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/docs/make.jl+` (line 12), +`+/var$REPOS_DIR/Exnovation.jl/docs/src/api.md+` (MISSING) + +*Problem:* `+docs/make.jl+` line 12 declares +`+pages = ["Home" => "index.md", "API" => "api.md"]+`. The file +`+docs/src/api.md+` does not exist. Running `+makedocs()+` will fail or +produce a broken documentation site. + +*What to do:* 1. Create +`+/var$REPOS_DIR/Exnovation.jl/docs/src/api.md+`. 2. Add an SPDX header +comment (use HTML comment since it is Markdown). 3. Add a title +`+# API Reference+`. 4. Use Documenter.jl `+@autodocs+` or `+@docs+` +blocks to auto-generate documentation from the docstrings in +`+src/Exnovation.jl+`. Include all 14 exported functions and 12 exported +types. Example: + +[source,markdown] +---- +# API Reference + +## Types + +```@docs +ExnovationItem +Driver +Barrier +DecisionCriteria +ExnovationAssessment +ExnovationSummary +IntelligentFailureCriteria +FailureAssessment +FailureSummary +RiskGovernance +ExnovationCase +DecisionReport +ImpactModel +PortfolioItem +StageGate +---- + +=== Enums + +[source,@docs] +---- +BarrierType +FailureType +---- + +=== Functions + +[source,@docs] +---- +sunk_cost_bias_index +exnovation_score +recommendation +debiasing_actions +intelligent_failure_score +failure_summary +decision_pipeline +write_report_json +barrier_templates +run_stage_gates +portfolio_scores +allocate_budget +---- + +.... + +**Verification:** +```julia +@assert isfile("/var$REPOS_DIR/Exnovation.jl/docs/src/api.md") "api.md must exist" +content = read("/var$REPOS_DIR/Exnovation.jl/docs/src/api.md", String) +@assert contains(content, "ExnovationItem") "Must document ExnovationItem" +@assert contains(content, "exnovation_score") "Must document exnovation_score" +@assert contains(content, "allocate_budget") "Must document allocate_budget" +println("PASS: api.md exists and documents key exports") +.... + +''''' + +=== TASK 4: Update `+docs/src/index.md+` Placeholder (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/docs/src/index.md+` (line 17) + +*Problem:* Line 17 says `+# Examples coming soon+` – this is a +placeholder. The repo has two complete examples in `+examples/+` and a +full Quick Start in `+README.md+`. + +*What to do:* 1. Replace `+# Examples coming soon+` with an actual Quick +Start code example, adapted from the `+README.md+` Quick Start section +(lines 48-81). 2. Add a brief description of the package (1-2 sentences +from `+README.md+` lines 8-10). 3. Mention the two example files: +`+examples/01_basic_usage.jl+` and +`+examples/02_portfolio_management.jl+`. + +*Verification:* + +[source,julia] +---- +content = read("/var$REPOS_DIR/Exnovation.jl/docs/src/index.md", String) +@assert !contains(content, "coming soon") "Must remove 'coming soon' placeholder" +@assert contains(content, "ExnovationItem") "Must include actual code example" +println("PASS: index.md updated with real content") +---- + +''''' + +=== TASK 5: Fix AGPL-3.0 License Headers (Must Be MPL-2.0) (HIGH) + +*Files:* - `+/var$REPOS_DIR/Exnovation.jl/ffi/zig/build.zig+` (line 2) - +`+/var$REPOS_DIR/Exnovation.jl/ffi/zig/src/main.zig+` (line 6) - +`+/var$REPOS_DIR/Exnovation.jl/ffi/zig/test/integration_test.zig+` (line +2) - `+/var$REPOS_DIR/Exnovation.jl/examples/SafeDOMExample.res+` (line +1) - `+/var$REPOS_DIR/Exnovation.jl/docs/CITATIONS.adoc+` (line 13) + +*Problem:* Five files use `+SPDX-License-Identifier: CC-BY-SA-4.0+`. Per +CLAUDE.md license policy: "`NEVER use AGPL-3.0 (old license, replaced by +MPL-2.0)`". The `+docs/CITATIONS.adoc+` also says +`+license = {AGPL-3.0-or-later}+` in the BibTeX block. + +*What to do:* 1. In each of the 5 files listed, replace +`+AGPL-3.0-or-later+` with `+MPL-2.0+`. 2. In `+docs/CITATIONS.adoc+`, +also fix the project name from `+rsr-template-repo+` to +`+Exnovation.jl+`, the author from `+Polymath, Hyper+` to +`+Jewell, Jonathan D.A.+`, the year to `+2026+`, and the URL to +`+https://github.com/hyperpolymath/Exnovation.jl+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +count=$(grep -r "AGPL-3.0" --include="*.zig" --include="*.res" --include="*.adoc" . | wc -l) +if [ "$count" -eq 0 ]; then echo "PASS: no AGPL-3.0 references remain"; else echo "FAIL: $count AGPL-3.0 references found"; exit 1; fi +---- + +''''' + +=== TASK 6: Remove or Customize Boilerplate ABI/FFI Template Files (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Exnovation.jl/src/abi/Types.idr+` - +`+/var$REPOS_DIR/Exnovation.jl/src/abi/Layout.idr+` - +`+/var$REPOS_DIR/Exnovation.jl/src/abi/Foreign.idr+` - +`+/var$REPOS_DIR/Exnovation.jl/ffi/zig/build.zig+` - +`+/var$REPOS_DIR/Exnovation.jl/ffi/zig/src/main.zig+` - +`+/var$REPOS_DIR/Exnovation.jl/ffi/zig/test/integration_test.zig+` - +`+/var$REPOS_DIR/Exnovation.jl/ABI-FFI-README.md+` + +*Problem:* Exnovation.jl is a pure-Julia package. It has no C FFI, no +Zig build, and no Idris2 ABI. All 7 files above contain raw +`+{{PROJECT}}+` / `+{{project}}+` template placeholders that have never +been customized. They are non-functional boilerplate from +`+rsr-template-repo+` and will confuse users. + +*What to do:* 1. Delete all 7 files listed above. 2. Remove the empty +directories `+src/abi/+`, `+ffi/zig/src/+`, `+ffi/zig/test/+`, +`+ffi/zig/+`, and `+ffi/+` if they become empty. 3. In `+README.adoc+`, +remove or rewrite the ABI/FFI section (lines 5-34 and lines 36-101) so +it describes Exnovation.jl instead of RSR template boilerplate. Replace +the entire file content with a brief pointer: `+= Exnovation.jl+` +followed by `+See README.md for full documentation.+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +if [ -d "src/abi" ]; then echo "FAIL: src/abi/ still exists"; exit 1; fi +if [ -d "ffi" ]; then echo "FAIL: ffi/ still exists"; exit 1; fi +if [ -f "ABI-FFI-README.md" ]; then echo "FAIL: ABI-FFI-README.md still exists"; exit 1; fi +count=$(grep -r '{{PROJECT}}\|{{project}}' --include="*.idr" --include="*.zig" --include="*.md" . 2>/dev/null | wc -l) +if [ "$count" -eq 0 ]; then echo "PASS: no template placeholders remain in code"; else echo "FAIL: $count template placeholders found"; exit 1; fi +---- + +''''' + +=== TASK 7: Customize RSR Template Placeholders in Markdown Files (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/Exnovation.jl/CONTRIBUTING.md+` - +`+/var$REPOS_DIR/Exnovation.jl/CODE_OF_CONDUCT.md+` - +`+/var$REPOS_DIR/Exnovation.jl/SECURITY.md+` - +`+/var$REPOS_DIR/Exnovation.jl/ROADMAP.adoc+` - +`+/var$REPOS_DIR/Exnovation.jl/RSR_OUTLINE.adoc+` + +*Problem:* These files are raw RSR template copies with `+{{FORGE}}+`, +`+{{OWNER}}+`, `+{{REPO}}+`, `+{{PROJECT_NAME}}+`, +`+{{SECURITY_EMAIL}}+`, `+{{CONDUCT_EMAIL}}+`, `+{{CONDUCT_TEAM}}+`, +`+{{RESPONSE_TIME}}+`, `+{{CURRENT_YEAR}}+`, `+{{PGP_FINGERPRINT}}+`, +`+{{PGP_KEY_URL}}+`, `+{{WEBSITE}}+`, `+{{MAIN_BRANCH}}+` placeholders. + +`+ROADMAP.adoc+` is also a generic template that conflicts with the real +`+ROADMAP.md+`. + +*What to do:* 1. In `+CONTRIBUTING.md+`, replace: - `+{{FORGE}}+` with +`+github.com+` - `+{{OWNER}}+` with `+hyperpolymath+` - `+{{REPO}}+` +with `+Exnovation.jl+` - `+{{MAIN_BRANCH}}+` with `+main+` 2. In +`+CODE_OF_CONDUCT.md+`, replace: - `+{{PROJECT_NAME}}+` with +`+Exnovation.jl+` - `+{{OWNER}}+` with `+hyperpolymath+` - `+{{REPO}}+` +with `+Exnovation.jl+` - `+{{CONDUCT_EMAIL}}+` with +`+jonathan.jewell@open.ac.uk+` - `+{{CONDUCT_TEAM}}+` with +`+Exnovation.jl Maintainers+` - `+{{RESPONSE_TIME}}+` with `+72 hours+` +- `+{{CURRENT_YEAR}}+` with `+2026+` - `+{{FORGE}}+` with `+github.com+` +3. In `+SECURITY.md+`, replace: - `+{{PROJECT_NAME}}+` with +`+Exnovation.jl+` - `+{{OWNER}}+` with `+hyperpolymath+` - `+{{REPO}}+` +with `+Exnovation.jl+` - `+{{SECURITY_EMAIL}}+` with +`+jonathan.jewell@open.ac.uk+` - `+{{PGP_FINGERPRINT}}+` with +`+(not yet configured)+` - `+{{PGP_KEY_URL}}+` with +`+(not yet configured)+` - `+{{WEBSITE}}+` with +`+https://github.com/hyperpolymath/Exnovation.jl+` - +`+{{CURRENT_YEAR}}+` with `+2026+` 4. Delete `+ROADMAP.adoc+` (the real +roadmap is `+ROADMAP.md+`). 5. In `+RSR_OUTLINE.adoc+`, replace the +title on line 1 from `+= RSR Template Repository+` to +`+= Exnovation.jl RSR Outline+`. Replace the SPDX identifier on line 212 +from `+MPL-2.0-or-later+` (typo with doubled suffix) to `+MPL-2.0+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +count=$(grep -r '{{[A-Z_]*}}' CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md RSR_OUTLINE.adoc 2>/dev/null | wc -l) +if [ "$count" -eq 0 ]; then echo "PASS: no template placeholders in docs"; else echo "FAIL: $count placeholders remain"; exit 1; fi +if [ -f "ROADMAP.adoc" ]; then echo "FAIL: ROADMAP.adoc should be deleted"; exit 1; fi +echo "PASS: all template docs customized" +---- + +''''' + +=== TASK 8: Create `+.machine_readable/+` Directory with SCM Files (MEDIUM) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/.machine_readable/+` (MISSING) + +*Problem:* Per CLAUDE.md and the project’s own `+AI.djot+`, every +hyperpolymath repo must have `+.machine_readable/STATE.scm+`, +`+.machine_readable/ECOSYSTEM.scm+`, and `+.machine_readable/META.scm+`. +This directory does not exist. + +*What to do:* 1. Create directory +`+/var$REPOS_DIR/Exnovation.jl/.machine_readable/+`. 2. Create +`+STATE.scm+` with: - +`+(metadata (project . "Exnovation.jl") (updated . "2026-02-12"))+` - +`+(position (phase . maintenance) (maturity . production))+` - +`+(completion-percentage . 85)+` - `+(blockers . ())+` - Current status +note: core library complete, docs and template cleanup remaining. 3. +Create `+ECOSYSTEM.scm+` with: - Name: `+Exnovation.jl+` - Type: +`+julia-package+` - Purpose: +`+Exnovation decision framework for phase-out analysis+` - Related +projects: +`+(related-projects ((name . "BowtieRisk.jl") (relationship . "potential-consumer")))+` +4. Create `+META.scm+` with: - License: `+MPL-2.0+` - Author: +`+Jonathan D.A. Jewell+` - Architecture decision: single-module Julia +package, no FFI needed. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +for f in STATE.scm ECOSYSTEM.scm META.scm; do + if [ ! -f ".machine_readable/$f" ]; then echo "FAIL: .machine_readable/$f missing"; exit 1; fi +done +echo "PASS: .machine_readable/ directory with all SCM files" +---- + +''''' + +=== TASK 9: Remove Unrelated Example Files (LOW) + +*Files:* - `+/var$REPOS_DIR/Exnovation.jl/examples/SafeDOMExample.res+` +- `+/var$REPOS_DIR/Exnovation.jl/examples/web-project-deno.json+` + +*Problem:* These are RSR template examples for ReScript web projects. +They have nothing to do with Exnovation.jl (a Julia decision-framework +package). `+SafeDOMExample.res+` is a ReScript file demonstrating DOM +mounting. `+web-project-deno.json+` is a Deno configuration for ReScript +projects. Both are confusing detritus. + +*What to do:* 1. Delete `+examples/SafeDOMExample.res+`. 2. Delete +`+examples/web-project-deno.json+`. 3. Verify that +`+examples/01_basic_usage.jl+` and +`+examples/02_portfolio_management.jl+` remain untouched. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +if [ -f "examples/SafeDOMExample.res" ]; then echo "FAIL: SafeDOMExample.res should be deleted"; exit 1; fi +if [ -f "examples/web-project-deno.json" ]; then echo "FAIL: web-project-deno.json should be deleted"; exit 1; fi +if [ ! -f "examples/01_basic_usage.jl" ]; then echo "FAIL: 01_basic_usage.jl must exist"; exit 1; fi +if [ ! -f "examples/02_portfolio_management.jl" ]; then echo "FAIL: 02_portfolio_management.jl must exist"; exit 1; fi +echo "PASS: only Julia examples remain" +---- + +''''' + +=== TASK 10: Customize `+docs/CITATIONS.adoc+` (LOW) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/docs/CITATIONS.adoc+` + +*Problem:* This file is a raw RSR template copy. It references +`+rsr-template-repo+`, uses author `+Polymath, Hyper+`, year `+2025+`, +and the wrong URL. It also references non-existent `+CITATION.cff+` and +`+codemeta.json+` files. + +*What to do:* 1. Replace all instances of `+rsr-template-repo+` / +`+RSR-template-repo+` with `+Exnovation.jl+`. 2. Replace author +`+Polymath, Hyper+` with `+Jewell, Jonathan D.A.+` (BibTeX last-first) +and `+Hyper Polymath+` with `+Jonathan D.A. Jewell+`. 3. Replace year +`+2025+` with `+2026+`. 4. Replace the URL with +`+https://github.com/hyperpolymath/Exnovation.jl+`. 5. Fix the license +from `+AGPL-3.0-or-later+` to `+MPL-2.0+` (if not done in Task 5). 6. +Remove the "`See Also`" section referencing `+CITATION.cff+` and +`+codemeta.json+` (they do not exist), or create those files. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +content=$(cat docs/CITATIONS.adoc) +if echo "$content" | grep -q "rsr-template-repo"; then echo "FAIL: still references rsr-template-repo"; exit 1; fi +if echo "$content" | grep -q "AGPL"; then echo "FAIL: still references AGPL"; exit 1; fi +if echo "$content" | grep -q "Polymath, Hyper"; then echo "FAIL: wrong author name"; exit 1; fi +echo "PASS: CITATIONS.adoc customized" +---- + +''''' + +=== TASK 11: Pin Unpinned GitHub Actions in release.yml (LOW) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/.github/workflows/release.yml+` +(lines 46, 94, 108) + +*Problem:* Three action references use tag-only pins (`+@v4+`) instead +of SHA pins: - Line 46: `+actions/upload-artifact@v4+` - Line 94: +`+actions/upload-artifact@v4+` - Line 108: +`+actions/download-artifact@v4+` + +Per CLAUDE.md workflow standards, all actions must be SHA-pinned. + +*What to do:* 1. Replace `+actions/upload-artifact@v4+` on lines 46 and +94 with a SHA-pinned version. Use a current v4 SHA (e.g., +`+actions/upload-artifact@ea165f8d65b6db9a8b22b984b926f09f6cef9ab8+` or +look up the latest v4 tag SHA on the actions/upload-artifact repo). 2. +Replace `+actions/download-artifact@v4+` on line 108 with a SHA-pinned +version (e.g., +`+actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093+` +or look up the latest v4 tag SHA). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +count=$(grep -E 'uses:.*@v[0-9]+\s*$' .github/workflows/release.yml | wc -l) +if [ "$count" -eq 0 ]; then echo "PASS: all actions SHA-pinned"; else echo "FAIL: $count actions not SHA-pinned"; exit 1; fi +---- + +''''' + +=== TASK 12: Fix `+AI.a2ml+` Template References (LOW) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/AI.a2ml+` + +*Problem:* This file references `+rsr-template-repo+` (line 5) and paths +like `+.machines_readable/6scm/STATE.scm+` (line 9) and +`+.machines_readable/6scm/AGENTIC.scm+` (line 10). The correct path per +CLAUDE.md is `+.machine_readable/+` (no `+s+`, no `+6scm/+` +subdirectory). The file also does not mention Exnovation.jl at all. + +*What to do:* 1. Replace `+rsr-template-repo+` with `+Exnovation.jl+` on +line 5. 2. Replace `+.machines_readable/6scm/+` with +`+.machine_readable/+` throughout (lines 9-10). 3. Update the +description to mention exnovation decision-making. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +content=$(cat AI.a2ml) +if echo "$content" | grep -q "rsr-template-repo"; then echo "FAIL: still says rsr-template-repo"; exit 1; fi +if echo "$content" | grep -q "machines_readable"; then echo "FAIL: wrong directory name (has extra s)"; exit 1; fi +if echo "$content" | grep -q "6scm"; then echo "FAIL: references 6scm subdirectory"; exit 1; fi +echo "PASS: AI.a2ml references corrected" +---- + +''''' + +=== TASK 13: Add Input Validation to Public API Functions (LOW) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/src/Exnovation.jl+` + +*Problem:* The `+DecisionCriteria+` struct (lines 52-57) expects weights +in 0..1 but no validation is performed. Negative weights or weights > 1 +are silently accepted. Similarly, `+Driver+` and `+Barrier+` weights +have no validation. The `+_clamp01+` function clamps individual weights +during scoring, but the raw structs allow nonsensical values like +`+-5.0+` or `+100.0+` to be constructed without any warning. + +*What to do:* 1. Add a constructor function +`+DecisionCriteria(sw, sfw, pw, rw)+` that warns (via `+@warn+`) if any +weight is outside [0, 1]. Do NOT throw – just warn. The clamping in +scoring already handles the math, but users should know their inputs are +unusual. 2. Alternatively, add a +`+validate(criteria::DecisionCriteria)+` exported function that returns +a vector of warning strings. This is less intrusive. 3. Add a test that +constructs `+DecisionCriteria+` with out-of-range weights and verifies +that `+validate()+` returns warnings, or that scoring still works +correctly. + +*Verification:* + +[source,julia] +---- +using Exnovation +# Extreme values should not crash +bad_criteria = DecisionCriteria(-1.0, 2.0, 0.5, 0.5) +item = ExnovationItem(:test, "test", "test") +drivers = [Driver(:d, 0.5, "test")] +barriers = Barrier[] +a = ExnovationAssessment(item, drivers, barriers, bad_criteria, 100.0, 50.0, 0.0, 0.5, 0.5, 0.5) +s = exnovation_score(a) +@assert isfinite(s.total_score) "Score must be finite even with bad inputs" +println("PASS: out-of-range weights handled gracefully") +---- + +''''' + +=== TASK 14: Add `+permissions: read-all+` to CI Workflow (LOW) + +*Files:* `+/var$REPOS_DIR/Exnovation.jl/.github/workflows/ci.yml+` + +*Problem:* Per CLAUDE.md workflow validation checklist item 4: +"``+permissions: read-all+` at workflow level`". The CI workflow has no +`+permissions+` block at all. + +*What to do:* 1. Add `+permissions: read-all+` after the `+on:+` block +(after line 6) and before `+jobs:+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl +if grep -q "permissions:" .github/workflows/ci.yml; then echo "PASS: permissions block exists"; else echo "FAIL: no permissions block"; exit 1; fi +---- + +''''' + +=== FINAL VERIFICATION + +After all tasks are complete, run: + +[source,bash] +---- +cd /var$REPOS_DIR/Exnovation.jl + +echo "=== 1. Julia tests ===" +julia --project=. -e 'using Pkg; Pkg.test()' + +echo "=== 2. No AGPL references ===" +count=$(grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.idr" --include="*.res" --include="*.adoc" . 2>/dev/null | wc -l) +[ "$count" -eq 0 ] && echo "PASS" || echo "FAIL: $count AGPL references" + +echo "=== 3. No raw template placeholders in code ===" +count=$(grep -rn '{{[A-Za-z_]*}}' --include="*.jl" --include="*.zig" --include="*.idr" --include="*.yml" . 2>/dev/null | wc -l) +[ "$count" -eq 0 ] && echo "PASS" || echo "FAIL: $count placeholders" + +echo "=== 4. Machine-readable directory exists ===" +[ -f ".machine_readable/STATE.scm" ] && [ -f ".machine_readable/META.scm" ] && [ -f ".machine_readable/ECOSYSTEM.scm" ] && echo "PASS" || echo "FAIL" + +echo "=== 5. No stale ABI/FFI boilerplate ===" +[ ! -d "src/abi" ] && [ ! -d "ffi" ] && [ ! -f "ABI-FFI-README.md" ] && echo "PASS" || echo "FAIL" + +echo "=== 6. api.md exists ===" +[ -f "docs/src/api.md" ] && echo "PASS" || echo "FAIL" + +echo "=== 7. Version consistency ===" +julia --project=. -e ' + using Pkg + p = Pkg.TOML.parsefile("Project.toml") + m = Pkg.TOML.parsefile("Manifest.toml") + pv = p["version"] + mv = m["deps"]["Exnovation"][1]["version"] + @assert pv == mv "Version mismatch: Project=$pv Manifest=$mv" + println("PASS: versions match ($pv)") +' + +echo "=== 8. Political debiasing actions ===" +julia --project=. -e ' + using Exnovation + actions = debiasing_actions([Barrier(Political, 0.5, "test")]) + @assert length(actions) >= 1 "Political barriers must produce actions" + println("PASS: $(length(actions)) actions for Political barriers") +' + +echo "=== AUDIT COMPLETE ===" +---- diff --git a/packages/Exnovation.jl/SONNET-TASKS.md b/packages/Exnovation.jl/SONNET-TASKS.md deleted file mode 100644 index 6c39b44eb..000000000 --- a/packages/Exnovation.jl/SONNET-TASKS.md +++ /dev/null @@ -1,557 +0,0 @@ -# SONNET-TASKS.md --- Exnovation.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 72% - -The Julia core library (`src/Exnovation.jl`) is genuinely complete: 14 exported functions, -12 exported types, 2 enums, all with implementations and docstrings, and a test suite with -29+ assertions. However, the repo is littered with uncustomized RSR template files, -wrong license headers, a missing documentation page, a missing `.machine_readable/` -directory, a version mismatch, and a `debiasing_actions` gap. The ABI/FFI scaffolding -(Idris2 + Zig) is entirely boilerplate with `{{PROJECT}}` placeholders -- these template -files add no value for a pure-Julia package. - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update STATE.scm with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/Exnovation.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix Version Mismatch Between Project.toml and Manifest.toml (HIGH) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/Project.toml` (line 4), `/var$REPOS_DIR/Exnovation.jl/Manifest.toml` (line 16) - -**Problem:** `Project.toml` declares `version = "1.0.0"` but `Manifest.toml` records the -package as `version = "0.1.0"`. The `Manifest.toml` is stale from an older `Project.toml` -version. This means anyone running `Pkg.instantiate()` will get a mismatched manifest. - -**What to do:** -1. Delete `Manifest.toml` entirely. It will be regenerated from `Project.toml`. -2. Run `julia --project=. -e 'using Pkg; Pkg.instantiate()'` to regenerate it. -3. Verify the regenerated `Manifest.toml` shows `version = "1.0.0"` for Exnovation. - -**Verification:** -```julia -cd("/var$REPOS_DIR/Exnovation.jl") -toml = Pkg.TOML.parsefile("Project.toml") -manifest = Pkg.TOML.parsefile("Manifest.toml") -@assert toml["version"] == "1.0.0" "Project.toml version must be 1.0.0" -# Find Exnovation entry in manifest deps -exnov_entry = manifest["deps"]["Exnovation"][1] -@assert exnov_entry["version"] == "1.0.0" "Manifest must match Project.toml version" -println("PASS: versions match") -``` - ---- - -## TASK 2: Add Missing `Political` Case to `debiasing_actions` (HIGH) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/src/Exnovation.jl` (lines 234-249) - -**Problem:** The `debiasing_actions` function handles `Cognitive`, `Emotional`, `Behavioral`, -and `Structural` barriers but silently ignores `Political` barriers. The `BarrierType` enum -(line 19) includes `Political`, and `barrier_templates()` (line 342) creates `Political` -barriers. Passing a `Political` barrier to `debiasing_actions` produces an empty result -with no warning. - -**What to do:** -1. Add an `elseif barrier.kind == Political` branch after the `Structural` branch (after line 245). -2. Push two debiasing actions for Political barriers: - - `"Map stakeholder influence and build coalition support for the transition."` - - `"Communicate reputational benefits and de-risk through staged rollout."` -3. Add a test in `test/runtests.jl` that passes a `Political` barrier and asserts the - result is non-empty. - -**Verification:** -```julia -using Exnovation -political_barriers = [Barrier(Political, 0.5, "Stakeholder resistance")] -actions = debiasing_actions(political_barriers) -@assert length(actions) >= 1 "Political barriers must produce debiasing actions" -@assert any(contains(a, "stakeholder") || contains(a, "Stakeholder") for a in actions) "Must mention stakeholders" -println("PASS: Political debiasing actions work") -``` - ---- - -## TASK 3: Create Missing `docs/src/api.md` (HIGH) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/docs/make.jl` (line 12), `/var$REPOS_DIR/Exnovation.jl/docs/src/api.md` (MISSING) - -**Problem:** `docs/make.jl` line 12 declares `pages = ["Home" => "index.md", "API" => "api.md"]`. -The file `docs/src/api.md` does not exist. Running `makedocs()` will fail or produce a broken -documentation site. - -**What to do:** -1. Create `/var$REPOS_DIR/Exnovation.jl/docs/src/api.md`. -2. Add an SPDX header comment (use HTML comment since it is Markdown). -3. Add a title `# API Reference`. -4. Use Documenter.jl `@autodocs` or `@docs` blocks to auto-generate documentation - from the docstrings in `src/Exnovation.jl`. Include all 14 exported functions - and 12 exported types. Example: - -```markdown -# API Reference - -## Types - -```@docs -ExnovationItem -Driver -Barrier -DecisionCriteria -ExnovationAssessment -ExnovationSummary -IntelligentFailureCriteria -FailureAssessment -FailureSummary -RiskGovernance -ExnovationCase -DecisionReport -ImpactModel -PortfolioItem -StageGate -``` - -## Enums - -```@docs -BarrierType -FailureType -``` - -## Functions - -```@docs -sunk_cost_bias_index -exnovation_score -recommendation -debiasing_actions -intelligent_failure_score -failure_summary -decision_pipeline -write_report_json -barrier_templates -run_stage_gates -portfolio_scores -allocate_budget -``` -``` - -**Verification:** -```julia -@assert isfile("/var$REPOS_DIR/Exnovation.jl/docs/src/api.md") "api.md must exist" -content = read("/var$REPOS_DIR/Exnovation.jl/docs/src/api.md", String) -@assert contains(content, "ExnovationItem") "Must document ExnovationItem" -@assert contains(content, "exnovation_score") "Must document exnovation_score" -@assert contains(content, "allocate_budget") "Must document allocate_budget" -println("PASS: api.md exists and documents key exports") -``` - ---- - -## TASK 4: Update `docs/src/index.md` Placeholder (MEDIUM) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/docs/src/index.md` (line 17) - -**Problem:** Line 17 says `# Examples coming soon` -- this is a placeholder. The repo -has two complete examples in `examples/` and a full Quick Start in `README.md`. - -**What to do:** -1. Replace `# Examples coming soon` with an actual Quick Start code example, adapted - from the `README.md` Quick Start section (lines 48-81). -2. Add a brief description of the package (1-2 sentences from `README.md` lines 8-10). -3. Mention the two example files: `examples/01_basic_usage.jl` and - `examples/02_portfolio_management.jl`. - -**Verification:** -```julia -content = read("/var$REPOS_DIR/Exnovation.jl/docs/src/index.md", String) -@assert !contains(content, "coming soon") "Must remove 'coming soon' placeholder" -@assert contains(content, "ExnovationItem") "Must include actual code example" -println("PASS: index.md updated with real content") -``` - ---- - -## TASK 5: Fix AGPL-3.0 License Headers (Must Be MPL-2.0) (HIGH) - -**Files:** -- `/var$REPOS_DIR/Exnovation.jl/ffi/zig/build.zig` (line 2) -- `/var$REPOS_DIR/Exnovation.jl/ffi/zig/src/main.zig` (line 6) -- `/var$REPOS_DIR/Exnovation.jl/ffi/zig/test/integration_test.zig` (line 2) -- `/var$REPOS_DIR/Exnovation.jl/examples/SafeDOMExample.res` (line 1) -- `/var$REPOS_DIR/Exnovation.jl/docs/CITATIONS.adoc` (line 13) - -**Problem:** Five files use `SPDX-License-Identifier: CC-BY-SA-4.0`. Per -CLAUDE.md license policy: "NEVER use AGPL-3.0 (old license, replaced by MPL-2.0)". -The `docs/CITATIONS.adoc` also says `license = {AGPL-3.0-or-later}` in the BibTeX block. - -**What to do:** -1. In each of the 5 files listed, replace `AGPL-3.0-or-later` with `MPL-2.0`. -2. In `docs/CITATIONS.adoc`, also fix the project name from `rsr-template-repo` to - `Exnovation.jl`, the author from `Polymath, Hyper` to `Jewell, Jonathan D.A.`, the - year to `2026`, and the URL to `https://github.com/hyperpolymath/Exnovation.jl`. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -count=$(grep -r "AGPL-3.0" --include="*.zig" --include="*.res" --include="*.adoc" . | wc -l) -if [ "$count" -eq 0 ]; then echo "PASS: no AGPL-3.0 references remain"; else echo "FAIL: $count AGPL-3.0 references found"; exit 1; fi -``` - ---- - -## TASK 6: Remove or Customize Boilerplate ABI/FFI Template Files (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Exnovation.jl/src/abi/Types.idr` -- `/var$REPOS_DIR/Exnovation.jl/src/abi/Layout.idr` -- `/var$REPOS_DIR/Exnovation.jl/src/abi/Foreign.idr` -- `/var$REPOS_DIR/Exnovation.jl/ffi/zig/build.zig` -- `/var$REPOS_DIR/Exnovation.jl/ffi/zig/src/main.zig` -- `/var$REPOS_DIR/Exnovation.jl/ffi/zig/test/integration_test.zig` -- `/var$REPOS_DIR/Exnovation.jl/ABI-FFI-README.md` - -**Problem:** Exnovation.jl is a pure-Julia package. It has no C FFI, no Zig build, and no -Idris2 ABI. All 7 files above contain raw `{{PROJECT}}` / `{{project}}` template -placeholders that have never been customized. They are non-functional boilerplate from -`rsr-template-repo` and will confuse users. - -**What to do:** -1. Delete all 7 files listed above. -2. Remove the empty directories `src/abi/`, `ffi/zig/src/`, `ffi/zig/test/`, `ffi/zig/`, - and `ffi/` if they become empty. -3. In `README.adoc`, remove or rewrite the ABI/FFI section (lines 5-34 and lines 36-101) - so it describes Exnovation.jl instead of RSR template boilerplate. Replace the entire - file content with a brief pointer: `= Exnovation.jl` followed by `See README.md for - full documentation.` - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -if [ -d "src/abi" ]; then echo "FAIL: src/abi/ still exists"; exit 1; fi -if [ -d "ffi" ]; then echo "FAIL: ffi/ still exists"; exit 1; fi -if [ -f "ABI-FFI-README.md" ]; then echo "FAIL: ABI-FFI-README.md still exists"; exit 1; fi -count=$(grep -r '{{PROJECT}}\|{{project}}' --include="*.idr" --include="*.zig" --include="*.md" . 2>/dev/null | wc -l) -if [ "$count" -eq 0 ]; then echo "PASS: no template placeholders remain in code"; else echo "FAIL: $count template placeholders found"; exit 1; fi -``` - ---- - -## TASK 7: Customize RSR Template Placeholders in Markdown Files (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/Exnovation.jl/CONTRIBUTING.md` -- `/var$REPOS_DIR/Exnovation.jl/CODE_OF_CONDUCT.md` -- `/var$REPOS_DIR/Exnovation.jl/SECURITY.md` -- `/var$REPOS_DIR/Exnovation.jl/ROADMAP.adoc` -- `/var$REPOS_DIR/Exnovation.jl/RSR_OUTLINE.adoc` - -**Problem:** These files are raw RSR template copies with `{{FORGE}}`, `{{OWNER}}`, -`{{REPO}}`, `{{PROJECT_NAME}}`, `{{SECURITY_EMAIL}}`, `{{CONDUCT_EMAIL}}`, -`{{CONDUCT_TEAM}}`, `{{RESPONSE_TIME}}`, `{{CURRENT_YEAR}}`, `{{PGP_FINGERPRINT}}`, -`{{PGP_KEY_URL}}`, `{{WEBSITE}}`, `{{MAIN_BRANCH}}` placeholders. - -`ROADMAP.adoc` is also a generic template that conflicts with the real `ROADMAP.md`. - -**What to do:** -1. In `CONTRIBUTING.md`, replace: - - `{{FORGE}}` with `github.com` - - `{{OWNER}}` with `hyperpolymath` - - `{{REPO}}` with `Exnovation.jl` - - `{{MAIN_BRANCH}}` with `main` -2. In `CODE_OF_CONDUCT.md`, replace: - - `{{PROJECT_NAME}}` with `Exnovation.jl` - - `{{OWNER}}` with `hyperpolymath` - - `{{REPO}}` with `Exnovation.jl` - - `{{CONDUCT_EMAIL}}` with `jonathan.jewell@open.ac.uk` - - `{{CONDUCT_TEAM}}` with `Exnovation.jl Maintainers` - - `{{RESPONSE_TIME}}` with `72 hours` - - `{{CURRENT_YEAR}}` with `2026` - - `{{FORGE}}` with `github.com` -3. In `SECURITY.md`, replace: - - `{{PROJECT_NAME}}` with `Exnovation.jl` - - `{{OWNER}}` with `hyperpolymath` - - `{{REPO}}` with `Exnovation.jl` - - `{{SECURITY_EMAIL}}` with `jonathan.jewell@open.ac.uk` - - `{{PGP_FINGERPRINT}}` with `(not yet configured)` - - `{{PGP_KEY_URL}}` with `(not yet configured)` - - `{{WEBSITE}}` with `https://github.com/hyperpolymath/Exnovation.jl` - - `{{CURRENT_YEAR}}` with `2026` -4. Delete `ROADMAP.adoc` (the real roadmap is `ROADMAP.md`). -5. In `RSR_OUTLINE.adoc`, replace the title on line 1 from `= RSR Template Repository` - to `= Exnovation.jl RSR Outline`. Replace the SPDX identifier on line 212 from - `MPL-2.0-or-later` (typo with doubled suffix) to `MPL-2.0`. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -count=$(grep -r '{{[A-Z_]*}}' CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md RSR_OUTLINE.adoc 2>/dev/null | wc -l) -if [ "$count" -eq 0 ]; then echo "PASS: no template placeholders in docs"; else echo "FAIL: $count placeholders remain"; exit 1; fi -if [ -f "ROADMAP.adoc" ]; then echo "FAIL: ROADMAP.adoc should be deleted"; exit 1; fi -echo "PASS: all template docs customized" -``` - ---- - -## TASK 8: Create `.machine_readable/` Directory with SCM Files (MEDIUM) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/.machine_readable/` (MISSING) - -**Problem:** Per CLAUDE.md and the project's own `AI.djot`, every hyperpolymath repo must -have `.machine_readable/STATE.scm`, `.machine_readable/ECOSYSTEM.scm`, and -`.machine_readable/META.scm`. This directory does not exist. - -**What to do:** -1. Create directory `/var$REPOS_DIR/Exnovation.jl/.machine_readable/`. -2. Create `STATE.scm` with: - - `(metadata (project . "Exnovation.jl") (updated . "2026-02-12"))` - - `(position (phase . maintenance) (maturity . production))` - - `(completion-percentage . 85)` - - `(blockers . ())` - - Current status note: core library complete, docs and template cleanup remaining. -3. Create `ECOSYSTEM.scm` with: - - Name: `Exnovation.jl` - - Type: `julia-package` - - Purpose: `Exnovation decision framework for phase-out analysis` - - Related projects: `(related-projects ((name . "BowtieRisk.jl") (relationship . "potential-consumer")))` -4. Create `META.scm` with: - - License: `MPL-2.0` - - Author: `Jonathan D.A. Jewell` - - Architecture decision: single-module Julia package, no FFI needed. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -for f in STATE.scm ECOSYSTEM.scm META.scm; do - if [ ! -f ".machine_readable/$f" ]; then echo "FAIL: .machine_readable/$f missing"; exit 1; fi -done -echo "PASS: .machine_readable/ directory with all SCM files" -``` - ---- - -## TASK 9: Remove Unrelated Example Files (LOW) - -**Files:** -- `/var$REPOS_DIR/Exnovation.jl/examples/SafeDOMExample.res` -- `/var$REPOS_DIR/Exnovation.jl/examples/web-project-deno.json` - -**Problem:** These are RSR template examples for ReScript web projects. They have nothing -to do with Exnovation.jl (a Julia decision-framework package). `SafeDOMExample.res` is -a ReScript file demonstrating DOM mounting. `web-project-deno.json` is a Deno configuration -for ReScript projects. Both are confusing detritus. - -**What to do:** -1. Delete `examples/SafeDOMExample.res`. -2. Delete `examples/web-project-deno.json`. -3. Verify that `examples/01_basic_usage.jl` and `examples/02_portfolio_management.jl` - remain untouched. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -if [ -f "examples/SafeDOMExample.res" ]; then echo "FAIL: SafeDOMExample.res should be deleted"; exit 1; fi -if [ -f "examples/web-project-deno.json" ]; then echo "FAIL: web-project-deno.json should be deleted"; exit 1; fi -if [ ! -f "examples/01_basic_usage.jl" ]; then echo "FAIL: 01_basic_usage.jl must exist"; exit 1; fi -if [ ! -f "examples/02_portfolio_management.jl" ]; then echo "FAIL: 02_portfolio_management.jl must exist"; exit 1; fi -echo "PASS: only Julia examples remain" -``` - ---- - -## TASK 10: Customize `docs/CITATIONS.adoc` (LOW) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/docs/CITATIONS.adoc` - -**Problem:** This file is a raw RSR template copy. It references `rsr-template-repo`, -uses author `Polymath, Hyper`, year `2025`, and the wrong URL. It also references -non-existent `CITATION.cff` and `codemeta.json` files. - -**What to do:** -1. Replace all instances of `rsr-template-repo` / `RSR-template-repo` with `Exnovation.jl`. -2. Replace author `Polymath, Hyper` with `Jewell, Jonathan D.A.` (BibTeX last-first) and - `Hyper Polymath` with `Jonathan D.A. Jewell`. -3. Replace year `2025` with `2026`. -4. Replace the URL with `https://github.com/hyperpolymath/Exnovation.jl`. -5. Fix the license from `AGPL-3.0-or-later` to `MPL-2.0` (if not done in Task 5). -6. Remove the "See Also" section referencing `CITATION.cff` and `codemeta.json` (they - do not exist), or create those files. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -content=$(cat docs/CITATIONS.adoc) -if echo "$content" | grep -q "rsr-template-repo"; then echo "FAIL: still references rsr-template-repo"; exit 1; fi -if echo "$content" | grep -q "AGPL"; then echo "FAIL: still references AGPL"; exit 1; fi -if echo "$content" | grep -q "Polymath, Hyper"; then echo "FAIL: wrong author name"; exit 1; fi -echo "PASS: CITATIONS.adoc customized" -``` - ---- - -## TASK 11: Pin Unpinned GitHub Actions in release.yml (LOW) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/.github/workflows/release.yml` (lines 46, 94, 108) - -**Problem:** Three action references use tag-only pins (`@v4`) instead of SHA pins: -- Line 46: `actions/upload-artifact@v4` -- Line 94: `actions/upload-artifact@v4` -- Line 108: `actions/download-artifact@v4` - -Per CLAUDE.md workflow standards, all actions must be SHA-pinned. - -**What to do:** -1. Replace `actions/upload-artifact@v4` on lines 46 and 94 with a SHA-pinned version. - Use a current v4 SHA (e.g., `actions/upload-artifact@ea165f8d65b6db9a8b22b984b926f09f6cef9ab8` - or look up the latest v4 tag SHA on the actions/upload-artifact repo). -2. Replace `actions/download-artifact@v4` on line 108 with a SHA-pinned version - (e.g., `actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093` - or look up the latest v4 tag SHA). - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -count=$(grep -E 'uses:.*@v[0-9]+\s*$' .github/workflows/release.yml | wc -l) -if [ "$count" -eq 0 ]; then echo "PASS: all actions SHA-pinned"; else echo "FAIL: $count actions not SHA-pinned"; exit 1; fi -``` - ---- - -## TASK 12: Fix `AI.a2ml` Template References (LOW) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/AI.a2ml` - -**Problem:** This file references `rsr-template-repo` (line 5) and paths like -`.machines_readable/6scm/STATE.scm` (line 9) and `.machines_readable/6scm/AGENTIC.scm` -(line 10). The correct path per CLAUDE.md is `.machine_readable/` (no `s`, no `6scm/` -subdirectory). The file also does not mention Exnovation.jl at all. - -**What to do:** -1. Replace `rsr-template-repo` with `Exnovation.jl` on line 5. -2. Replace `.machines_readable/6scm/` with `.machine_readable/` throughout (lines 9-10). -3. Update the description to mention exnovation decision-making. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -content=$(cat AI.a2ml) -if echo "$content" | grep -q "rsr-template-repo"; then echo "FAIL: still says rsr-template-repo"; exit 1; fi -if echo "$content" | grep -q "machines_readable"; then echo "FAIL: wrong directory name (has extra s)"; exit 1; fi -if echo "$content" | grep -q "6scm"; then echo "FAIL: references 6scm subdirectory"; exit 1; fi -echo "PASS: AI.a2ml references corrected" -``` - ---- - -## TASK 13: Add Input Validation to Public API Functions (LOW) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/src/Exnovation.jl` - -**Problem:** The `DecisionCriteria` struct (lines 52-57) expects weights in 0..1 but -no validation is performed. Negative weights or weights > 1 are silently accepted. -Similarly, `Driver` and `Barrier` weights have no validation. The `_clamp01` function -clamps individual weights during scoring, but the raw structs allow nonsensical values -like `-5.0` or `100.0` to be constructed without any warning. - -**What to do:** -1. Add a constructor function `DecisionCriteria(sw, sfw, pw, rw)` that warns (via - `@warn`) if any weight is outside [0, 1]. Do NOT throw -- just warn. The clamping - in scoring already handles the math, but users should know their inputs are unusual. -2. Alternatively, add a `validate(criteria::DecisionCriteria)` exported function that - returns a vector of warning strings. This is less intrusive. -3. Add a test that constructs `DecisionCriteria` with out-of-range weights and verifies - that `validate()` returns warnings, or that scoring still works correctly. - -**Verification:** -```julia -using Exnovation -# Extreme values should not crash -bad_criteria = DecisionCriteria(-1.0, 2.0, 0.5, 0.5) -item = ExnovationItem(:test, "test", "test") -drivers = [Driver(:d, 0.5, "test")] -barriers = Barrier[] -a = ExnovationAssessment(item, drivers, barriers, bad_criteria, 100.0, 50.0, 0.0, 0.5, 0.5, 0.5) -s = exnovation_score(a) -@assert isfinite(s.total_score) "Score must be finite even with bad inputs" -println("PASS: out-of-range weights handled gracefully") -``` - ---- - -## TASK 14: Add `permissions: read-all` to CI Workflow (LOW) - -**Files:** `/var$REPOS_DIR/Exnovation.jl/.github/workflows/ci.yml` - -**Problem:** Per CLAUDE.md workflow validation checklist item 4: "`permissions: read-all` -at workflow level". The CI workflow has no `permissions` block at all. - -**What to do:** -1. Add `permissions: read-all` after the `on:` block (after line 6) and before `jobs:`. - -**Verification:** -```bash -cd /var$REPOS_DIR/Exnovation.jl -if grep -q "permissions:" .github/workflows/ci.yml; then echo "PASS: permissions block exists"; else echo "FAIL: no permissions block"; exit 1; fi -``` - ---- - -## FINAL VERIFICATION - -After all tasks are complete, run: - -```bash -cd /var$REPOS_DIR/Exnovation.jl - -echo "=== 1. Julia tests ===" -julia --project=. -e 'using Pkg; Pkg.test()' - -echo "=== 2. No AGPL references ===" -count=$(grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.idr" --include="*.res" --include="*.adoc" . 2>/dev/null | wc -l) -[ "$count" -eq 0 ] && echo "PASS" || echo "FAIL: $count AGPL references" - -echo "=== 3. No raw template placeholders in code ===" -count=$(grep -rn '{{[A-Za-z_]*}}' --include="*.jl" --include="*.zig" --include="*.idr" --include="*.yml" . 2>/dev/null | wc -l) -[ "$count" -eq 0 ] && echo "PASS" || echo "FAIL: $count placeholders" - -echo "=== 4. Machine-readable directory exists ===" -[ -f ".machine_readable/STATE.scm" ] && [ -f ".machine_readable/META.scm" ] && [ -f ".machine_readable/ECOSYSTEM.scm" ] && echo "PASS" || echo "FAIL" - -echo "=== 5. No stale ABI/FFI boilerplate ===" -[ ! -d "src/abi" ] && [ ! -d "ffi" ] && [ ! -f "ABI-FFI-README.md" ] && echo "PASS" || echo "FAIL" - -echo "=== 6. api.md exists ===" -[ -f "docs/src/api.md" ] && echo "PASS" || echo "FAIL" - -echo "=== 7. Version consistency ===" -julia --project=. -e ' - using Pkg - p = Pkg.TOML.parsefile("Project.toml") - m = Pkg.TOML.parsefile("Manifest.toml") - pv = p["version"] - mv = m["deps"]["Exnovation"][1]["version"] - @assert pv == mv "Version mismatch: Project=$pv Manifest=$mv" - println("PASS: versions match ($pv)") -' - -echo "=== 8. Political debiasing actions ===" -julia --project=. -e ' - using Exnovation - actions = debiasing_actions([Barrier(Political, 0.5, "test")]) - @assert length(actions) >= 1 "Political barriers must produce actions" - println("PASS: $(length(actions)) actions for Political barriers") -' - -echo "=== AUDIT COMPLETE ===" -``` diff --git a/packages/Exnovation.jl/TOPOLOGY.md b/packages/Exnovation.jl/TOPOLOGY.adoc similarity index 89% rename from packages/Exnovation.jl/TOPOLOGY.md rename to packages/Exnovation.jl/TOPOLOGY.adoc index 044884a78..992d73c60 100644 --- a/packages/Exnovation.jl/TOPOLOGY.md +++ b/packages/Exnovation.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Exnovation.jl — Project Topology -# Exnovation.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE MODELS @@ -68,26 +64,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Production Phase (Complete) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Exnovation Item ──────► Assessment Engine ──────► Decision Pipeline │ Intelligent Failure ─────────────────────────────────┘ │ Debiasing Actions ◀───── Portfolio Scoring ◀─────────┘ -``` +.... -## 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/packages/Exnovation.jl/docs/src/api.md b/packages/Exnovation.jl/docs/src/api.adoc similarity index 56% rename from packages/Exnovation.jl/docs/src/api.md rename to packages/Exnovation.jl/docs/src/api.adoc index e61b74c12..b98f0287e 100644 --- a/packages/Exnovation.jl/docs/src/api.md +++ b/packages/Exnovation.jl/docs/src/api.adoc @@ -1,12 +1,11 @@ - - -# API Reference +== API Reference This page documents all exported types and functions in Exnovation.jl. -## Types +=== Types -```@docs +[source,@docs] +---- ExnovationItem Driver Barrier @@ -20,11 +19,12 @@ FailureSummary ImpactModel PortfolioItem StageGate -``` +---- -## Functions +=== Functions -```@docs +[source,@docs] +---- assess_exnovation normalize_score recommendation @@ -36,15 +36,17 @@ portfolio_scores allocate_budget run_stage_gates lifecycle_fit -``` +---- -## Enums +=== Enums -- `BarrierType`: `Cognitive`, `Emotional`, `Behavioral`, `Structural`, `Political` -- `LegacyType`: `Sustaining`, `Disruptive` -- `FailureType`: `Intelligent`, `Preventable`, `Complex` +* `+BarrierType+`: `+Cognitive+`, `+Emotional+`, `+Behavioral+`, +`+Structural+`, `+Political+` +* `+LegacyType+`: `+Sustaining+`, `+Disruptive+` +* `+FailureType+`: `+Intelligent+`, `+Preventable+`, `+Complex+` -## Index +=== Index -```@index -``` +[source,@index] +---- +---- diff --git a/packages/Exnovation.jl/docs/src/index.md b/packages/Exnovation.jl/docs/src/index.adoc similarity index 62% rename from packages/Exnovation.jl/docs/src/index.md rename to packages/Exnovation.jl/docs/src/index.adoc index cd08d2bb4..c42e71a1f 100644 --- a/packages/Exnovation.jl/docs/src/index.md +++ b/packages/Exnovation.jl/docs/src/index.adoc @@ -1,19 +1,22 @@ -# Exnovation.jl +== Exnovation.jl -**Exnovation.jl** is a decision-support library for exnovation: the strategic retirement -of legacy systems. It helps organizations assess whether to exnovate (retire), pilot, or -keep existing infrastructure using quantitative drivers, barriers, and impact models. +*Exnovation.jl* is a decision-support library for exnovation: the +strategic retirement of legacy systems. It helps organizations assess +whether to exnovate (retire), pilot, or keep existing infrastructure +using quantitative drivers, barriers, and impact models. -## Installation +=== Installation -```julia +[source,julia] +---- using Pkg Pkg.add(url="https://github.com/hyperpolymath/Exnovation.jl") -``` +---- -## Quick Start +=== Quick Start -```julia +[source,julia] +---- using Exnovation item = ExnovationItem(:LegacyCRM, "Legacy CRM system", "Sales operations") @@ -46,15 +49,16 @@ assessment = ExnovationAssessment( score = exnovation_score(assessment) println(score) println(recommendation(assessment)) -``` +---- -## Examples +=== Examples The repository includes two complete examples: -- **`examples/01_basic_usage.jl`**: Basic exnovation assessment workflow -- **`examples/02_portfolio_management.jl`**: Portfolio prioritization and budgeting +* *`+examples/01_basic_usage.jl+`*: Basic exnovation assessment workflow +* *`+examples/02_portfolio_management.jl+`*: Portfolio prioritization +and budgeting -## API Reference +=== API Reference -See [API](api.md) for complete reference documentation. +See link:api.md[API] for complete reference documentation. diff --git a/packages/HackenbushGames.jl/CODE_OF_CONDUCT.adoc b/packages/HackenbushGames.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..bc39f2e5c --- /dev/null +++ b/packages/HackenbushGames.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,340 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +HackenbushGames.jl a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |jonathan.jewell@open.ac.uk |Detailed reports, sensitive +matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The Project Maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a Project Maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The Project Maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* jonathan.jewell@open.ac.uk with subject line "`Appeal: +[Original Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different Project Maintainers member than +the original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/HackenbushGames.jl/discussions[Discussion] +(for general questions) +* Email jonathan.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/HackenbushGames.jl/CODE_OF_CONDUCT.md b/packages/HackenbushGames.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 9663a64f1..000000000 --- a/packages/HackenbushGames.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,308 +0,0 @@ -# Code of Conduct - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in HackenbushGames.jl a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | jonathan.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The Project Maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a Project Maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The Project Maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** jonathan.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different Project Maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/HackenbushGames.jl/discussions) (for general questions) -- Email jonathan.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/HackenbushGames.jl/CONTRIBUTING.adoc b/packages/HackenbushGames.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..2d1787315 --- /dev/null +++ b/packages/HackenbushGames.jl/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/HackenbushGames.jl.git cd +HackenbushGames.jl + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create HackenbushGames.jl-dev toolbox enter +HackenbushGames.jl-dev # Install dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +HackenbushGames.jl/ ├── 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/HackenbushGames.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/HackenbushGames.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/HackenbushGames.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/HackenbushGames.jl/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/packages/HackenbushGames.jl/CONTRIBUTING.md b/packages/HackenbushGames.jl/CONTRIBUTING.md deleted file mode 100644 index f6663c63a..000000000 --- a/packages/HackenbushGames.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/HackenbushGames.jl.git -cd HackenbushGames.jl - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create HackenbushGames.jl-dev -toolbox enter HackenbushGames.jl-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -HackenbushGames.jl/ -├── 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/HackenbushGames.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/HackenbushGames.jl/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/HackenbushGames.jl/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/HackenbushGames.jl/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/packages/HackenbushGames.jl/README.adoc b/packages/HackenbushGames.jl/README.adoc new file mode 100644 index 000000000..41ff8bd98 --- /dev/null +++ b/packages/HackenbushGames.jl/README.adoc @@ -0,0 +1,110 @@ +== HackenbushGames.jl + +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-100%25-green[Completion +Status]] +link:LICENSE[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License]] + +HackenbushGames.jl is a Julia toolkit for experimenting with Hackenbush +positions and the combinatorial game theory ideas from Padraic +Bartlett’s "`A Short Guide to Hackenbush`" (VIGRE REU 2006). It provides +a small API for building graphs, cutting edges, evaluating basic +positions, and exporting visualizations. + +This project emphasizes transparent rules over heavy automation. It +includes simple evaluators for stalks and small green graphs plus +utilities for nimbers and dyadic rationals. + +=== Installation + +==== From Julia REPL + +[source,julia] +---- +using Pkg +Pkg.add("HackenbushGames") +---- + +==== From Git (Development) + +[source,julia] +---- +using Pkg +Pkg.add(url="https://github.com/hyperpolymath/HackenbushGames.jl") +---- + +=== Features + +* Build Red/Blue/Green Hackenbush graphs and generate legal moves. +* Compute dyadic values for *Red-Blue stalks* (linear chains). +* Compute nimbers for *Green stalks* and *small Green graphs*. +* Helpers for nim-sum and minimal excluded value (mex). +* Graph sum composition and GraphViz export. +* Canonical \{L|R} notation and numeric evaluation for small games. +* ASCII visualization helper. + +=== Quick Start + +[source,julia] +---- +using HackenbushGames + +# Red-Blue stalk value (ground -> top) +colors = [Blue, Red, Blue] +value = stalk_value(colors) +println(value) # dyadic rational + +# Green impartial position via graph + Grundy number +edges = [ + Edge(0, 1, Green), + Edge(1, 2, Green), + Edge(1, 3, Green), +] +position = HackenbushGraph(edges, [0]) +println(green_grundy(position)) +---- + +[source,julia] +---- +g = simple_stalk([Blue, Red, Blue]) +println(game_value(g)) # dyadic value if numeric +println(to_ascii(g)) +---- + +=== Model Notes (Based on the Bartlett Guide) + +* *Red-Blue Hackenbush* uses \{L | R} game values and the Simplicity +Rule to identify dyadic rationals for stalks. +* *Green Hackenbush* is impartial and can be evaluated via nimbers. This +package uses a Grundy-number search for small graphs. +* *Graph sums* are supported for building disjoint unions. +* *Colon and Fusion* rules and the "`flower/jungle`" ideas are described +in the guide; in this package they are documented as concepts and can be +layered into higher-level analysis later. + +=== Limitations + +The `+green_grundy+` evaluator is exponential in the number of edges and +is intended for small positions and teaching. Larger graphs should use +specialized algorithms or structural simplifications. + +=== Development + +[source,bash] +---- +julia --project=. -e 'using Pkg; Pkg.instantiate()' +julia --project=. -e 'using Pkg; Pkg.test()' +---- + +=== API Snapshot + +[source,julia] +---- +EdgeColor, Edge, HackenbushGraph +prune_disconnected, cut_edge, moves, game_sum +simple_stalk, to_ascii, to_graphviz +GameForm, canonical_game, simplify_game, game_value +stalk_value, simplest_dyadic_between +mex, nim_sum, green_stalk_nimber, green_grundy +---- diff --git a/packages/HackenbushGames.jl/README.md b/packages/HackenbushGames.jl/README.md deleted file mode 100644 index 3b4dd67d3..000000000 --- a/packages/HackenbushGames.jl/README.md +++ /dev/null @@ -1,103 +0,0 @@ -# HackenbushGames.jl - -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-100%25-green)](TOPOLOGY.md) -[![License](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](LICENSE) - - - - -HackenbushGames.jl is a Julia toolkit for experimenting with Hackenbush -positions and the combinatorial game theory ideas from Padraic Bartlett’s -“A Short Guide to Hackenbush” (VIGRE REU 2006). It provides a small API for -building graphs, cutting edges, evaluating basic positions, and exporting -visualizations. - -This project emphasizes transparent rules over heavy automation. It includes -simple evaluators for stalks and small green graphs plus utilities for nimbers -and dyadic rationals. - -## Installation - -### From Julia REPL -```julia -using Pkg -Pkg.add("HackenbushGames") -``` - -### From Git (Development) -```julia -using Pkg -Pkg.add(url="https://github.com/hyperpolymath/HackenbushGames.jl") -``` - -## Features - -- Build Red/Blue/Green Hackenbush graphs and generate legal moves. -- Compute dyadic values for **Red-Blue stalks** (linear chains). -- Compute nimbers for **Green stalks** and **small Green graphs**. -- Helpers for nim-sum and minimal excluded value (mex). -- Graph sum composition and GraphViz export. -- Canonical {L|R} notation and numeric evaluation for small games. -- ASCII visualization helper. - -## Quick Start - -```julia -using HackenbushGames - -# Red-Blue stalk value (ground -> top) -colors = [Blue, Red, Blue] -value = stalk_value(colors) -println(value) # dyadic rational - -# Green impartial position via graph + Grundy number -edges = [ - Edge(0, 1, Green), - Edge(1, 2, Green), - Edge(1, 3, Green), -] -position = HackenbushGraph(edges, [0]) -println(green_grundy(position)) -``` - -```julia -g = simple_stalk([Blue, Red, Blue]) -println(game_value(g)) # dyadic value if numeric -println(to_ascii(g)) -``` - -## Model Notes (Based on the Bartlett Guide) - -- **Red-Blue Hackenbush** uses {L | R} game values and the Simplicity Rule - to identify dyadic rationals for stalks. -- **Green Hackenbush** is impartial and can be evaluated via nimbers. - This package uses a Grundy-number search for small graphs. -- **Graph sums** are supported for building disjoint unions. -- **Colon and Fusion** rules and the “flower/jungle” ideas are described in - the guide; in this package they are documented as concepts and can be - layered into higher-level analysis later. - -## Limitations - -The `green_grundy` evaluator is exponential in the number of edges and is -intended for small positions and teaching. Larger graphs should use specialized -algorithms or structural simplifications. - -## Development - -```bash -julia --project=. -e 'using Pkg; Pkg.instantiate()' -julia --project=. -e 'using Pkg; Pkg.test()' -``` - -## API Snapshot - -```julia -EdgeColor, Edge, HackenbushGraph -prune_disconnected, cut_edge, moves, game_sum -simple_stalk, to_ascii, to_graphviz -GameForm, canonical_game, simplify_game, game_value -stalk_value, simplest_dyadic_between -mex, nim_sum, green_stalk_nimber, green_grundy -``` diff --git a/packages/HackenbushGames.jl/ROADMAP.adoc b/packages/HackenbushGames.jl/ROADMAP.adoc index 6cf5a10dd..19dd56ed3 100644 --- a/packages/HackenbushGames.jl/ROADMAP.adoc +++ b/packages/HackenbushGames.jl/ROADMAP.adoc @@ -1,18 +1,156 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Roadmap -:revdate: 2026-02-17 - -== Release Baseline (Must) -- Package installs from a clean Julia environment (`Pkg.add`). -- Precompile, build, test, and module load smoke are gated in CI. -- Versioning stays semver and aligned with release refs/tags. - -== V2 Backlog (Should) -- Expand CI matrix (OS + Julia versions + optional dependency modes). -- Add performance baselines and regression checks. -- Improve machine-readable evidence and release artifact metadata. - -== V2 Backlog (Could) -- Add deeper formal verification evidence exports. -- Add optional accelerator/hardware strategy tracks where relevant. -- Add richer diagnostics and fault-recovery instrumentation. +== HackenbushGames.jl Development Roadmap + +=== Current State (v1.0) + +Functional beta Hackenbush game implementation: - Red, Blue, Green +(neutral) edges - Conway’s surreal number evaluation - Canonical form +computation - Basic game operations (addition via game_sum) - +Simplification algorithms + +*Status:* Core algorithms implemented. Test coverage is basic (35 test +cases). + +''''' + +=== v1.0 → v1.2 Roadmap (Near-term) + +==== v1.1 - Game Analysis & Visualization (3-6 months) + +*MUST:* - [ ] *Interactive game viewer* - Makie.jl/GraphMakie.jl +visualization of game positions - [ ] *Move recommendation engine* - +Suggest optimal moves based on game value - [ ] *Game position database* +- Library of solved positions with canonical forms - [ ] *Proof +verification* - Validate game value calculations with step-by-step +proofs + +*SHOULD:* - [ ] *AI opponent* - Minimax/alpha-beta pruning for computer +play - [ ] *Opening book* - Pre-computed optimal strategies for common +starting positions - [ ] *Thermography* - Temperature analysis for +combinatorial game theory research - [ ] *LaTeX export* - Generate +publication-quality game diagrams and surreal number expressions + +*COULD:* - [ ] *Web-based game player* - Franklin.jl/Genie.jl +interactive Hackenbush app - [ ] *Mobile app* - Touch-friendly +Hackenbush game (via Julia + web frontend) - [ ] *Tutorial mode* - +Guided lessons on surreal numbers and game theory + +==== v1.2 - Advanced Game Theory & Extensions (6-12 months) + +*MUST:* - [ ] *Loopy Hackenbush* - Support for games with cycles +(infinite game analysis) - [ ] *Mis�re Hackenbush* - Last-to-move-loses +variant - [ ] *Team Hackenbush* - Multi-player cooperative/competitive +variants - [ ] *Integration with Graphs.jl* - Advanced graph algorithms +for position analysis + +*SHOULD:* - [ ] *Game fuzzing* - Generate random positions for testing +edge cases - [ ] *Symmetry detection* - Identify isomorphic game +positions for performance - [ ] *Decomposition algorithms* - Break +complex games into independent subgames - [ ] *Integration with +Axiom.jl* - Formal verification of surreal number arithmetic + +*COULD:* - [ ] *3D Hackenbush* - Extend to spatial graphs (nodes in 3D, +edges as rods) - [ ] *Quantum Hackenbush* - Superposition of game states +(research exploration) - [ ] *Hackenbush variants* - Domineering, Nim, +Chomp (expand to other combinatorial games) + +''''' + +=== v1.3+ Roadmap (Speculative) + +==== Research Frontiers + +*Advanced Combinatorial Game Theory:* - Infinitesimal game analysis +(tiny, miny, infinitesimals) - Transfinite Hackenbush (ordinal-valued +positions) - Non-deterministic Hackenbush (dice, cards, hidden +information) - Partizan game complexity (computational hardness proofs) + +*AI & Machine Learning:* - Deep reinforcement learning (AlphaGo-style +neural networks for Hackenbush) - Symbolic regression (discover new game +theory theorems from data) - Generative models (create interesting +Hackenbush positions for puzzles) - Neural surreal number arithmetic +(learn surreal operations end-to-end) + +*Formal Verification:* - Coq/Lean formalization of Conway’s construction +- Certified game solver (verified correctness of value computation) - +Proof-producing game analysis (generate human-readable proofs of +optimality) + +*Educational Technology:* - Interactive textbook (Pluto.jl + Hackenbush +animations) - Gamified learning platform (earn surreal number badges) - +Research collaboration tool (shared game database for CGT community) + +==== Ecosystem Integration + +* *Symbolics.jl:* Symbolic manipulation of surreal number expressions +* *JuMP.jl:* Optimization-based game solving (LP formulation of +Hackenbush) +* *Graphs.jl:* Leverage advanced graph algorithms (matchings, flows, +cuts) +* *DataFrames.jl:* Tabulate game databases with rich metadata + +==== Ambitious Features + +* *Combinatorial game theory foundation model* - Pre-trained on all +known solved games +* *Automated theorem discovery* - AI that proposes and proves new CGT +conjectures +* *Virtual CGT conference* - Online platform for sharing positions, +proofs, and puzzles +* *Hackenbush Olympics* - Annual tournament with cash prizes for best +players/solvers + +''''' + +=== Future Horizons (v2.0+) + +==== Surreal Economic & Financial Models + +* [ ] *Game-Theoretic Asset Pricing*: Apply surreal number theory to +model complex financial derivatives where payoffs are better represented +as game positions than real numbers. +* [ ] *Incentive Alignment Verification*: Use Hackenbush game values to +formally verify that a mechanism design (e.g., a multi-agent auction) is +"`Winning`" for all participants. + +==== Biological & Metabolic Hackenbush + +* [ ] *Metabolic Game Theory*: Model metabolic pathways as Hackenbush +graphs where enzyme reactions are "`cuts`" and steady-state fluxes are +"`Winning Strategies`" for cellular survival. +* [ ] *Gene Regulatory Games*: Represent gene activation/inhibition as a +partizan game to understand the robustness of biological switch +networks. + +==== Combinatorial Logic & Computing + +* [ ] *Surreal Logic Gates*: Implement standard computing primitives +(AND, OR, NOT) where the operands are Hackenbush game positions, +enabling a new form of "`Game-Based Computation`". +* [ ] *Surreal Algebra System*: Full symbolic system for manipulating +surreal numbers, including multiplication and division (which are +notoriously difficult to implement for games). + +==== AI Reasoning Benchmarks + +* [ ] *Hackenbush AI Arena*: A specialized benchmark for testing the +logical and mathematical reasoning of Large Language Models (LLMs) +through interactive Hackenbush play. +* [ ] *Neuro-Symbolic Surrealism*: Train neural networks to "`Intuiter`" +the game value of complex Hackenbush positions without exhaustive +search. + +''''' + +=== Migration Path + +*v1.0 → v1.1:* Backward compatible (visualization and AI features are +additive) *v1.1 → v1.2:* Mostly compatible (loopy games may require new +data structures) *v1.2 → v1.3+:* Breaking changes likely +(transfinite/quantum variants need fundamental redesign) + +=== Community Goals + +* *Adoption by CGT researchers* (Siegel, Albert, Nowakowski) by v1.2 +* *Publication in Integers or similar* (CGT journal) by v1.2 +* *Workshop at Combinatorial Game Theory Colloquium* by v1.2 +* *1000 solved positions* in public database by v1.2 diff --git a/packages/HackenbushGames.jl/ROADMAP.md b/packages/HackenbushGames.jl/ROADMAP.md deleted file mode 100644 index e30f24247..000000000 --- a/packages/HackenbushGames.jl/ROADMAP.md +++ /dev/null @@ -1,131 +0,0 @@ -# HackenbushGames.jl Development Roadmap - -## Current State (v1.0) - -Functional beta Hackenbush game implementation: -- Red, Blue, Green (neutral) edges -- Conway's surreal number evaluation -- Canonical form computation -- Basic game operations (addition via game_sum) -- Simplification algorithms - -**Status:** Core algorithms implemented. Test coverage is basic (35 test cases). - ---- - -## v1.0 → v1.2 Roadmap (Near-term) - -### v1.1 - Game Analysis & Visualization (3-6 months) - -**MUST:** -- [ ] **Interactive game viewer** - Makie.jl/GraphMakie.jl visualization of game positions -- [ ] **Move recommendation engine** - Suggest optimal moves based on game value -- [ ] **Game position database** - Library of solved positions with canonical forms -- [ ] **Proof verification** - Validate game value calculations with step-by-step proofs - -**SHOULD:** -- [ ] **AI opponent** - Minimax/alpha-beta pruning for computer play -- [ ] **Opening book** - Pre-computed optimal strategies for common starting positions -- [ ] **Thermography** - Temperature analysis for combinatorial game theory research -- [ ] **LaTeX export** - Generate publication-quality game diagrams and surreal number expressions - -**COULD:** -- [ ] **Web-based game player** - Franklin.jl/Genie.jl interactive Hackenbush app -- [ ] **Mobile app** - Touch-friendly Hackenbush game (via Julia + web frontend) -- [ ] **Tutorial mode** - Guided lessons on surreal numbers and game theory - -### v1.2 - Advanced Game Theory & Extensions (6-12 months) - -**MUST:** -- [ ] **Loopy Hackenbush** - Support for games with cycles (infinite game analysis) -- [ ] **Mis�re Hackenbush** - Last-to-move-loses variant -- [ ] **Team Hackenbush** - Multi-player cooperative/competitive variants -- [ ] **Integration with Graphs.jl** - Advanced graph algorithms for position analysis - -**SHOULD:** -- [ ] **Game fuzzing** - Generate random positions for testing edge cases -- [ ] **Symmetry detection** - Identify isomorphic game positions for performance -- [ ] **Decomposition algorithms** - Break complex games into independent subgames -- [ ] **Integration with Axiom.jl** - Formal verification of surreal number arithmetic - -**COULD:** -- [ ] **3D Hackenbush** - Extend to spatial graphs (nodes in 3D, edges as rods) -- [ ] **Quantum Hackenbush** - Superposition of game states (research exploration) -- [ ] **Hackenbush variants** - Domineering, Nim, Chomp (expand to other combinatorial games) - ---- - -## v1.3+ Roadmap (Speculative) - -### Research Frontiers - -**Advanced Combinatorial Game Theory:** -- Infinitesimal game analysis (tiny, miny, infinitesimals) -- Transfinite Hackenbush (ordinal-valued positions) -- Non-deterministic Hackenbush (dice, cards, hidden information) -- Partizan game complexity (computational hardness proofs) - -**AI & Machine Learning:** -- Deep reinforcement learning (AlphaGo-style neural networks for Hackenbush) -- Symbolic regression (discover new game theory theorems from data) -- Generative models (create interesting Hackenbush positions for puzzles) -- Neural surreal number arithmetic (learn surreal operations end-to-end) - -**Formal Verification:** -- Coq/Lean formalization of Conway's construction -- Certified game solver (verified correctness of value computation) -- Proof-producing game analysis (generate human-readable proofs of optimality) - -**Educational Technology:** -- Interactive textbook (Pluto.jl + Hackenbush animations) -- Gamified learning platform (earn surreal number badges) -- Research collaboration tool (shared game database for CGT community) - -### Ecosystem Integration - -- **Symbolics.jl:** Symbolic manipulation of surreal number expressions -- **JuMP.jl:** Optimization-based game solving (LP formulation of Hackenbush) -- **Graphs.jl:** Leverage advanced graph algorithms (matchings, flows, cuts) -- **DataFrames.jl:** Tabulate game databases with rich metadata - -### Ambitious Features - -- **Combinatorial game theory foundation model** - Pre-trained on all known solved games -- **Automated theorem discovery** - AI that proposes and proves new CGT conjectures -- **Virtual CGT conference** - Online platform for sharing positions, proofs, and puzzles -- **Hackenbush Olympics** - Annual tournament with cash prizes for best players/solvers - ---- - -## Future Horizons (v2.0+) - -### Surreal Economic & Financial Models -- [ ] **Game-Theoretic Asset Pricing**: Apply surreal number theory to model complex financial derivatives where payoffs are better represented as game positions than real numbers. -- [ ] **Incentive Alignment Verification**: Use Hackenbush game values to formally verify that a mechanism design (e.g., a multi-agent auction) is "Winning" for all participants. - -### Biological & Metabolic Hackenbush -- [ ] **Metabolic Game Theory**: Model metabolic pathways as Hackenbush graphs where enzyme reactions are "cuts" and steady-state fluxes are "Winning Strategies" for cellular survival. -- [ ] **Gene Regulatory Games**: Represent gene activation/inhibition as a partizan game to understand the robustness of biological switch networks. - -### Combinatorial Logic & Computing -- [ ] **Surreal Logic Gates**: Implement standard computing primitives (AND, OR, NOT) where the operands are Hackenbush game positions, enabling a new form of "Game-Based Computation". -- [ ] **Surreal Algebra System**: Full symbolic system for manipulating surreal numbers, including multiplication and division (which are notoriously difficult to implement for games). - -### AI Reasoning Benchmarks -- [ ] **Hackenbush AI Arena**: A specialized benchmark for testing the logical and mathematical reasoning of Large Language Models (LLMs) through interactive Hackenbush play. -- [ ] **Neuro-Symbolic Surrealism**: Train neural networks to "Intuiter" the game value of complex Hackenbush positions without exhaustive search. - ---- - -## Migration Path - -**v1.0 → v1.1:** Backward compatible (visualization and AI features are additive) -**v1.1 → v1.2:** Mostly compatible (loopy games may require new data structures) -**v1.2 → v1.3+:** Breaking changes likely (transfinite/quantum variants need fundamental redesign) - -## Community Goals - -- **Adoption by CGT researchers** (Siegel, Albert, Nowakowski) by v1.2 -- **Publication in Integers or similar** (CGT journal) by v1.2 -- **Workshop at Combinatorial Game Theory Colloquium** by v1.2 -- **1000 solved positions** in public database by v1.2 diff --git a/packages/HackenbushGames.jl/SECURITY.adoc b/packages/HackenbushGames.jl/SECURITY.adoc new file mode 100644 index 000000000..37d1bec60 --- /dev/null +++ b/packages/HackenbushGames.jl/SECURITY.adoc @@ -0,0 +1,425 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories/new[Report +a Vulnerability] If you cannot use GitHub Security Advisories, you may +email us directly: + +[cols=",",] +|=== +|*Email* |jonathan.jewell@open.ac.uk +|=== + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/HackenbushGames.jl+`) and all its +code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using HackenbushGames.jl, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories/new[Report +via GitHub] or jonathan.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/HackenbushGames.jl/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep HackenbushGames.jl and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/packages/HackenbushGames.jl/SECURITY.md b/packages/HackenbushGames.jl/SECURITY.md deleted file mode 100644 index ad8df81ae..000000000 --- a/packages/HackenbushGames.jl/SECURITY.md +++ /dev/null @@ -1,362 +0,0 @@ -# Security Policy - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories/new) -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | jonathan.jewell@open.ac.uk | - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/HackenbushGames.jl`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using HackenbushGames.jl, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Security Advisories](https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/HackenbushGames.jl/security/advisories/new) or jonathan.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/HackenbushGames.jl/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep HackenbushGames.jl and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/packages/HackenbushGames.jl/SONNET-TASKS.adoc b/packages/HackenbushGames.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..022250e90 --- /dev/null +++ b/packages/HackenbushGames.jl/SONNET-TASKS.adoc @@ -0,0 +1,573 @@ +== SONNET-TASKS.md — HackenbushGames.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 62% +____ + +The Julia core (`+src/HackenbushGames.jl+` + `+test/runtests.jl+`) is +genuinely functional with real implementations. However, the repository +is cloned from `+rsr-template-repo+` and most surrounding files still +contain `+{{PLACEHOLDER}}+` template tokens, the ABI/FFI layer is +entirely generic template code unrelated to Hackenbush, the +Documenter.jl setup references a missing `+api.md+` page, docs say +"`coming soon`", the `+examples/+` directory contains irrelevant +ReScript/Deno template files, the `+ROADMAP.adoc+` is still the RSR +template, `+CITATIONS.adoc+` references the template repo with wrong +author/license, there is no `+.machine_readable/+` directory with SCM +files, and the Manifest.toml version (0.1.0) contradicts Project.toml +version (1.0.0). + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update STATE.scm with honest completion percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix Manifest.toml version mismatch (HIGH) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/Manifest.toml+` + +*Problem:* Line 9 says `+version = "0.1.0"+` but `+Project.toml+` line 4 +says `+version = "1.0.0"+`. The Manifest is machine-generated and stale. + +*What to do:* 1. Delete `+Manifest.toml+` entirely. 2. Regenerate it: +`+cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.instantiate()'+` +3. Verify the regenerated `+Manifest.toml+` shows `+version = "1.0.0"+` +for HackenbushGames. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/HackenbushGames.jl && grep 'version = "1.0.0"' Manifest.toml +---- + +''''' + +=== TASK 2: Create .machine_readable/ directory with SCM files (HIGH) + +*Files:* - +`+/var$REPOS_DIR/HackenbushGames.jl/.machine_readable/STATE.scm+` +(create) - +`+/var$REPOS_DIR/HackenbushGames.jl/.machine_readable/ECOSYSTEM.scm+` +(create) - +`+/var$REPOS_DIR/HackenbushGames.jl/.machine_readable/META.scm+` +(create) + +*Problem:* The repo has no `+.machine_readable/+` directory at all. This +is mandatory for every hyperpolymath repo per CLAUDE.md. The AI.a2ml +file on line 9 references `+.machines_readable/6scm/STATE.scm+` which is +both a different path AND does not exist. + +*What to do:* 1. Create the directory: +`+mkdir -p /var$REPOS_DIR/HackenbushGames.jl/.machine_readable+` 2. +Create `+STATE.scm+` with content reflecting actual project state: - +Phase: implementation - Maturity: beta (core Julia code works, but +template artifacts are unfinished) - Completion: 62% - Blockers: +template placeholders, missing docs 3. Create `+ECOSYSTEM.scm+` placing +HackenbushGames.jl in the hyperpolymath Julia ecosystem, related to +combinatorial game theory. 4. Create `+META.scm+` with architecture +decisions (pure Julia, no deps, dyadic rationals, Grundy numbers). 5. +Use `+language-bridges+` repo as reference for SCM file format. + +*Verification:* + +[source,bash] +---- +ls /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/STATE.scm \ + /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/ECOSYSTEM.scm \ + /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/META.scm +---- + +''''' + +=== TASK 3: Replace all \{\{PLACEHOLDER}} tokens in CONTRIBUTING.md (HIGH) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/CONTRIBUTING.md+` + +*Problem:* Lines 2, 3, 9, 10, 20, 89, 90, 91, 92 all contain raw +`+{{FORGE}}+`, `+{{OWNER}}+`, `+{{REPO}}+` template placeholders. + +*What to do:* 1. Replace every `+{{FORGE}}+` with `+github.com+` 2. +Replace every `+{{OWNER}}+` with `+hyperpolymath+` 3. Replace every +`+{{REPO}}+` with `+HackenbushGames.jl+` 4. Review the entire file to +ensure no `+{{+` tokens remain. + +*Verification:* + +[source,bash] +---- +grep -c '{{' /var$REPOS_DIR/HackenbushGames.jl/CONTRIBUTING.md && echo "FAIL: placeholders remain" || echo "PASS" +---- + +''''' + +=== TASK 4: Replace all \{\{PLACEHOLDER}} tokens in CODE_OF_CONDUCT.md (HIGH) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/CODE_OF_CONDUCT.md+` + +*Problem:* Lines 7-14, 313 contain `+{{PLACEHOLDER}}+`, `+{{OWNER}}+`, +`+{{REPO}}+`, `+{{FORGE}}+`, `+{{PROJECT_NAME}}+`, +`+{{CONDUCT_EMAIL}}+`, `+{{CONDUCT_TEAM}}+`, `+{{RESPONSE_TIME}}+`, +`+{{CURRENT_YEAR}}+` template tokens. + +*What to do:* 1. Delete the template instruction comment block (lines +3-20 approximately). 2. Replace `+{{PROJECT_NAME}}+` with +`+HackenbushGames.jl+` 3. Replace `+{{OWNER}}+` with `+hyperpolymath+` +4. Replace `+{{REPO}}+` with `+HackenbushGames.jl+` 5. Replace +`+{{FORGE}}+` with `+github.com+` 6. Replace `+{{CONDUCT_EMAIL}}+` with +`+jonathan.jewell@open.ac.uk+` 7. Replace `+{{CONDUCT_TEAM}}+` with +`+Project Maintainers+` 8. Replace `+{{RESPONSE_TIME}}+` with +`+48 hours+` 9. Replace `+{{CURRENT_YEAR}}+` with `+2026+` + +*Verification:* + +[source,bash] +---- +grep -c '{{' /var$REPOS_DIR/HackenbushGames.jl/CODE_OF_CONDUCT.md && echo "FAIL: placeholders remain" || echo "PASS" +---- + +''''' + +=== TASK 5: Replace all \{\{PLACEHOLDER}} tokens in SECURITY.md (HIGH) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/SECURITY.md+` + +*Problem:* Lines 7-16, 43, 61-73, 206, 325, 374, 386-387, 402, 406 +contain `+{{OWNER}}+`, `+{{REPO}}+`, `+{{PROJECT_NAME}}+`, +`+{{SECURITY_EMAIL}}+`, `+{{PGP_FINGERPRINT}}+`, `+{{PGP_KEY_URL}}+`, +`+{{WEBSITE}}+`, `+{{CURRENT_YEAR}}+` template tokens. + +*What to do:* 1. Delete the template instruction comment block (lines +3-19). 2. Replace `+{{PROJECT_NAME}}+` with `+HackenbushGames.jl+` 3. +Replace `+{{OWNER}}+` with `+hyperpolymath+` 4. Replace `+{{REPO}}+` +with `+HackenbushGames.jl+` 5. Replace `+{{SECURITY_EMAIL}}+` with +`+jonathan.jewell@open.ac.uk+` 6. Remove the PGP section entirely (lines +60-74) since there is no PGP key configured. 7. Replace +`+{{CURRENT_YEAR}}+` with `+2026+` 8. Remove `+{{WEBSITE}}+` references +or replace with `+https://github.com/hyperpolymath+` + +*Verification:* + +[source,bash] +---- +grep -c '{{' /var$REPOS_DIR/HackenbushGames.jl/SECURITY.md && echo "FAIL: placeholders remain" || echo "PASS" +---- + +''''' + +=== TASK 6: Fix CITATIONS.adoc (HIGH) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/docs/CITATIONS.adoc+` + +*Problem:* The entire file (lines 1-36) references `+rsr-template-repo+` +instead of `+HackenbushGames.jl+`. The author is listed as +`+Polymath, Hyper+` instead of `+Jewell, Jonathan D.A.+`. The license +says `+AGPL-3.0-or-later+` instead of `+MPL-2.0+`. It references +`+CITATION.cff+` and `+codemeta.json+` which do not exist. + +*What to do:* 1. Replace every occurrence of `+rsr-template-repo+` and +`+RSR-template-repo+` with `+HackenbushGames.jl+` 2. Replace every +occurrence of `+RSR-template-repo+` in URLs with `+HackenbushGames.jl+` +3. Replace author `+Polymath, Hyper+` with `+Jewell, Jonathan D.A.+` in +all citation formats 4. Replace author `+Hyper Polymath+` with +`+Jonathan D.A. Jewell+` in OSCOLA format 5. Replace +`+AGPL-3.0-or-later+` with `+MPL-2.0+` 6. Replace year `+2025+` with +`+2026+` 7. Remove the `+See Also+` section referencing non-existent +`+CITATION.cff+` and `+codemeta.json+`, OR create those files +(preferred: remove the references). + +*Verification:* + +[source,bash] +---- +grep -c 'rsr-template-repo\|RSR-template-repo\|AGPL\|Polymath, Hyper' /var$REPOS_DIR/HackenbushGames.jl/docs/CITATIONS.adoc && echo "FAIL" || echo "PASS" +---- + +''''' + +=== TASK 7: Fix Documenter.jl — missing api.md page (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/HackenbushGames.jl/docs/make.jl+` (line 12) +- `+/var$REPOS_DIR/HackenbushGames.jl/docs/src/api.md+` (create) - +`+/var$REPOS_DIR/HackenbushGames.jl/docs/src/index.md+` (line 17) + +*Problem:* `+docs/make.jl+` line 12 references `+"API" => "api.md"+` but +`+docs/src/api.md+` does not exist. Also, `+docs/src/index.md+` line 17 +says `+# Examples coming soon+` which is a placeholder. + +*What to do:* 1. Create +`+/var$REPOS_DIR/HackenbushGames.jl/docs/src/api.md+` with proper +Documenter.jl autodoc blocks for all exported symbols: - `+EdgeColor+`, +`+Edge+`, `+HackenbushGraph+`, `+GameForm+` - `+Blue+`, `+Red+`, +`+Green+` - `+prune_disconnected+`, `+cut_edge+`, `+moves+`, +`+game_sum+` - `+simplest_dyadic_between+`, `+stalk_value+` - `+mex+`, +`+nim_sum+`, `+green_stalk_nimber+`, `+green_grundy+` - +`+simple_stalk+`, `+to_graphviz+`, `+to_ascii+` - `+canonical_game+`, +`+simplify_game+`, `+game_value+` Use `+@docs+` blocks, e.g.: +```markdown # API Reference + +## Types + +[source,@docs] +---- +EdgeColor +Edge +HackenbushGraph +GameForm +---- + +## Graph Operations + +[source,@docs] +---- +prune_disconnected +cut_edge +moves +game_sum +simple_stalk +---- + +(etc. for all exported symbols) ```+2. Replace+`# Examples coming +soon`+in+`docs/src/index.md` with actual examples matching the README.md +Quick Start section (lines 44-66). + +*Verification:* + +[source,bash] +---- +test -f /var$REPOS_DIR/HackenbushGames.jl/docs/src/api.md && echo "PASS: api.md exists" || echo "FAIL" +grep -c 'coming soon' /var$REPOS_DIR/HackenbushGames.jl/docs/src/index.md && echo "FAIL: placeholder remains" || echo "PASS" +---- + +''''' + +=== TASK 8: Remove irrelevant example files (MEDIUM) + +*Files:* - +`+/var$REPOS_DIR/HackenbushGames.jl/examples/SafeDOMExample.res+` +(delete) - +`+/var$REPOS_DIR/HackenbushGames.jl/examples/web-project-deno.json+` +(delete) + +*Problem:* These are RSR template boilerplate files for a ReScript web +project. They have nothing to do with a Julia Hackenbush game theory +library. `+SafeDOMExample.res+` line 1 also has +`+SPDX-License-Identifier: CC-BY-SA-4.0+` (wrong license). + +*What to do:* 1. Delete `+examples/SafeDOMExample.res+` 2. Delete +`+examples/web-project-deno.json+` 3. Create `+examples/basic_usage.jl+` +with working examples derived from README.md: - Stalk value computation +- Green Grundy number - Graph sum - Canonical game form - GraphViz and +ASCII output 4. Add SPDX header +`+# SPDX-License-Identifier: CC-BY-SA-4.0+` to the new file. + +*Verification:* + +[source,bash] +---- +test ! -f /var$REPOS_DIR/HackenbushGames.jl/examples/SafeDOMExample.res && echo "PASS: res deleted" || echo "FAIL" +test ! -f /var$REPOS_DIR/HackenbushGames.jl/examples/web-project-deno.json && echo "PASS: json deleted" || echo "FAIL" +cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. examples/basic_usage.jl +---- + +''''' + +=== TASK 9: Replace ROADMAP.adoc template content (MEDIUM) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/ROADMAP.adoc+` + +*Problem:* The entire file is the RSR template boilerplate +(`+YOUR Template Repo Roadmap+`, `+Core functionality+`, +`+To be determined+`). `+ROADMAP.md+` exists with real content but +`+ROADMAP.adoc+` is still the template. + +*What to do:* 1. Delete `+ROADMAP.adoc+` entirely (the real roadmap is +`+ROADMAP.md+`). OR replace its content with an AsciiDoc version of +`+ROADMAP.md+`. Preferred: delete `+ROADMAP.adoc+` since `+ROADMAP.md+` +is the authoritative file. + +*Verification:* + +[source,bash] +---- +test ! -f /var$REPOS_DIR/HackenbushGames.jl/ROADMAP.adoc && echo "PASS: template roadmap removed" || echo "FAIL" +test -f /var$REPOS_DIR/HackenbushGames.jl/ROADMAP.md && echo "PASS: real roadmap exists" || echo "FAIL" +---- + +''''' + +=== TASK 10: Remove or customize ABI/FFI template files (MEDIUM) + +*Files:* - `+/var$REPOS_DIR/HackenbushGames.jl/src/abi/Types.idr+` - +`+/var$REPOS_DIR/HackenbushGames.jl/src/abi/Layout.idr+` - +`+/var$REPOS_DIR/HackenbushGames.jl/src/abi/Foreign.idr+` - +`+/var$REPOS_DIR/HackenbushGames.jl/ffi/zig/build.zig+` - +`+/var$REPOS_DIR/HackenbushGames.jl/ffi/zig/src/main.zig+` - +`+/var$REPOS_DIR/HackenbushGames.jl/ffi/zig/test/integration_test.zig+` +- `+/var$REPOS_DIR/HackenbushGames.jl/ABI-FFI-README.md+` + +*Problem:* All 7 files are unmodified RSR template boilerplate with +`+{{PROJECT}}+` and `+{{project}}+` placeholders throughout (hundreds of +occurrences). They define generic `+Handle+`, `+Result+`, +`+ExampleStruct+` types that have nothing to do with Hackenbush. The Zig +files have `+SPDX-License-Identifier: CC-BY-SA-4.0+` (wrong license). +This is a pure Julia library with zero FFI needs. + +*What to do:* 1. Delete the entire `+src/abi/+` directory (3 Idris2 +template files). 2. Delete the entire `+ffi/zig/+` directory tree +(build.zig, src/main.zig, test/integration_test.zig). 3. Delete +`+ABI-FFI-README.md+`. 4. These are template scaffolding for projects +that need C FFI. A pure Julia library with no dependencies does not need +them. + +*Verification:* + +[source,bash] +---- +test ! -d /var$REPOS_DIR/HackenbushGames.jl/src/abi && echo "PASS: abi removed" || echo "FAIL" +test ! -d /var$REPOS_DIR/HackenbushGames.jl/ffi && echo "PASS: ffi removed" || echo "FAIL" +test ! -f /var$REPOS_DIR/HackenbushGames.jl/ABI-FFI-README.md && echo "PASS: abi readme removed" || echo "FAIL" +cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.test()' +---- + +''''' + +=== TASK 11: Fix AI.a2ml to reference correct paths (LOW) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/AI.a2ml+` + +*Problem:* Line 1 says this is `+rsr-template-repo+`. Line 6 says obey +Rhodium policies and keep `+.machines_readable/6scm/+` authoritative +(wrong path – should be `+.machine_readable/+` per CLAUDE.md). Line 9 +references `+.machines_readable/6scm/STATE.scm+` (wrong path). Line 10 +references `+.machines_readable/6scm/AGENTIC.scm+` (does not exist). + +*What to do:* 1. Replace the title/description to reference +HackenbushGames.jl, not rsr-template-repo. 2. Replace +`+.machines_readable/6scm/+` with `+.machine_readable/+` everywhere. 3. +Remove reference to `+AGENTIC.scm+` (does not exist in this repo, not +mandatory). 4. Update the workflow section to reflect actual project +structure. + +*Verification:* + +[source,bash] +---- +grep -c 'rsr-template-repo\|machines_readable\|6scm' /var$REPOS_DIR/HackenbushGames.jl/AI.a2ml && echo "FAIL" || echo "PASS" +---- + +''''' + +=== TASK 12: Fix CodeQL workflow language matrix (LOW) + +*Files:* +`+/var$REPOS_DIR/HackenbushGames.jl/.github/workflows/codeql.yml+` + +*Problem:* Line 24-25 configures CodeQL to scan +`+javascript-typescript+` language. This is a pure Julia repository with +no JavaScript or TypeScript files. CodeQL does not support Julia, so +this workflow should either scan `+actions+` (workflow files only) or be +removed. + +*What to do:* 1. Change the language matrix on line 24 from +`+javascript-typescript+` to `+actions+`. 2. Keep `+build-mode: none+` +since actions analysis does not need building. + +*Verification:* + +[source,bash] +---- +grep 'javascript-typescript' /var$REPOS_DIR/HackenbushGames.jl/.github/workflows/codeql.yml && echo "FAIL" || echo "PASS" +grep 'actions' /var$REPOS_DIR/HackenbushGames.jl/.github/workflows/codeql.yml && echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 13: Fix quality.yml TODO scanner to include Julia files (LOW) + +*Files:* +`+/var$REPOS_DIR/HackenbushGames.jl/.github/workflows/quality.yml+` + +*Problem:* Line 31 scans for TODOs in `+*.rs+`, `+*.res+`, `+*.py+`, +`+*.ex+` files only. This is a Julia project; it should scan `+*.jl+` +files. + +*What to do:* 1. On line 31, add `+--include="*.jl"+` to the grep +command. 2. Optionally remove `+*.rs+`, `+*.res+`, `+*.py+`, `+*.ex+` +includes since those languages are not present in this repo. + +*Verification:* + +[source,bash] +---- +grep '\.jl' /var$REPOS_DIR/HackenbushGames.jl/.github/workflows/quality.yml && echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 14: Add more comprehensive tests (LOW) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/test/runtests.jl+` + +*Problem:* The test suite has only 7 test cases. Key behaviors are +untested: - `+prune_disconnected+` is never directly tested. - +`+simplest_dyadic_between+` is never directly tested. - `+nim_sum+` is +never tested. - `+mex+` is never tested. - `+green_stalk_nimber+` is +never tested. - `+game_sum+` with empty graphs is not tested. - +`+game_value+` returning `+nothing+` for non-numeric positions is not +tested. - `+cut_edge+` with invalid index is not tested. - `+moves+` +with Green edges (both players can move) is not tested. - Edge cases: +empty graph, single-edge graph, multi-branch graphs. + +*What to do:* 1. Add a `+@testset "Prune Disconnected"+` block testing +that floating edges are removed. 2. Add a `+@testset "Simplest Dyadic"+` +block verifying: - `+simplest_dyadic_between(0//1, 1//1) == 1//2+` (or +the simplest integer 0 if 0 is between) - +`+simplest_dyadic_between(-1//1, 1//1) == 0//1+` - Error on `+l >= r+` +3. Add a `+@testset "Nim Sum"+` block: `+nim_sum([3, 5]) == 6+` (3 XOR +5). 4. Add a `+@testset "Mex"+` block: `+mex([0, 1, 3]) == 2+`, +`+mex(Int[]) == 0+`. 5. Add a `+@testset "Green Stalk Nimber"+` block: +`+green_stalk_nimber(5) == 5+`. 6. Add a `+@testset "Green Moves"+` +block: Green edges allow both left and right moves. 7. Add a +`+@testset "Empty Graph"+` block: empty graph has no moves, value 0//1. +8. Add a `+@testset "Game Value Nothing"+` testing a position where +`+game_value+` returns `+nothing+`. + +*Verification:* + +[source,julia] +---- +cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.test()' +---- + +''''' + +=== TASK 15: Fix README.adoc template content (LOW) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/README.adoc+` + +*Problem:* This is the RSR template README +(`+see RSR_OUTLINE.adoc in root+`, +`+This is your repo - don't forget to rename me!+`, SafeDOM examples). +It conflicts with the real README.md. A Julia Hackenbush library does +not need ReScript web dependency instructions. + +*What to do:* 1. Delete `+README.adoc+` entirely. The authoritative +README is `+README.md+`. OR convert it to an AsciiDoc version of +`+README.md+` with Hackenbush-specific content. Preferred: delete it to +avoid confusion. + +*Verification:* + +[source,bash] +---- +test ! -f /var$REPOS_DIR/HackenbushGames.jl/README.adoc && echo "PASS" || echo "FAIL" +test -f /var$REPOS_DIR/HackenbushGames.jl/README.md && echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 16: Fix RSR_OUTLINE.adoc template content (LOW) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/RSR_OUTLINE.adoc+` + +*Problem:* This is a generic RSR standard description file not specific +to this project. It references `+RSR-template-repo+`, `+139 repos+`, +`+justfile+`, `+guix.scm+`, `+STATE.scm+` in root (violates SCM path +rules), and includes a `+Cookbook generation+` section. None of this is +specific to HackenbushGames.jl. Line 212 says +`+SPDX-License-Identifier: CC-BY-SA-4.0+` (doubled suffix). + +*What to do:* 1. Either delete `+RSR_OUTLINE.adoc+` (it is RSR framework +docs, not project docs), or customize it to describe this project’s RSR +compliance status. Preferred: delete it. + +*Verification:* + +[source,bash] +---- +test ! -f /var$REPOS_DIR/HackenbushGames.jl/RSR_OUTLINE.adoc && echo "PASS" || echo "FAIL" +---- + +''''' + +=== TASK 17: Clean up ROADMAP.md false claims (LOW) + +*Files:* `+/var$REPOS_DIR/HackenbushGames.jl/ROADMAP.md+` + +*Problem:* Lines 5-13 claim "`Production-ready`" and "`Complete with +security hardening and comprehensive test coverage.`" It also claims +"`Game comparison (>, <, =, ||)`" (line 9) which is NOT implemented +anywhere in the source. The code has no `+>+`, `+<+`, `+==+`, or `+||+` +game comparison operators. It also claims "`Basic game operations +(negation, addition)`" (line 10) – `+game_sum+` exists but there is no +negation function. + +*What to do:* 1. Change "`Production-ready`" to "`Functional beta`" 2. +Remove or mark as TODO: "`Game comparison (>, <, =, ||)`" – not +implemented 3. Change "`Basic game operations (negation, addition)`" to +"`Basic game operations (addition via game_sum)`" 4. Change "`Complete +with security hardening and comprehensive test coverage`" to "`Core +algorithms implemented. Test coverage is basic (7 test cases).`" + +*Verification:* + +[source,bash] +---- +grep -c 'Production-ready\|Game comparison' /var$REPOS_DIR/HackenbushGames.jl/ROADMAP.md && echo "FAIL: false claims remain" || echo "PASS" +---- + +''''' + +=== FINAL VERIFICATION + +After all 17 tasks are complete, run the following sequence to confirm +everything works: + +[source,bash] +---- +# 1. Full test suite +cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.instantiate(); Pkg.test()' + +# 2. No template placeholders remain in any file +grep -r '{{' /var$REPOS_DIR/HackenbushGames.jl --include='*.md' --include='*.adoc' --include='*.yml' --include='*.idr' --include='*.zig' --include='*.a2ml' --include='*.djot' --include='*.res' --include='*.json' | grep -v '.git/' | grep -v 'node_modules' && echo "FAIL: template tokens remain" || echo "PASS: no template tokens" + +# 3. No AGPL references remain (old license, replaced by PMPL) +grep -r 'AGPL' /var$REPOS_DIR/HackenbushGames.jl --include='*.jl' --include='*.zig' --include='*.idr' --include='*.res' --include='*.adoc' | grep -v '.git/' && echo "FAIL: AGPL references remain" || echo "PASS: no AGPL" + +# 4. SCM files exist in correct location +ls /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/STATE.scm \ + /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/ECOSYSTEM.scm \ + /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/META.scm && echo "PASS: SCM files exist" || echo "FAIL" + +# 5. No irrelevant template files remain +test ! -f /var$REPOS_DIR/HackenbushGames.jl/examples/SafeDOMExample.res && \ +test ! -d /var$REPOS_DIR/HackenbushGames.jl/src/abi && \ +test ! -d /var$REPOS_DIR/HackenbushGames.jl/ffi && \ +echo "PASS: template artifacts removed" || echo "FAIL" + +# 6. Docs build check (optional, needs Documenter.jl installed) +cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=docs -e ' + using Pkg + Pkg.develop(PackageSpec(path=".")) + Pkg.instantiate() + include("docs/make.jl") +' 2>&1 | tail -5 + +# 7. Example runs without error +cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. examples/basic_usage.jl +---- diff --git a/packages/HackenbushGames.jl/SONNET-TASKS.md b/packages/HackenbushGames.jl/SONNET-TASKS.md deleted file mode 100644 index 73b307175..000000000 --- a/packages/HackenbushGames.jl/SONNET-TASKS.md +++ /dev/null @@ -1,521 +0,0 @@ -# SONNET-TASKS.md — HackenbushGames.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 62% - -The Julia core (`src/HackenbushGames.jl` + `test/runtests.jl`) is genuinely functional with -real implementations. However, the repository is cloned from `rsr-template-repo` and most -surrounding files still contain `{{PLACEHOLDER}}` template tokens, the ABI/FFI layer is -entirely generic template code unrelated to Hackenbush, the Documenter.jl setup references -a missing `api.md` page, docs say "coming soon", the `examples/` directory contains -irrelevant ReScript/Deno template files, the `ROADMAP.adoc` is still the RSR template, -`CITATIONS.adoc` references the template repo with wrong author/license, there is no -`.machine_readable/` directory with SCM files, and the Manifest.toml version (0.1.0) -contradicts Project.toml version (1.0.0). - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update STATE.scm with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix Manifest.toml version mismatch (HIGH) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/Manifest.toml` - -**Problem:** Line 9 says `version = "0.1.0"` but `Project.toml` line 4 says -`version = "1.0.0"`. The Manifest is machine-generated and stale. - -**What to do:** -1. Delete `Manifest.toml` entirely. -2. Regenerate it: `cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.instantiate()'` -3. Verify the regenerated `Manifest.toml` shows `version = "1.0.0"` for HackenbushGames. - -**Verification:** -```bash -cd /var$REPOS_DIR/HackenbushGames.jl && grep 'version = "1.0.0"' Manifest.toml -``` - ---- - -## TASK 2: Create .machine_readable/ directory with SCM files (HIGH) - -**Files:** -- `/var$REPOS_DIR/HackenbushGames.jl/.machine_readable/STATE.scm` (create) -- `/var$REPOS_DIR/HackenbushGames.jl/.machine_readable/ECOSYSTEM.scm` (create) -- `/var$REPOS_DIR/HackenbushGames.jl/.machine_readable/META.scm` (create) - -**Problem:** The repo has no `.machine_readable/` directory at all. This is mandatory for -every hyperpolymath repo per CLAUDE.md. The AI.a2ml file on line 9 references -`.machines_readable/6scm/STATE.scm` which is both a different path AND does not exist. - -**What to do:** -1. Create the directory: `mkdir -p /var$REPOS_DIR/HackenbushGames.jl/.machine_readable` -2. Create `STATE.scm` with content reflecting actual project state: - - Phase: implementation - - Maturity: beta (core Julia code works, but template artifacts are unfinished) - - Completion: 62% - - Blockers: template placeholders, missing docs -3. Create `ECOSYSTEM.scm` placing HackenbushGames.jl in the hyperpolymath Julia ecosystem, - related to combinatorial game theory. -4. Create `META.scm` with architecture decisions (pure Julia, no deps, dyadic rationals, - Grundy numbers). -5. Use `language-bridges` repo as reference for SCM file format. - -**Verification:** -```bash -ls /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/STATE.scm \ - /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/ECOSYSTEM.scm \ - /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/META.scm -``` - ---- - -## TASK 3: Replace all {{PLACEHOLDER}} tokens in CONTRIBUTING.md (HIGH) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/CONTRIBUTING.md` - -**Problem:** Lines 2, 3, 9, 10, 20, 89, 90, 91, 92 all contain raw `{{FORGE}}`, -`{{OWNER}}`, `{{REPO}}` template placeholders. - -**What to do:** -1. Replace every `{{FORGE}}` with `github.com` -2. Replace every `{{OWNER}}` with `hyperpolymath` -3. Replace every `{{REPO}}` with `HackenbushGames.jl` -4. Review the entire file to ensure no `{{` tokens remain. - -**Verification:** -```bash -grep -c '{{' /var$REPOS_DIR/HackenbushGames.jl/CONTRIBUTING.md && echo "FAIL: placeholders remain" || echo "PASS" -``` - ---- - -## TASK 4: Replace all {{PLACEHOLDER}} tokens in CODE_OF_CONDUCT.md (HIGH) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/CODE_OF_CONDUCT.md` - -**Problem:** Lines 7-14, 313 contain `{{PLACEHOLDER}}`, `{{OWNER}}`, `{{REPO}}`, -`{{FORGE}}`, `{{PROJECT_NAME}}`, `{{CONDUCT_EMAIL}}`, `{{CONDUCT_TEAM}}`, -`{{RESPONSE_TIME}}`, `{{CURRENT_YEAR}}` template tokens. - -**What to do:** -1. Delete the template instruction comment block (lines 3-20 approximately). -2. Replace `{{PROJECT_NAME}}` with `HackenbushGames.jl` -3. Replace `{{OWNER}}` with `hyperpolymath` -4. Replace `{{REPO}}` with `HackenbushGames.jl` -5. Replace `{{FORGE}}` with `github.com` -6. Replace `{{CONDUCT_EMAIL}}` with `jonathan.jewell@open.ac.uk` -7. Replace `{{CONDUCT_TEAM}}` with `Project Maintainers` -8. Replace `{{RESPONSE_TIME}}` with `48 hours` -9. Replace `{{CURRENT_YEAR}}` with `2026` - -**Verification:** -```bash -grep -c '{{' /var$REPOS_DIR/HackenbushGames.jl/CODE_OF_CONDUCT.md && echo "FAIL: placeholders remain" || echo "PASS" -``` - ---- - -## TASK 5: Replace all {{PLACEHOLDER}} tokens in SECURITY.md (HIGH) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/SECURITY.md` - -**Problem:** Lines 7-16, 43, 61-73, 206, 325, 374, 386-387, 402, 406 contain -`{{OWNER}}`, `{{REPO}}`, `{{PROJECT_NAME}}`, `{{SECURITY_EMAIL}}`, -`{{PGP_FINGERPRINT}}`, `{{PGP_KEY_URL}}`, `{{WEBSITE}}`, `{{CURRENT_YEAR}}` -template tokens. - -**What to do:** -1. Delete the template instruction comment block (lines 3-19). -2. Replace `{{PROJECT_NAME}}` with `HackenbushGames.jl` -3. Replace `{{OWNER}}` with `hyperpolymath` -4. Replace `{{REPO}}` with `HackenbushGames.jl` -5. Replace `{{SECURITY_EMAIL}}` with `jonathan.jewell@open.ac.uk` -6. Remove the PGP section entirely (lines 60-74) since there is no PGP key configured. -7. Replace `{{CURRENT_YEAR}}` with `2026` -8. Remove `{{WEBSITE}}` references or replace with `https://github.com/hyperpolymath` - -**Verification:** -```bash -grep -c '{{' /var$REPOS_DIR/HackenbushGames.jl/SECURITY.md && echo "FAIL: placeholders remain" || echo "PASS" -``` - ---- - -## TASK 6: Fix CITATIONS.adoc (HIGH) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/docs/CITATIONS.adoc` - -**Problem:** The entire file (lines 1-36) references `rsr-template-repo` instead of -`HackenbushGames.jl`. The author is listed as `Polymath, Hyper` instead of -`Jewell, Jonathan D.A.`. The license says `AGPL-3.0-or-later` instead of -`MPL-2.0`. It references `CITATION.cff` and `codemeta.json` which do not exist. - -**What to do:** -1. Replace every occurrence of `rsr-template-repo` and `RSR-template-repo` with `HackenbushGames.jl` -2. Replace every occurrence of `RSR-template-repo` in URLs with `HackenbushGames.jl` -3. Replace author `Polymath, Hyper` with `Jewell, Jonathan D.A.` in all citation formats -4. Replace author `Hyper Polymath` with `Jonathan D.A. Jewell` in OSCOLA format -5. Replace `AGPL-3.0-or-later` with `MPL-2.0` -6. Replace year `2025` with `2026` -7. Remove the `See Also` section referencing non-existent `CITATION.cff` and `codemeta.json`, - OR create those files (preferred: remove the references). - -**Verification:** -```bash -grep -c 'rsr-template-repo\|RSR-template-repo\|AGPL\|Polymath, Hyper' /var$REPOS_DIR/HackenbushGames.jl/docs/CITATIONS.adoc && echo "FAIL" || echo "PASS" -``` - ---- - -## TASK 7: Fix Documenter.jl — missing api.md page (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/HackenbushGames.jl/docs/make.jl` (line 12) -- `/var$REPOS_DIR/HackenbushGames.jl/docs/src/api.md` (create) -- `/var$REPOS_DIR/HackenbushGames.jl/docs/src/index.md` (line 17) - -**Problem:** `docs/make.jl` line 12 references `"API" => "api.md"` but `docs/src/api.md` -does not exist. Also, `docs/src/index.md` line 17 says `# Examples coming soon` which is -a placeholder. - -**What to do:** -1. Create `/var$REPOS_DIR/HackenbushGames.jl/docs/src/api.md` with proper - Documenter.jl autodoc blocks for all exported symbols: - - `EdgeColor`, `Edge`, `HackenbushGraph`, `GameForm` - - `Blue`, `Red`, `Green` - - `prune_disconnected`, `cut_edge`, `moves`, `game_sum` - - `simplest_dyadic_between`, `stalk_value` - - `mex`, `nim_sum`, `green_stalk_nimber`, `green_grundy` - - `simple_stalk`, `to_graphviz`, `to_ascii` - - `canonical_game`, `simplify_game`, `game_value` - Use `@docs` blocks, e.g.: - ```markdown - # API Reference - - ## Types - - ```@docs - EdgeColor - Edge - HackenbushGraph - GameForm - ``` - - ## Graph Operations - - ```@docs - prune_disconnected - cut_edge - moves - game_sum - simple_stalk - ``` - - (etc. for all exported symbols) - ``` -2. Replace `# Examples coming soon` in `docs/src/index.md` with actual examples matching - the README.md Quick Start section (lines 44-66). - -**Verification:** -```bash -test -f /var$REPOS_DIR/HackenbushGames.jl/docs/src/api.md && echo "PASS: api.md exists" || echo "FAIL" -grep -c 'coming soon' /var$REPOS_DIR/HackenbushGames.jl/docs/src/index.md && echo "FAIL: placeholder remains" || echo "PASS" -``` - ---- - -## TASK 8: Remove irrelevant example files (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/HackenbushGames.jl/examples/SafeDOMExample.res` (delete) -- `/var$REPOS_DIR/HackenbushGames.jl/examples/web-project-deno.json` (delete) - -**Problem:** These are RSR template boilerplate files for a ReScript web project. They have -nothing to do with a Julia Hackenbush game theory library. `SafeDOMExample.res` line 1 also -has `SPDX-License-Identifier: CC-BY-SA-4.0` (wrong license). - -**What to do:** -1. Delete `examples/SafeDOMExample.res` -2. Delete `examples/web-project-deno.json` -3. Create `examples/basic_usage.jl` with working examples derived from README.md: - - Stalk value computation - - Green Grundy number - - Graph sum - - Canonical game form - - GraphViz and ASCII output -4. Add SPDX header `# SPDX-License-Identifier: CC-BY-SA-4.0` to the new file. - -**Verification:** -```bash -test ! -f /var$REPOS_DIR/HackenbushGames.jl/examples/SafeDOMExample.res && echo "PASS: res deleted" || echo "FAIL" -test ! -f /var$REPOS_DIR/HackenbushGames.jl/examples/web-project-deno.json && echo "PASS: json deleted" || echo "FAIL" -cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. examples/basic_usage.jl -``` - ---- - -## TASK 9: Replace ROADMAP.adoc template content (MEDIUM) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/ROADMAP.adoc` - -**Problem:** The entire file is the RSR template boilerplate (`YOUR Template Repo Roadmap`, -`Core functionality`, `To be determined`). `ROADMAP.md` exists with real content but -`ROADMAP.adoc` is still the template. - -**What to do:** -1. Delete `ROADMAP.adoc` entirely (the real roadmap is `ROADMAP.md`). - OR replace its content with an AsciiDoc version of `ROADMAP.md`. - Preferred: delete `ROADMAP.adoc` since `ROADMAP.md` is the authoritative file. - -**Verification:** -```bash -test ! -f /var$REPOS_DIR/HackenbushGames.jl/ROADMAP.adoc && echo "PASS: template roadmap removed" || echo "FAIL" -test -f /var$REPOS_DIR/HackenbushGames.jl/ROADMAP.md && echo "PASS: real roadmap exists" || echo "FAIL" -``` - ---- - -## TASK 10: Remove or customize ABI/FFI template files (MEDIUM) - -**Files:** -- `/var$REPOS_DIR/HackenbushGames.jl/src/abi/Types.idr` -- `/var$REPOS_DIR/HackenbushGames.jl/src/abi/Layout.idr` -- `/var$REPOS_DIR/HackenbushGames.jl/src/abi/Foreign.idr` -- `/var$REPOS_DIR/HackenbushGames.jl/ffi/zig/build.zig` -- `/var$REPOS_DIR/HackenbushGames.jl/ffi/zig/src/main.zig` -- `/var$REPOS_DIR/HackenbushGames.jl/ffi/zig/test/integration_test.zig` -- `/var$REPOS_DIR/HackenbushGames.jl/ABI-FFI-README.md` - -**Problem:** All 7 files are unmodified RSR template boilerplate with `{{PROJECT}}` and -`{{project}}` placeholders throughout (hundreds of occurrences). They define generic -`Handle`, `Result`, `ExampleStruct` types that have nothing to do with Hackenbush. -The Zig files have `SPDX-License-Identifier: CC-BY-SA-4.0` (wrong license). -This is a pure Julia library with zero FFI needs. - -**What to do:** -1. Delete the entire `src/abi/` directory (3 Idris2 template files). -2. Delete the entire `ffi/zig/` directory tree (build.zig, src/main.zig, test/integration_test.zig). -3. Delete `ABI-FFI-README.md`. -4. These are template scaffolding for projects that need C FFI. A pure Julia library - with no dependencies does not need them. - -**Verification:** -```bash -test ! -d /var$REPOS_DIR/HackenbushGames.jl/src/abi && echo "PASS: abi removed" || echo "FAIL" -test ! -d /var$REPOS_DIR/HackenbushGames.jl/ffi && echo "PASS: ffi removed" || echo "FAIL" -test ! -f /var$REPOS_DIR/HackenbushGames.jl/ABI-FFI-README.md && echo "PASS: abi readme removed" || echo "FAIL" -cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.test()' -``` - ---- - -## TASK 11: Fix AI.a2ml to reference correct paths (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/AI.a2ml` - -**Problem:** Line 1 says this is `rsr-template-repo`. Line 6 says obey Rhodium policies -and keep `.machines_readable/6scm/` authoritative (wrong path -- should be -`.machine_readable/` per CLAUDE.md). Line 9 references `.machines_readable/6scm/STATE.scm` -(wrong path). Line 10 references `.machines_readable/6scm/AGENTIC.scm` (does not exist). - -**What to do:** -1. Replace the title/description to reference HackenbushGames.jl, not rsr-template-repo. -2. Replace `.machines_readable/6scm/` with `.machine_readable/` everywhere. -3. Remove reference to `AGENTIC.scm` (does not exist in this repo, not mandatory). -4. Update the workflow section to reflect actual project structure. - -**Verification:** -```bash -grep -c 'rsr-template-repo\|machines_readable\|6scm' /var$REPOS_DIR/HackenbushGames.jl/AI.a2ml && echo "FAIL" || echo "PASS" -``` - ---- - -## TASK 12: Fix CodeQL workflow language matrix (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/.github/workflows/codeql.yml` - -**Problem:** Line 24-25 configures CodeQL to scan `javascript-typescript` language. This is -a pure Julia repository with no JavaScript or TypeScript files. CodeQL does not support -Julia, so this workflow should either scan `actions` (workflow files only) or be removed. - -**What to do:** -1. Change the language matrix on line 24 from `javascript-typescript` to `actions`. -2. Keep `build-mode: none` since actions analysis does not need building. - -**Verification:** -```bash -grep 'javascript-typescript' /var$REPOS_DIR/HackenbushGames.jl/.github/workflows/codeql.yml && echo "FAIL" || echo "PASS" -grep 'actions' /var$REPOS_DIR/HackenbushGames.jl/.github/workflows/codeql.yml && echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 13: Fix quality.yml TODO scanner to include Julia files (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/.github/workflows/quality.yml` - -**Problem:** Line 31 scans for TODOs in `*.rs`, `*.res`, `*.py`, `*.ex` files only. This -is a Julia project; it should scan `*.jl` files. - -**What to do:** -1. On line 31, add `--include="*.jl"` to the grep command. -2. Optionally remove `*.rs`, `*.res`, `*.py`, `*.ex` includes since those languages are - not present in this repo. - -**Verification:** -```bash -grep '\.jl' /var$REPOS_DIR/HackenbushGames.jl/.github/workflows/quality.yml && echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 14: Add more comprehensive tests (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/test/runtests.jl` - -**Problem:** The test suite has only 7 test cases. Key behaviors are untested: -- `prune_disconnected` is never directly tested. -- `simplest_dyadic_between` is never directly tested. -- `nim_sum` is never tested. -- `mex` is never tested. -- `green_stalk_nimber` is never tested. -- `game_sum` with empty graphs is not tested. -- `game_value` returning `nothing` for non-numeric positions is not tested. -- `cut_edge` with invalid index is not tested. -- `moves` with Green edges (both players can move) is not tested. -- Edge cases: empty graph, single-edge graph, multi-branch graphs. - -**What to do:** -1. Add a `@testset "Prune Disconnected"` block testing that floating edges are removed. -2. Add a `@testset "Simplest Dyadic"` block verifying: - - `simplest_dyadic_between(0//1, 1//1) == 1//2` (or the simplest integer 0 if 0 is between) - - `simplest_dyadic_between(-1//1, 1//1) == 0//1` - - Error on `l >= r` -3. Add a `@testset "Nim Sum"` block: `nim_sum([3, 5]) == 6` (3 XOR 5). -4. Add a `@testset "Mex"` block: `mex([0, 1, 3]) == 2`, `mex(Int[]) == 0`. -5. Add a `@testset "Green Stalk Nimber"` block: `green_stalk_nimber(5) == 5`. -6. Add a `@testset "Green Moves"` block: Green edges allow both left and right moves. -7. Add a `@testset "Empty Graph"` block: empty graph has no moves, value 0//1. -8. Add a `@testset "Game Value Nothing"` testing a position where `game_value` returns `nothing`. - -**Verification:** -```julia -cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.test()' -``` - ---- - -## TASK 15: Fix README.adoc template content (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/README.adoc` - -**Problem:** This is the RSR template README (`see RSR_OUTLINE.adoc in root`, `This is -your repo - don't forget to rename me!`, SafeDOM examples). It conflicts with the real -README.md. A Julia Hackenbush library does not need ReScript web dependency instructions. - -**What to do:** -1. Delete `README.adoc` entirely. The authoritative README is `README.md`. - OR convert it to an AsciiDoc version of `README.md` with Hackenbush-specific content. - Preferred: delete it to avoid confusion. - -**Verification:** -```bash -test ! -f /var$REPOS_DIR/HackenbushGames.jl/README.adoc && echo "PASS" || echo "FAIL" -test -f /var$REPOS_DIR/HackenbushGames.jl/README.md && echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 16: Fix RSR_OUTLINE.adoc template content (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/RSR_OUTLINE.adoc` - -**Problem:** This is a generic RSR standard description file not specific to this project. -It references `RSR-template-repo`, `139 repos`, `justfile`, `guix.scm`, `STATE.scm` in -root (violates SCM path rules), and includes a `Cookbook generation` section. None of this -is specific to HackenbushGames.jl. Line 212 says `SPDX-License-Identifier: CC-BY-SA-4.0` (doubled suffix). - -**What to do:** -1. Either delete `RSR_OUTLINE.adoc` (it is RSR framework docs, not project docs), - or customize it to describe this project's RSR compliance status. - Preferred: delete it. - -**Verification:** -```bash -test ! -f /var$REPOS_DIR/HackenbushGames.jl/RSR_OUTLINE.adoc && echo "PASS" || echo "FAIL" -``` - ---- - -## TASK 17: Clean up ROADMAP.md false claims (LOW) - -**Files:** `/var$REPOS_DIR/HackenbushGames.jl/ROADMAP.md` - -**Problem:** Lines 5-13 claim "Production-ready" and "Complete with security hardening and -comprehensive test coverage." It also claims "Game comparison (>, <, =, ||)" (line 9) which -is NOT implemented anywhere in the source. The code has no `>`, `<`, `==`, or `||` game -comparison operators. It also claims "Basic game operations (negation, addition)" (line 10) --- `game_sum` exists but there is no negation function. - -**What to do:** -1. Change "Production-ready" to "Functional beta" -2. Remove or mark as TODO: "Game comparison (>, <, =, ||)" -- not implemented -3. Change "Basic game operations (negation, addition)" to "Basic game operations (addition via game_sum)" -4. Change "Complete with security hardening and comprehensive test coverage" to - "Core algorithms implemented. Test coverage is basic (7 test cases)." - -**Verification:** -```bash -grep -c 'Production-ready\|Game comparison' /var$REPOS_DIR/HackenbushGames.jl/ROADMAP.md && echo "FAIL: false claims remain" || echo "PASS" -``` - ---- - -## FINAL VERIFICATION - -After all 17 tasks are complete, run the following sequence to confirm everything works: - -```bash -# 1. Full test suite -cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. -e 'using Pkg; Pkg.instantiate(); Pkg.test()' - -# 2. No template placeholders remain in any file -grep -r '{{' /var$REPOS_DIR/HackenbushGames.jl --include='*.md' --include='*.adoc' --include='*.yml' --include='*.idr' --include='*.zig' --include='*.a2ml' --include='*.djot' --include='*.res' --include='*.json' | grep -v '.git/' | grep -v 'node_modules' && echo "FAIL: template tokens remain" || echo "PASS: no template tokens" - -# 3. No AGPL references remain (old license, replaced by PMPL) -grep -r 'AGPL' /var$REPOS_DIR/HackenbushGames.jl --include='*.jl' --include='*.zig' --include='*.idr' --include='*.res' --include='*.adoc' | grep -v '.git/' && echo "FAIL: AGPL references remain" || echo "PASS: no AGPL" - -# 4. SCM files exist in correct location -ls /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/STATE.scm \ - /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/ECOSYSTEM.scm \ - /var$REPOS_DIR/HackenbushGames.jl/.machine_readable/META.scm && echo "PASS: SCM files exist" || echo "FAIL" - -# 5. No irrelevant template files remain -test ! -f /var$REPOS_DIR/HackenbushGames.jl/examples/SafeDOMExample.res && \ -test ! -d /var$REPOS_DIR/HackenbushGames.jl/src/abi && \ -test ! -d /var$REPOS_DIR/HackenbushGames.jl/ffi && \ -echo "PASS: template artifacts removed" || echo "FAIL" - -# 6. Docs build check (optional, needs Documenter.jl installed) -cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=docs -e ' - using Pkg - Pkg.develop(PackageSpec(path=".")) - Pkg.instantiate() - include("docs/make.jl") -' 2>&1 | tail -5 - -# 7. Example runs without error -cd /var$REPOS_DIR/HackenbushGames.jl && julia --project=. examples/basic_usage.jl -``` diff --git a/packages/HackenbushGames.jl/TOPOLOGY.md b/packages/HackenbushGames.jl/TOPOLOGY.adoc similarity index 89% rename from packages/HackenbushGames.jl/TOPOLOGY.md rename to packages/HackenbushGames.jl/TOPOLOGY.adoc index 156db230d..bb2e83c91 100644 --- a/packages/HackenbushGames.jl/TOPOLOGY.md +++ b/packages/HackenbushGames.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== HackenbushGames.jl — Project Topology -# HackenbushGames.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE STRUCTURES @@ -69,26 +65,27 @@ INFRASTRUCTURE & DOCS ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Production Phase (Complete) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Hackenbush Graph ──────► Move Enumeration ──────► Game Evaluation │ Dyadic Arithmetic ──────► Red-Blue Stalks ───────────┤ │ Nimber Helpers ───────► Green Grundy ──────────────┘ -``` +.... -## 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/packages/HackenbushGames.jl/docs/src/api.adoc b/packages/HackenbushGames.jl/docs/src/api.adoc new file mode 100644 index 000000000..4df9d5987 --- /dev/null +++ b/packages/HackenbushGames.jl/docs/src/api.adoc @@ -0,0 +1,56 @@ +== API Reference + +Complete API documentation for HackenbushGames.jl. + +=== Types + +[source,@docs] +---- +EdgeColor +Edge +HackenbushGraph +GameForm +---- + +=== Color Constants + +[source,@docs] +---- +Blue +Red +Green +---- + +=== Graph Operations + +[source,@docs] +---- +prune_disconnected +cut_edge +moves +game_sum +---- + +=== Dyadic Rational Values + +[source,@docs] +---- +simplest_dyadic_between +stalk_value +---- + +=== Nimber Operations + +[source,@docs] +---- +mex +nim_sum +green_stalk_nimber +green_grundy +---- + +=== Index + +[source,@index] +---- +---- diff --git a/packages/HackenbushGames.jl/docs/src/api.md b/packages/HackenbushGames.jl/docs/src/api.md deleted file mode 100644 index 2258229d8..000000000 --- a/packages/HackenbushGames.jl/docs/src/api.md +++ /dev/null @@ -1,50 +0,0 @@ -# API Reference - -Complete API documentation for HackenbushGames.jl. - -## Types - -```@docs -EdgeColor -Edge -HackenbushGraph -GameForm -``` - -## Color Constants - -```@docs -Blue -Red -Green -``` - -## Graph Operations - -```@docs -prune_disconnected -cut_edge -moves -game_sum -``` - -## Dyadic Rational Values - -```@docs -simplest_dyadic_between -stalk_value -``` - -## Nimber Operations - -```@docs -mex -nim_sum -green_stalk_nimber -green_grundy -``` - -## Index - -```@index -``` diff --git a/packages/HackenbushGames.jl/docs/src/index.md b/packages/HackenbushGames.jl/docs/src/index.adoc similarity index 73% rename from packages/HackenbushGames.jl/docs/src/index.md rename to packages/HackenbushGames.jl/docs/src/index.adoc index e29aa7775..db7b3fe4d 100644 --- a/packages/HackenbushGames.jl/docs/src/index.md +++ b/packages/HackenbushGames.jl/docs/src/index.adoc @@ -1,17 +1,19 @@ -# HackenbushGames.jl +== HackenbushGames.jl Documentation for HackenbushGames.jl -## Installation +=== Installation -```julia +[source,julia] +---- using Pkg Pkg.add(url="https://github.com/hyperpolymath/HackenbushGames.jl") -``` +---- -## Quick Start +=== Quick Start -```julia +[source,julia] +---- using HackenbushGames # Red-Blue stalk value (ground -> top) @@ -27,8 +29,8 @@ edges = [ ] position = HackenbushGraph(edges, [0]) println(green_grundy(position)) -``` +---- -## API Reference +=== API Reference -See [API](api.md) for complete reference. +See link:api.md[API] for complete reference. diff --git a/packages/HardwareResilience.jl/TOPOLOGY.md b/packages/HardwareResilience.jl/TOPOLOGY.adoc similarity index 86% rename from packages/HardwareResilience.jl/TOPOLOGY.md rename to packages/HardwareResilience.jl/TOPOLOGY.adoc index 49e046786..962093bc0 100644 --- a/packages/HardwareResilience.jl/TOPOLOGY.md +++ b/packages/HardwareResilience.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== HardwareResilience.jl — Project Topology -# HardwareResilience.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ HARDWARE KERNELS │ ├─────────────────────────────────────────┤ @@ -36,11 +32,11 @@ │ REPO INFRASTRUCTURE │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE RESILIENCE @@ -53,24 +49,25 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █░░░░░░░░░ ~10% Initial Stub -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Kernel Execution ──────► Kernel Guardian ──────► Self-Healing │ Error Detection ───────► Error Handling ───────► COMPLETE -``` +.... -## 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/packages/Hyperpolymath.jl/TOPOLOGY.md b/packages/Hyperpolymath.jl/TOPOLOGY.adoc similarity index 89% rename from packages/Hyperpolymath.jl/TOPOLOGY.md rename to packages/Hyperpolymath.jl/TOPOLOGY.adoc index ddc698a7e..6937d31bd 100644 --- a/packages/Hyperpolymath.jl/TOPOLOGY.md +++ b/packages/Hyperpolymath.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Hyperpolymath.jl — Project Topology -# Hyperpolymath.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ JULIA REPL / USER SPACE │ ├─────────────────────────────────────────┤ @@ -47,11 +43,11 @@ │ │ LowLevel.jl│ ───▶ │ SiliconCore│ │ │ └────────────┘ └────────────┘ │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── ECOSYSTEM LAYERS @@ -69,26 +65,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Metapackage Complete -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... SiliconCore ──────► LowLevel ──────► Disciplinary Modules │ PostDisciplinary ◀──────────────────────────┘ │ Hyperpolymath.jl ──────► User REPL ──────► COMPLETE -``` +.... -## 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/packages/InvestigativeJournalism.jl/ABI-FFI-README.adoc b/packages/InvestigativeJournalism.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..46c07c05c --- /dev/null +++ b/packages/InvestigativeJournalism.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/%7B%7BOWNER%7D%7D/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/InvestigativeJournalism.jl/CHANGELOG.adoc b/packages/InvestigativeJournalism.jl/CHANGELOG.adoc new file mode 100644 index 000000000..ca1c65289 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/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/packages/InvestigativeJournalism.jl/CHANGELOG.md b/packages/InvestigativeJournalism.jl/CHANGELOG.md deleted file mode 100644 index 810947691..000000000 --- a/packages/InvestigativeJournalism.jl/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/packages/InvestigativeJournalism.jl/CODE_OF_CONDUCT.adoc b/packages/InvestigativeJournalism.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/InvestigativeJournalism.jl/CODE_OF_CONDUCT.md b/packages/InvestigativeJournalism.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/InvestigativeJournalism.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/InvestigativeJournalism.jl/CONTRIBUTING.adoc b/packages/InvestigativeJournalism.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..ad866b5ab --- /dev/null +++ b/packages/InvestigativeJournalism.jl/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/InvestigativeJournalism.jl/CONTRIBUTING.md b/packages/InvestigativeJournalism.jl/CONTRIBUTING.md deleted file mode 100644 index 02758c676..000000000 --- a/packages/InvestigativeJournalism.jl/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/InvestigativeJournalism.jl/GOVERNANCE.adoc b/packages/InvestigativeJournalism.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..6dddd7a45 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/GOVERNANCE.adoc @@ -0,0 +1,176 @@ +== Project Governance + +This document describes the governance model for *\{\{PROJECT_NAME}}*. + +''''' + +=== Project Governance Model + +\{\{PROJECT_NAME}} follows a *Benevolent Dictator For Life (BDFL)* +governance model. This model is well-suited for solo maintainers and +small project teams where rapid, consistent decision-making is more +valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including +technical direction, release schedules, contributor access, and +community standards. + +____ +*Transition clause:* When the core team exceeds three active +maintainers, this project should transition to a *consensus-based +governance model* with documented voting procedures. That transition +should itself be recorded as an Architecture Decision Record (ADR) in +`+docs/decisions/+`. +____ + +''''' + +=== Decision Making + +==== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (bug fixes, dependency updates, minor improvements) +may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on +non-trivial changes. + +==== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new features, breaking changes, architectural +shifts) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +==== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs in +`+docs/decisions/+`. +* ADR statuses: `+proposed+`, `+accepted+`, `+deprecated+`, +`+superseded+`, `+rejected+`. +* ADRs provide a historical record of why decisions were made and what +alternatives were considered. +* See `+.machine_readable/META.a2ml+` for the machine-readable ADR +index. + +''''' + +=== Roles + +==== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project’s technical direction and long-term vision. +* Has final say on all matters, including maintainer appointments and +removals. +* Responsible for ensuring the project adheres to RSR standards. + +==== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages releases. +* Upholds code quality, security standards, and the Code of Conduct. +* Listed in MAINTAINERS.md. + +==== Contributor + +* Anyone who submits pull requests, opens issues, or participates in +discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +==== Bot + +* Automated agents managed via your bot orchestration system. +* Perform automated code review, security scanning, dependency updates, +and standards enforcement. +* Bot actions are subject to the same quality and review standards as +human contributions. +* Configure your bots in `+.machine_readable/bot_directives/+`. + +''''' + +=== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they +demonstrate: + +[arabic] +. *Sustained quality contributions* – a track record of well-crafted +pull requests that follow project conventions and require minimal +revision. +. *Understanding of RSR standards* – familiarity with the Repository +Structure Requirements, security policies, and CI/CD workflows used +across the project. +. *Constructive participation* – helpful issue triage, thoughtful code +review comments, and mentoring of other contributors. +. *Reliability* – consistent engagement over a meaningful period +(typically 3+ months of active contribution). + +==== Process + +[arabic] +. An existing maintainer nominates the candidate by opening a private +discussion with the BDFL. +. The BDFL reviews the candidate’s contribution history and community +interactions. +. The BDFL approves or declines the nomination, with reasoning provided +to the nominator. +. If approved, the new maintainer is added to MAINTAINERS.md and granted +appropriate repository access. + +''''' + +=== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more +consecutive months. The maintainer will be contacted before removal and +offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the +link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the +enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons +(e.g., repeated disregard for project standards, loss of trust). +Reasoning will be documented privately. + +Removed maintainers are moved to the Emeritus section of MAINTAINERS.md +unless removal was due to a serious Code of Conduct violation. + +''''' + +=== Code of Conduct + +All participants in this project are expected to follow the +link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to +all project spaces, including issues, pull requests, discussions, and +any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The +BDFL serves as the final arbiter in conduct disputes. + +''''' + +=== Amendments + +This governance document may be amended by the BDFL at any time. All +amendments will be: + +[arabic] +. Documented as an ADR in `+docs/decisions/+` explaining the rationale +for the change. +. Committed to the repository with a clear commit message. +. Communicated to existing maintainers and contributors via the +project’s usual channels. + +Substantive changes (e.g., changing the governance model itself) should +be discussed with the community before adoption, even though the BDFL +retains final authority. + +''''' + +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/InvestigativeJournalism.jl/GOVERNANCE.md b/packages/InvestigativeJournalism.jl/GOVERNANCE.md deleted file mode 100644 index 5f082df92..000000000 --- a/packages/InvestigativeJournalism.jl/GOVERNANCE.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/InvestigativeJournalism.jl/MAINTAINERS.adoc b/packages/InvestigativeJournalism.jl/MAINTAINERS.adoc index d829dd959..f3a0e022b 100644 --- a/packages/InvestigativeJournalism.jl/MAINTAINERS.adoc +++ b/packages/InvestigativeJournalism.jl/MAINTAINERS.adoc @@ -1,47 +1,43 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of +*\{\{PROJECT_NAME}}*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|\{\{AUTHOR}} |https://github.com/%7B%7BOWNER%7D%7D[@\{OWNER}] |BDFL +|\{\{CURRENT_DATE}} |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/InvestigativeJournalism.jl/MAINTAINERS.md b/packages/InvestigativeJournalism.jl/MAINTAINERS.md deleted file mode 100644 index 32b92cc4a..000000000 --- a/packages/InvestigativeJournalism.jl/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **{{PROJECT_NAME}}**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| {{AUTHOR}} | [@{{OWNER}}](https://github.com/{{OWNER}}) | BDFL | {{CURRENT_DATE}} | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/InvestigativeJournalism.jl/PLACEHOLDERS.adoc b/packages/InvestigativeJournalism.jl/PLACEHOLDERS.adoc new file mode 100644 index 000000000..1ec75339b --- /dev/null +++ b/packages/InvestigativeJournalism.jl/PLACEHOLDERS.adoc @@ -0,0 +1,191 @@ +== Template Placeholders + +All placeholders in this template follow the `+{{PLACEHOLDER}}+` +pattern. After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) +sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) +sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) +sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) +sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) +sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) +sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) +sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{AUTHOR}}+` |Full legal name |`+Jane Doe+` |SPDX headers (all +files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md + +|`+{{AUTHOR_EMAIL}}+` |Primary contact email |`+jane@example.org+` |SPDX +headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+{{AUTHOR_LAST}}+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_FIRST}}+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_INITIALS}}+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{PROJECT_NAME}}+` |Human-readable project name |`+My Project+` +|SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, +GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json + +|`+{{PROJECT_DESCRIPTION}}+` |One-line description |`+A tool for X+` +|flake.nix + +|`+{{PROJECT}}+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+{{REPO}}+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+{{OWNER}}+` |GitHub/GitLab org or username |`+my-org+` |SPDX headers, +CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, +mirror.yml, cliff.toml + +|`+{{FORGE}}+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{CURRENT_YEAR}}+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+{{CURRENT_DATE}}+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+{{DATE}}+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{SECURITY_EMAIL}}+` |Security contact email +|`+security@example.org+` |SECURITY.md + +|`+{{PGP_FINGERPRINT}}+` |40-char PGP fingerprint |`+ABCD 1234 ...+` +|SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{MAIN_BRANCH}}+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{LICENSE}}+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+{{PROJECT_PURPOSE}}+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/packages/InvestigativeJournalism.jl/PLACEHOLDERS.md b/packages/InvestigativeJournalism.jl/PLACEHOLDERS.md deleted file mode 100644 index b6c9d28cc..000000000 --- a/packages/InvestigativeJournalism.jl/PLACEHOLDERS.md +++ /dev/null @@ -1,120 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/packages/InvestigativeJournalism.jl/SECURITY.adoc b/packages/InvestigativeJournalism.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/InvestigativeJournalism.jl/SECURITY.md b/packages/InvestigativeJournalism.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/InvestigativeJournalism.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/InvestigativeJournalism.jl/TOPOLOGY.md b/packages/InvestigativeJournalism.jl/TOPOLOGY.adoc similarity index 89% rename from packages/InvestigativeJournalism.jl/TOPOLOGY.md rename to packages/InvestigativeJournalism.jl/TOPOLOGY.adoc index 2a8dde5ab..f5ece5155 100644 --- a/packages/InvestigativeJournalism.jl/TOPOLOGY.md +++ b/packages/InvestigativeJournalism.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== InvestigativeJournalist.jl — Project Topology -# InvestigativeJournalist.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / SOURCES │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE WORKFLOW @@ -72,26 +68,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~80% Functional Prototype -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Ingest & Hash ──────► Claim Extraction ──────► Corroboration Matrix │ Timeline Analysis ◀─── Network Analysis ◀──────────┘ │ Story Architect ──────► Publication Pack ─────► COMPLETE -``` +.... -## 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/packages/InvestigativeJournalism.jl/docs/AI-CONVENTIONS.adoc b/packages/InvestigativeJournalism.jl/docs/AI-CONVENTIONS.adoc new file mode 100644 index 000000000..ba7e4ae74 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,81 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *\{\{AUTHOR}}* +* Email: *\{\{AUTHOR_EMAIL}}* +* Copyright: +`+Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>+` + +=== State Files + +State/metadata files (.a2ml) belong in `+.machine_readable/+` ONLY. +NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, +NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state diff --git a/packages/InvestigativeJournalism.jl/docs/AI-CONVENTIONS.md b/packages/InvestigativeJournalism.jl/docs/AI-CONVENTIONS.md deleted file mode 100644 index 37f594d12..000000000 --- a/packages/InvestigativeJournalism.jl/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,75 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state diff --git a/packages/InvestigativeJournalism.jl/docs/QUICKSTART.adoc b/packages/InvestigativeJournalism.jl/docs/QUICKSTART.adoc new file mode 100644 index 000000000..f000d4a13 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/docs/QUICKSTART.adoc @@ -0,0 +1,70 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/{{REPO}}.git +cd {{REPO}} +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +if you get stuck. diff --git a/packages/InvestigativeJournalism.jl/docs/QUICKSTART.md b/packages/InvestigativeJournalism.jl/docs/QUICKSTART.md deleted file mode 100644 index 724d8e111..000000000 --- a/packages/InvestigativeJournalism.jl/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/{{OWNER}}/{{REPO}}.git -cd {{REPO}} -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/{{OWNER}}/{{REPO}}/discussions) -if you get stuck. diff --git a/packages/InvestigativeJournalism.jl/docs/THREAT-MODEL.adoc b/packages/InvestigativeJournalism.jl/docs/THREAT-MODEL.adoc new file mode 100644 index 000000000..35aa8cc8e --- /dev/null +++ b/packages/InvestigativeJournalism.jl/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: \{\{PROJECT_NAME}} + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |\{\{PROJECT_NAME}} +|Version |1.0 +|Last Reviewed |\{\{DATE}} +|Author |\{\{AUTHOR}} +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of \{\{PROJECT_NAME}} and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/packages/InvestigativeJournalism.jl/docs/THREAT-MODEL.md b/packages/InvestigativeJournalism.jl/docs/THREAT-MODEL.md deleted file mode 100644 index c33fe79d8..000000000 --- a/packages/InvestigativeJournalism.jl/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/packages/InvestigativeJournalism.jl/docs/decisions/0000-template.adoc b/packages/InvestigativeJournalism.jl/docs/decisions/0000-template.adoc new file mode 100644 index 000000000..de603adff --- /dev/null +++ b/packages/InvestigativeJournalism.jl/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/packages/InvestigativeJournalism.jl/docs/decisions/0000-template.md b/packages/InvestigativeJournalism.jl/docs/decisions/0000-template.md deleted file mode 100644 index 2f7fc67de..000000000 --- a/packages/InvestigativeJournalism.jl/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/packages/InvestigativeJournalism.jl/docs/decisions/0001-adopt-rsr-standard.adoc b/packages/InvestigativeJournalism.jl/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 000000000..8e404cbbc --- /dev/null +++ b/packages/InvestigativeJournalism.jl/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/packages/InvestigativeJournalism.jl/docs/decisions/0001-adopt-rsr-standard.md b/packages/InvestigativeJournalism.jl/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index 806942f67..000000000 --- a/packages/InvestigativeJournalism.jl/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/packages/InvestigativeJournalism.jl/docs/decisions/README.adoc b/packages/InvestigativeJournalism.jl/docs/decisions/README.adoc new file mode 100644 index 000000000..3dc7a4856 --- /dev/null +++ b/packages/InvestigativeJournalism.jl/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/packages/InvestigativeJournalism.jl/docs/decisions/README.md b/packages/InvestigativeJournalism.jl/docs/decisions/README.md deleted file mode 100644 index 79851eea4..000000000 --- a/packages/InvestigativeJournalism.jl/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/packages/JuliaForChildren.jl/ABI-FFI-README.adoc b/packages/JuliaForChildren.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..46c07c05c --- /dev/null +++ b/packages/JuliaForChildren.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/%7B%7BOWNER%7D%7D/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/JuliaForChildren.jl/ABI-FFI-README.md b/packages/JuliaForChildren.jl/ABI-FFI-README.md deleted file mode 100644 index 320b3f6fa..000000000 --- a/packages/JuliaForChildren.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/JuliaForChildren.jl/CHANGELOG.adoc b/packages/JuliaForChildren.jl/CHANGELOG.adoc new file mode 100644 index 000000000..ca1c65289 --- /dev/null +++ b/packages/JuliaForChildren.jl/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/packages/JuliaForChildren.jl/CHANGELOG.md b/packages/JuliaForChildren.jl/CHANGELOG.md deleted file mode 100644 index 810947691..000000000 --- a/packages/JuliaForChildren.jl/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/packages/JuliaForChildren.jl/CODE_OF_CONDUCT.adoc b/packages/JuliaForChildren.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/JuliaForChildren.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/JuliaForChildren.jl/CODE_OF_CONDUCT.md b/packages/JuliaForChildren.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/JuliaForChildren.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/JuliaForChildren.jl/CONTRIBUTING.adoc b/packages/JuliaForChildren.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..ad866b5ab --- /dev/null +++ b/packages/JuliaForChildren.jl/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/JuliaForChildren.jl/CONTRIBUTING.md b/packages/JuliaForChildren.jl/CONTRIBUTING.md deleted file mode 100644 index 02758c676..000000000 --- a/packages/JuliaForChildren.jl/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/JuliaForChildren.jl/GOVERNANCE.adoc b/packages/JuliaForChildren.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..6dddd7a45 --- /dev/null +++ b/packages/JuliaForChildren.jl/GOVERNANCE.adoc @@ -0,0 +1,176 @@ +== Project Governance + +This document describes the governance model for *\{\{PROJECT_NAME}}*. + +''''' + +=== Project Governance Model + +\{\{PROJECT_NAME}} follows a *Benevolent Dictator For Life (BDFL)* +governance model. This model is well-suited for solo maintainers and +small project teams where rapid, consistent decision-making is more +valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including +technical direction, release schedules, contributor access, and +community standards. + +____ +*Transition clause:* When the core team exceeds three active +maintainers, this project should transition to a *consensus-based +governance model* with documented voting procedures. That transition +should itself be recorded as an Architecture Decision Record (ADR) in +`+docs/decisions/+`. +____ + +''''' + +=== Decision Making + +==== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (bug fixes, dependency updates, minor improvements) +may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on +non-trivial changes. + +==== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new features, breaking changes, architectural +shifts) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +==== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs in +`+docs/decisions/+`. +* ADR statuses: `+proposed+`, `+accepted+`, `+deprecated+`, +`+superseded+`, `+rejected+`. +* ADRs provide a historical record of why decisions were made and what +alternatives were considered. +* See `+.machine_readable/META.a2ml+` for the machine-readable ADR +index. + +''''' + +=== Roles + +==== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project’s technical direction and long-term vision. +* Has final say on all matters, including maintainer appointments and +removals. +* Responsible for ensuring the project adheres to RSR standards. + +==== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages releases. +* Upholds code quality, security standards, and the Code of Conduct. +* Listed in MAINTAINERS.md. + +==== Contributor + +* Anyone who submits pull requests, opens issues, or participates in +discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +==== Bot + +* Automated agents managed via your bot orchestration system. +* Perform automated code review, security scanning, dependency updates, +and standards enforcement. +* Bot actions are subject to the same quality and review standards as +human contributions. +* Configure your bots in `+.machine_readable/bot_directives/+`. + +''''' + +=== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they +demonstrate: + +[arabic] +. *Sustained quality contributions* – a track record of well-crafted +pull requests that follow project conventions and require minimal +revision. +. *Understanding of RSR standards* – familiarity with the Repository +Structure Requirements, security policies, and CI/CD workflows used +across the project. +. *Constructive participation* – helpful issue triage, thoughtful code +review comments, and mentoring of other contributors. +. *Reliability* – consistent engagement over a meaningful period +(typically 3+ months of active contribution). + +==== Process + +[arabic] +. An existing maintainer nominates the candidate by opening a private +discussion with the BDFL. +. The BDFL reviews the candidate’s contribution history and community +interactions. +. The BDFL approves or declines the nomination, with reasoning provided +to the nominator. +. If approved, the new maintainer is added to MAINTAINERS.md and granted +appropriate repository access. + +''''' + +=== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more +consecutive months. The maintainer will be contacted before removal and +offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the +link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the +enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons +(e.g., repeated disregard for project standards, loss of trust). +Reasoning will be documented privately. + +Removed maintainers are moved to the Emeritus section of MAINTAINERS.md +unless removal was due to a serious Code of Conduct violation. + +''''' + +=== Code of Conduct + +All participants in this project are expected to follow the +link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to +all project spaces, including issues, pull requests, discussions, and +any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The +BDFL serves as the final arbiter in conduct disputes. + +''''' + +=== Amendments + +This governance document may be amended by the BDFL at any time. All +amendments will be: + +[arabic] +. Documented as an ADR in `+docs/decisions/+` explaining the rationale +for the change. +. Committed to the repository with a clear commit message. +. Communicated to existing maintainers and contributors via the +project’s usual channels. + +Substantive changes (e.g., changing the governance model itself) should +be discussed with the community before adoption, even though the BDFL +retains final authority. + +''''' + +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaForChildren.jl/GOVERNANCE.md b/packages/JuliaForChildren.jl/GOVERNANCE.md deleted file mode 100644 index 5f082df92..000000000 --- a/packages/JuliaForChildren.jl/GOVERNANCE.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaForChildren.jl/MAINTAINERS.adoc b/packages/JuliaForChildren.jl/MAINTAINERS.adoc index d829dd959..f3a0e022b 100644 --- a/packages/JuliaForChildren.jl/MAINTAINERS.adoc +++ b/packages/JuliaForChildren.jl/MAINTAINERS.adoc @@ -1,47 +1,43 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of +*\{\{PROJECT_NAME}}*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|\{\{AUTHOR}} |https://github.com/%7B%7BOWNER%7D%7D[@\{OWNER}] |BDFL +|\{\{CURRENT_DATE}} |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaForChildren.jl/MAINTAINERS.md b/packages/JuliaForChildren.jl/MAINTAINERS.md deleted file mode 100644 index 32b92cc4a..000000000 --- a/packages/JuliaForChildren.jl/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **{{PROJECT_NAME}}**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| {{AUTHOR}} | [@{{OWNER}}](https://github.com/{{OWNER}}) | BDFL | {{CURRENT_DATE}} | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaForChildren.jl/PLACEHOLDERS.adoc b/packages/JuliaForChildren.jl/PLACEHOLDERS.adoc new file mode 100644 index 000000000..1ec75339b --- /dev/null +++ b/packages/JuliaForChildren.jl/PLACEHOLDERS.adoc @@ -0,0 +1,191 @@ +== Template Placeholders + +All placeholders in this template follow the `+{{PLACEHOLDER}}+` +pattern. After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) +sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) +sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) +sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) +sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) +sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) +sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) +sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{AUTHOR}}+` |Full legal name |`+Jane Doe+` |SPDX headers (all +files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md + +|`+{{AUTHOR_EMAIL}}+` |Primary contact email |`+jane@example.org+` |SPDX +headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+{{AUTHOR_LAST}}+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_FIRST}}+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_INITIALS}}+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{PROJECT_NAME}}+` |Human-readable project name |`+My Project+` +|SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, +GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json + +|`+{{PROJECT_DESCRIPTION}}+` |One-line description |`+A tool for X+` +|flake.nix + +|`+{{PROJECT}}+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+{{REPO}}+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+{{OWNER}}+` |GitHub/GitLab org or username |`+my-org+` |SPDX headers, +CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, +mirror.yml, cliff.toml + +|`+{{FORGE}}+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{CURRENT_YEAR}}+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+{{CURRENT_DATE}}+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+{{DATE}}+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{SECURITY_EMAIL}}+` |Security contact email +|`+security@example.org+` |SECURITY.md + +|`+{{PGP_FINGERPRINT}}+` |40-char PGP fingerprint |`+ABCD 1234 ...+` +|SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{MAIN_BRANCH}}+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{LICENSE}}+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+{{PROJECT_PURPOSE}}+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/packages/JuliaForChildren.jl/PLACEHOLDERS.md b/packages/JuliaForChildren.jl/PLACEHOLDERS.md deleted file mode 100644 index b6c9d28cc..000000000 --- a/packages/JuliaForChildren.jl/PLACEHOLDERS.md +++ /dev/null @@ -1,120 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/packages/JuliaForChildren.jl/SECURITY.adoc b/packages/JuliaForChildren.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/JuliaForChildren.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/JuliaForChildren.jl/SECURITY.md b/packages/JuliaForChildren.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/JuliaForChildren.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/JuliaForChildren.jl/TOPOLOGY.md b/packages/JuliaForChildren.jl/TOPOLOGY.adoc similarity index 89% rename from packages/JuliaForChildren.jl/TOPOLOGY.md rename to packages/JuliaForChildren.jl/TOPOLOGY.adoc index 999109e6a..5485383a9 100644 --- a/packages/JuliaForChildren.jl/TOPOLOGY.md +++ b/packages/JuliaForChildren.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== JuliaForChildren.jl — Project Topology -# JuliaForChildren.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / PLATFORMS │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE LEARNING @@ -68,26 +64,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Playable Alpha -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Curriculum Design ──────► Guided Lessons ──────► Achievement Tracking │ Visual Engine ──────► Coding Sandbox ───────────┤ │ External Bridges ──────► Game/Robot Integration ──┘ -``` +.... -## 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/packages/JuliaForChildren.jl/docs/AI-CONVENTIONS.adoc b/packages/JuliaForChildren.jl/docs/AI-CONVENTIONS.adoc new file mode 100644 index 000000000..ba7e4ae74 --- /dev/null +++ b/packages/JuliaForChildren.jl/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,81 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *\{\{AUTHOR}}* +* Email: *\{\{AUTHOR_EMAIL}}* +* Copyright: +`+Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>+` + +=== State Files + +State/metadata files (.a2ml) belong in `+.machine_readable/+` ONLY. +NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, +NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state diff --git a/packages/JuliaForChildren.jl/docs/AI-CONVENTIONS.md b/packages/JuliaForChildren.jl/docs/AI-CONVENTIONS.md deleted file mode 100644 index 37f594d12..000000000 --- a/packages/JuliaForChildren.jl/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,75 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state diff --git a/packages/JuliaForChildren.jl/docs/QUICKSTART.adoc b/packages/JuliaForChildren.jl/docs/QUICKSTART.adoc new file mode 100644 index 000000000..f000d4a13 --- /dev/null +++ b/packages/JuliaForChildren.jl/docs/QUICKSTART.adoc @@ -0,0 +1,70 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/{{REPO}}.git +cd {{REPO}} +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +if you get stuck. diff --git a/packages/JuliaForChildren.jl/docs/QUICKSTART.md b/packages/JuliaForChildren.jl/docs/QUICKSTART.md deleted file mode 100644 index 724d8e111..000000000 --- a/packages/JuliaForChildren.jl/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/{{OWNER}}/{{REPO}}.git -cd {{REPO}} -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/{{OWNER}}/{{REPO}}/discussions) -if you get stuck. diff --git a/packages/JuliaForChildren.jl/docs/THREAT-MODEL.adoc b/packages/JuliaForChildren.jl/docs/THREAT-MODEL.adoc new file mode 100644 index 000000000..35aa8cc8e --- /dev/null +++ b/packages/JuliaForChildren.jl/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: \{\{PROJECT_NAME}} + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |\{\{PROJECT_NAME}} +|Version |1.0 +|Last Reviewed |\{\{DATE}} +|Author |\{\{AUTHOR}} +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of \{\{PROJECT_NAME}} and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/packages/JuliaForChildren.jl/docs/THREAT-MODEL.md b/packages/JuliaForChildren.jl/docs/THREAT-MODEL.md deleted file mode 100644 index c33fe79d8..000000000 --- a/packages/JuliaForChildren.jl/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/packages/JuliaForChildren.jl/docs/decisions/0000-template.adoc b/packages/JuliaForChildren.jl/docs/decisions/0000-template.adoc new file mode 100644 index 000000000..de603adff --- /dev/null +++ b/packages/JuliaForChildren.jl/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/packages/JuliaForChildren.jl/docs/decisions/0000-template.md b/packages/JuliaForChildren.jl/docs/decisions/0000-template.md deleted file mode 100644 index 2f7fc67de..000000000 --- a/packages/JuliaForChildren.jl/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/packages/JuliaForChildren.jl/docs/decisions/0001-adopt-rsr-standard.adoc b/packages/JuliaForChildren.jl/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 000000000..8e404cbbc --- /dev/null +++ b/packages/JuliaForChildren.jl/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/packages/JuliaForChildren.jl/docs/decisions/0001-adopt-rsr-standard.md b/packages/JuliaForChildren.jl/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index 806942f67..000000000 --- a/packages/JuliaForChildren.jl/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/packages/JuliaForChildren.jl/docs/decisions/README.adoc b/packages/JuliaForChildren.jl/docs/decisions/README.adoc new file mode 100644 index 000000000..3dc7a4856 --- /dev/null +++ b/packages/JuliaForChildren.jl/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/packages/JuliaForChildren.jl/docs/decisions/README.md b/packages/JuliaForChildren.jl/docs/decisions/README.md deleted file mode 100644 index 79851eea4..000000000 --- a/packages/JuliaForChildren.jl/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/ABI-FFI-README.adoc b/packages/JuliaPackage-Reuse-Audit.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..46c07c05c --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/%7B%7BOWNER%7D%7D/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/JuliaPackage-Reuse-Audit.jl/ABI-FFI-README.md b/packages/JuliaPackage-Reuse-Audit.jl/ABI-FFI-README.md deleted file mode 100644 index 320b3f6fa..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/JuliaPackage-Reuse-Audit.jl/CHANGELOG.adoc b/packages/JuliaPackage-Reuse-Audit.jl/CHANGELOG.adoc new file mode 100644 index 000000000..ca1c65289 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/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/packages/JuliaPackage-Reuse-Audit.jl/CHANGELOG.md b/packages/JuliaPackage-Reuse-Audit.jl/CHANGELOG.md deleted file mode 100644 index 810947691..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/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/packages/JuliaPackage-Reuse-Audit.jl/CODE_OF_CONDUCT.adoc b/packages/JuliaPackage-Reuse-Audit.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/JuliaPackage-Reuse-Audit.jl/CODE_OF_CONDUCT.md b/packages/JuliaPackage-Reuse-Audit.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/JuliaPackage-Reuse-Audit.jl/CONTRIBUTING.adoc b/packages/JuliaPackage-Reuse-Audit.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..ad866b5ab --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/JuliaPackage-Reuse-Audit.jl/CONTRIBUTING.md b/packages/JuliaPackage-Reuse-Audit.jl/CONTRIBUTING.md deleted file mode 100644 index 02758c676..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/JuliaPackage-Reuse-Audit.jl/GOVERNANCE.adoc b/packages/JuliaPackage-Reuse-Audit.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..6dddd7a45 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/GOVERNANCE.adoc @@ -0,0 +1,176 @@ +== Project Governance + +This document describes the governance model for *\{\{PROJECT_NAME}}*. + +''''' + +=== Project Governance Model + +\{\{PROJECT_NAME}} follows a *Benevolent Dictator For Life (BDFL)* +governance model. This model is well-suited for solo maintainers and +small project teams where rapid, consistent decision-making is more +valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including +technical direction, release schedules, contributor access, and +community standards. + +____ +*Transition clause:* When the core team exceeds three active +maintainers, this project should transition to a *consensus-based +governance model* with documented voting procedures. That transition +should itself be recorded as an Architecture Decision Record (ADR) in +`+docs/decisions/+`. +____ + +''''' + +=== Decision Making + +==== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (bug fixes, dependency updates, minor improvements) +may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on +non-trivial changes. + +==== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new features, breaking changes, architectural +shifts) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +==== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs in +`+docs/decisions/+`. +* ADR statuses: `+proposed+`, `+accepted+`, `+deprecated+`, +`+superseded+`, `+rejected+`. +* ADRs provide a historical record of why decisions were made and what +alternatives were considered. +* See `+.machine_readable/META.a2ml+` for the machine-readable ADR +index. + +''''' + +=== Roles + +==== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project’s technical direction and long-term vision. +* Has final say on all matters, including maintainer appointments and +removals. +* Responsible for ensuring the project adheres to RSR standards. + +==== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages releases. +* Upholds code quality, security standards, and the Code of Conduct. +* Listed in MAINTAINERS.md. + +==== Contributor + +* Anyone who submits pull requests, opens issues, or participates in +discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +==== Bot + +* Automated agents managed via your bot orchestration system. +* Perform automated code review, security scanning, dependency updates, +and standards enforcement. +* Bot actions are subject to the same quality and review standards as +human contributions. +* Configure your bots in `+.machine_readable/bot_directives/+`. + +''''' + +=== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they +demonstrate: + +[arabic] +. *Sustained quality contributions* – a track record of well-crafted +pull requests that follow project conventions and require minimal +revision. +. *Understanding of RSR standards* – familiarity with the Repository +Structure Requirements, security policies, and CI/CD workflows used +across the project. +. *Constructive participation* – helpful issue triage, thoughtful code +review comments, and mentoring of other contributors. +. *Reliability* – consistent engagement over a meaningful period +(typically 3+ months of active contribution). + +==== Process + +[arabic] +. An existing maintainer nominates the candidate by opening a private +discussion with the BDFL. +. The BDFL reviews the candidate’s contribution history and community +interactions. +. The BDFL approves or declines the nomination, with reasoning provided +to the nominator. +. If approved, the new maintainer is added to MAINTAINERS.md and granted +appropriate repository access. + +''''' + +=== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more +consecutive months. The maintainer will be contacted before removal and +offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the +link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the +enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons +(e.g., repeated disregard for project standards, loss of trust). +Reasoning will be documented privately. + +Removed maintainers are moved to the Emeritus section of MAINTAINERS.md +unless removal was due to a serious Code of Conduct violation. + +''''' + +=== Code of Conduct + +All participants in this project are expected to follow the +link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to +all project spaces, including issues, pull requests, discussions, and +any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The +BDFL serves as the final arbiter in conduct disputes. + +''''' + +=== Amendments + +This governance document may be amended by the BDFL at any time. All +amendments will be: + +[arabic] +. Documented as an ADR in `+docs/decisions/+` explaining the rationale +for the change. +. Committed to the repository with a clear commit message. +. Communicated to existing maintainers and contributors via the +project’s usual channels. + +Substantive changes (e.g., changing the governance model itself) should +be discussed with the community before adoption, even though the BDFL +retains final authority. + +''''' + +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/GOVERNANCE.md b/packages/JuliaPackage-Reuse-Audit.jl/GOVERNANCE.md deleted file mode 100644 index 5f082df92..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/GOVERNANCE.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.adoc b/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.adoc index d829dd959..f3a0e022b 100644 --- a/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.adoc +++ b/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.adoc @@ -1,47 +1,43 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of +*\{\{PROJECT_NAME}}*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|\{\{AUTHOR}} |https://github.com/%7B%7BOWNER%7D%7D[@\{OWNER}] |BDFL +|\{\{CURRENT_DATE}} |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.md b/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.md deleted file mode 100644 index 32b92cc4a..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **{{PROJECT_NAME}}**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| {{AUTHOR}} | [@{{OWNER}}](https://github.com/{{OWNER}}) | BDFL | {{CURRENT_DATE}} | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/PLACEHOLDERS.adoc b/packages/JuliaPackage-Reuse-Audit.jl/PLACEHOLDERS.adoc new file mode 100644 index 000000000..1ec75339b --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/PLACEHOLDERS.adoc @@ -0,0 +1,191 @@ +== Template Placeholders + +All placeholders in this template follow the `+{{PLACEHOLDER}}+` +pattern. After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) +sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) +sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) +sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) +sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) +sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) +sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) +sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{AUTHOR}}+` |Full legal name |`+Jane Doe+` |SPDX headers (all +files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md + +|`+{{AUTHOR_EMAIL}}+` |Primary contact email |`+jane@example.org+` |SPDX +headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+{{AUTHOR_LAST}}+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_FIRST}}+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_INITIALS}}+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{PROJECT_NAME}}+` |Human-readable project name |`+My Project+` +|SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, +GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json + +|`+{{PROJECT_DESCRIPTION}}+` |One-line description |`+A tool for X+` +|flake.nix + +|`+{{PROJECT}}+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+{{REPO}}+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+{{OWNER}}+` |GitHub/GitLab org or username |`+my-org+` |SPDX headers, +CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, +mirror.yml, cliff.toml + +|`+{{FORGE}}+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{CURRENT_YEAR}}+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+{{CURRENT_DATE}}+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+{{DATE}}+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{SECURITY_EMAIL}}+` |Security contact email +|`+security@example.org+` |SECURITY.md + +|`+{{PGP_FINGERPRINT}}+` |40-char PGP fingerprint |`+ABCD 1234 ...+` +|SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{MAIN_BRANCH}}+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{LICENSE}}+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+{{PROJECT_PURPOSE}}+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/PLACEHOLDERS.md b/packages/JuliaPackage-Reuse-Audit.jl/PLACEHOLDERS.md deleted file mode 100644 index b6c9d28cc..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/PLACEHOLDERS.md +++ /dev/null @@ -1,120 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/SECURITY.adoc b/packages/JuliaPackage-Reuse-Audit.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/JuliaPackage-Reuse-Audit.jl/SECURITY.md b/packages/JuliaPackage-Reuse-Audit.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/JuliaPackage-Reuse-Audit.jl/TOPOLOGY.md b/packages/JuliaPackage-Reuse-Audit.jl/TOPOLOGY.adoc similarity index 89% rename from packages/JuliaPackage-Reuse-Audit.jl/TOPOLOGY.md rename to packages/JuliaPackage-Reuse-Audit.jl/TOPOLOGY.adoc index 08815182c..382334c75 100644 --- a/packages/JuliaPackage-Reuse-Audit.jl/TOPOLOGY.md +++ b/packages/JuliaPackage-Reuse-Audit.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== JuliaPackageSpitter.jl — Project Topology -# JuliaPackageSpitter.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── SCAFFOLDING ENGINE @@ -67,26 +63,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% Feature Complete -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... RSR Templates ──────► Template Processor ──────► Package Generator │ CI Profiles ─────────► CI Scaffolder ────────────┤ │ LLM Briefing ────────► SONNET-TASKS ───────────► COMPLETE -``` +.... -## 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/packages/JuliaPackage-Reuse-Audit.jl/docs/AI-CONVENTIONS.adoc b/packages/JuliaPackage-Reuse-Audit.jl/docs/AI-CONVENTIONS.adoc new file mode 100644 index 000000000..ba7e4ae74 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,81 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *\{\{AUTHOR}}* +* Email: *\{\{AUTHOR_EMAIL}}* +* Copyright: +`+Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>+` + +=== State Files + +State/metadata files (.a2ml) belong in `+.machine_readable/+` ONLY. +NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, +NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/AI-CONVENTIONS.md b/packages/JuliaPackage-Reuse-Audit.jl/docs/AI-CONVENTIONS.md deleted file mode 100644 index 37f594d12..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,75 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/QUICKSTART.adoc b/packages/JuliaPackage-Reuse-Audit.jl/docs/QUICKSTART.adoc new file mode 100644 index 000000000..f000d4a13 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/docs/QUICKSTART.adoc @@ -0,0 +1,70 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/{{REPO}}.git +cd {{REPO}} +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +if you get stuck. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/QUICKSTART.md b/packages/JuliaPackage-Reuse-Audit.jl/docs/QUICKSTART.md deleted file mode 100644 index 724d8e111..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/{{OWNER}}/{{REPO}}.git -cd {{REPO}} -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/{{OWNER}}/{{REPO}}/discussions) -if you get stuck. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/THREAT-MODEL.adoc b/packages/JuliaPackage-Reuse-Audit.jl/docs/THREAT-MODEL.adoc new file mode 100644 index 000000000..35aa8cc8e --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: \{\{PROJECT_NAME}} + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |\{\{PROJECT_NAME}} +|Version |1.0 +|Last Reviewed |\{\{DATE}} +|Author |\{\{AUTHOR}} +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of \{\{PROJECT_NAME}} and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/THREAT-MODEL.md b/packages/JuliaPackage-Reuse-Audit.jl/docs/THREAT-MODEL.md deleted file mode 100644 index c33fe79d8..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0000-template.adoc b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0000-template.adoc new file mode 100644 index 000000000..de603adff --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0000-template.md b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0000-template.md deleted file mode 100644 index 2f7fc67de..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0001-adopt-rsr-standard.adoc b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 000000000..8e404cbbc --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0001-adopt-rsr-standard.md b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index 806942f67..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/README.adoc b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/README.adoc new file mode 100644 index 000000000..3dc7a4856 --- /dev/null +++ b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/README.md b/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/README.md deleted file mode 100644 index 79851eea4..000000000 --- a/packages/JuliaPackage-Reuse-Audit.jl/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/packages/InvestigativeJournalism.jl/ABI-FFI-README.md b/packages/KnotTheory.jl/ABI-FFI-README.adoc similarity index 74% rename from packages/InvestigativeJournalism.jl/ABI-FFI-README.md rename to packages/KnotTheory.jl/ABI-FFI-README.adoc index 320b3f6fa..8e5244189 100644 --- a/packages/InvestigativeJournalism.jl/ABI-FFI-README.md +++ b/packages/KnotTheory.jl/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# {{PROJECT}} ABI/FFI Documentation +== \{\{PROJECT}} ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... {{project}}/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/KnotTheory.jl/ABI-FFI-README.md b/packages/KnotTheory.jl/ABI-FFI-README.md deleted file mode 100644 index 08d35da64..000000000 --- a/packages/KnotTheory.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/KnotTheory.jl/CODE_OF_CONDUCT.adoc b/packages/KnotTheory.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/KnotTheory.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/KnotTheory.jl/CODE_OF_CONDUCT.md b/packages/KnotTheory.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/KnotTheory.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/KnotTheory.jl/CONTRIBUTING.adoc b/packages/KnotTheory.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/KnotTheory.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/KnotTheory.jl/CONTRIBUTING.md b/packages/KnotTheory.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/KnotTheory.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/KnotTheory.jl/README.adoc b/packages/KnotTheory.jl/README.adoc index c8c706a8e..9d673ef81 100644 --- a/packages/KnotTheory.jl/README.adoc +++ b/packages/KnotTheory.jl/README.adoc @@ -1,143 +1,230 @@ -= KnotTheory.jl -:toc: macro +== KnotTheory.jl -**Julia Toolkit for Knot Theory** -_Planar diagrams, invariants, and import/export helpers for knot theorists and mathematicians._ +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-95%25-green[Completion +Status]] +link:LICENSE[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License]] -toc::[] +A comprehensive Julia toolkit for computational knot theory: planar +diagram data structures, classical invariants, polynomial invariants, +Seifert theory, Reidemeister simplification, braid word interop, and +import/export helpers. -== What is KnotTheory.jl? - -KnotTheory.jl is a **Julia toolkit** designed for: -- **Planar diagram manipulation** – Create, visualize, and transform knot diagrams. -- **Invariant computation** – Calculate polynomial invariants (Jones, Alexander, HOMFLY-PT, etc.). -- **Import/export helpers** – Seamlessly exchange data with other knot theory software (e.g., SnapPy, KnotAtlas). -- **Formal verification** – Ensure correctness of knot transformations and invariants. - -[source,julia] ----- -using KnotTheory - -# Define a trefoil knot -trefoil = Knot([1, -2, 3, -1, 2, -3]) - -# Compute the Jones polynomial -jones_poly = jones_polynomial(trefoil) - -# Visualize the knot -plot(trefoil) ----- - -== Features - -=== Planar Diagram Tools -- **Knot and link diagrams** – Create and manipulate planar projections. -- **Reidemeister moves** – Apply moves programmatically and verify equivalence. -- **Crossing information** – Track over/under crossings and writhe. - -[source,julia] ----- -# Apply a Reidemeister I move -new_knot = reidemeister1(trefoil, crossing=1) - -# Check if two knots are equivalent -are_equivalent(trefoil, new_knot) ----- - -=== Invariant Calculation -- **Jones polynomial** – Compute with normalization options. -- **Alexander polynomial** – Support for both single-variable and multivariable versions. -- **Khovanov homology** – Categorification of the Jones polynomial. - -[source,julia] ----- -# Compute the Alexander polynomial -alexander_poly = alexander_polynomial(trefoil) - -# Khovanov homology -khovanov = khovanov_homology(trefoil) ----- +=== Installation -=== Import/Export -- **SnapPy integration** – Import/export knots and links. -- **PD code support** – Read/write planar diagram codes. -- **KnotAtlas compatibility** – Fetch and work with KnotAtlas data. +==== From Julia REPL [source,julia] ---- -# Import from SnapPy -knot = import_snappy("3_1") - -# Export to PD code -pd_code = export_pd(trefoil) +using Pkg +Pkg.add("KnotTheory") ---- -== Quick Start +==== From Git (Development) -=== Installation [source,julia] ---- using Pkg -Pkg.add("KnotTheory") +Pkg.add(url="https://github.com/hyperpolymath/KnotTheory.jl") ---- -=== Hello World +=== Quick Start + [source,julia] ---- using KnotTheory -# Create a figure-eight knot -figure_eight = Knot([1, -2, 3, -4, 2, -1, 4, -3]) - -# Compute its Jones polynomial -jones_poly = jones_polynomial(figure_eight) - -# Plot the knot -plot(figure_eight) +k = trefoil() +println(crossing_number(k)) # 3 +println(alexander_polynomial(k)) # t^-1 - 1 + t +println(jones_polynomial(k)) # -t^-4 + t^-3 + t^-1 ---- -== Why KnotTheory.jl? - -=== The Problem -Knot theory research often involves: -- Manual diagram manipulation -- Error-prone invariant calculations -- Incompatible file formats between tools - -=== The Solution -KnotTheory.jl provides: -- **Automated diagram manipulation** – Reduce manual errors. -- **Verified invariants** – Trust your calculations. -- **Interoperability** – Work with existing tools and datasets. - -| Task | Traditional Tools | KnotTheory.jl | -|---------------------|-------------------|-----------------------| -| Diagram manipulation| Manual | Programmatic | -| Invariant calculation| Error-prone | Verified | -| Data exchange | Cumbersome | Seamless | - -== Project Structure -[source] +=== Features + +* *Planar diagram model* with oriented crossings and multi-component +links. +* *Code representations*: PD code, DT/Dowker code, JSON serialization. +* *Classical invariants*: crossing number, writhe, linking number, +signature, determinant. +* *Polynomial invariants*: Alexander, Jones, Conway, and HOMFLY-PT. +* *Seifert theory*: Seifert circles, Seifert matrix, braid index +estimate. +* *Reidemeister simplification*: R1, R2, R3 moves and combined +simplifier. +* *Braid word interop*: convert between planar diagrams and braid words +(TANGLE compatibility). +* *Knot table*: built-in catalogue with named knots up to standard +tables. +* *Graph conversion*: Graphs.jl integration via `+to_graph+`. +* *Polynomial helpers*: Polynomials.jl conversion via `+to_polynomial+`. +* *Optional plotting*: CairoMakie-based diagram rendering via package +extension. + +=== API Reference + +==== Types + +[cols=",",options="header",] +|=== +|Type |Description +|`+EdgeOrientation+` |Enum for edge direction (`+Over+`, `+Under+`) +|`+Crossing+` |Single crossing with strand indices and orientation +|`+PlanarDiagram+` |Full planar diagram with crossings and components +|`+DTCode+` |Dowker-Thistlethwaite code representation +|`+Knot+` |Named knot wrapper (e.g. `+trefoil()+`) +|`+Link+` |Named link wrapper for multi-component objects +|=== + +==== Constructors + +[width="100%",cols="44%,56%",options="header",] +|=== +|Function |Description +|`+unknot()+` |The unknot (zero crossings) +|`+trefoil()+` |Trefoil knot (3_1) +|`+figure_eight()+` |Figure-eight knot (4_1) +|`+cinquefoil()+` |Cinquefoil knot (5_1) +|`+knot_table(name)+` |Look up knot by standard name +|`+lookup_knot(property, value)+` |Search knot table by invariant value +|=== + +==== Classical Invariants + +[cols=",",options="header",] +|=== +|Function |Description +|`+crossing_number(k)+` |Minimum crossing number +|`+writhe(pd)+` |Sum of crossing signs +|`+linking_number(pd)+` |Linking number for two-component links +|`+signature(k)+` |Knot signature (from Seifert matrix) +|`+determinant(k)+` |Knot determinant (\|det(V + V^T)\|) +|=== + +==== Polynomial Invariants + +[width="100%",cols="44%,56%",options="header",] +|=== +|Function |Description +|`+alexander_polynomial(k)+` |Alexander polynomial via Seifert matrix + +|`+jones_polynomial(k)+` |Jones polynomial via skein relation + +|`+conway_polynomial(k)+` |Conway polynomial (substitution from +Alexander) + +|`+homfly_polynomial(k)+` |HOMFLY-PT two-variable polynomial +|=== + +==== Seifert Theory + +[width="100%",cols="44%,56%",options="header",] +|=== +|Function |Description +|`+seifert_circles(pd)+` |Seifert circle decomposition + +|`+seifert_circles_with_map(pd)+` |Seifert circles with strand-to-circle +mapping + +|`+seifert_matrix(pd)+` |Seifert matrix computation + +|`+braid_index_estimate(pd)+` |Lower bound on braid index from Seifert +circles +|=== + +==== Codes & Serialization + +[cols=",",options="header",] +|=== +|Function |Description +|`+pdcode(k)+` |Planar diagram code (list of crossing tuples) +|`+dtcode(k)+` |Dowker-Thistlethwaite code +|`+to_dowker(pd)+` |Convert planar diagram to Dowker notation +|`+write_knot_json(file, k)+` |Serialize knot data to JSON +|`+read_knot_json(file)+` |Deserialize knot data from JSON +|=== + +==== Simplification + +[cols=",",options="header",] +|=== +|Function |Description +|`+simplify_pd(pd)+` |Apply all Reidemeister moves until stable +|`+r1_simplify(pd)+` |Reidemeister I: remove kinks +|`+r2_simplify(pd)+` |Reidemeister II: cancel opposing crossings +|`+r3_simplify(pd)+` |Reidemeister III: triangle move +|=== + +==== Braid Words (TANGLE Interop) + +[cols=",",options="header",] +|=== +|Function |Description +|`+from_braid_word(word)+` |Construct planar diagram from braid word +|`+to_braid_word(pd)+` |Convert planar diagram to braid word +|=== + +==== Utilities + +[cols=",",options="header",] +|=== +|Function |Description +|`+to_graph(pd)+` |Convert to Graphs.jl graph structure +|`+to_polynomial(expr)+` |Convert to Polynomials.jl polynomial +|`+plot_pd(pd)+` |Render diagram (requires CairoMakie extension) +|=== + +=== Development + +[source,bash] ---- -KnotTheory.jl/ -├── src/ -│ ├── diagrams/ # Planar diagram tools -│ ├── invariants/ # Polynomial and homology calculations -│ ├── io/ # Import/export functionality -│ └── KnotTheory.jl # Main module -├── test/ # Test suite -├── examples/ # Example scripts -└── docs/ # Documentation +julia --project=. -e 'using Pkg; Pkg.instantiate()' +julia --project=. -e 'using Pkg; Pkg.test()' ---- -== Roadmap -- ✅ **v0.1** – Core diagram and invariant tools -- ❏ **v0.2** – Advanced homology and categorification -- ❏ **v0.3** – Integration with SnapPy and KnotAtlas -- ❏ **v1.0** – Full verification suite - -== Acknowledgments -KnotTheory.jl builds on the work of: -- *KnotAtlas* for knot data -- *SnapPy* for 3D visualization -- *Julia* for high-performance numerical computing +285 tests across 25 test sets covering all exported functions, invariant +consistency, and known values from knot tables. + +=== Docs & Tutorials + +* `+docs/README.md+` for documentation drafts. +* `+tutorials/intro.ipynb+` for a minimal notebook scaffold. + +=== References & Bibliography + +==== Textbooks + +* Adams, C.C. _The Knot Book: An Elementary Introduction to the +Mathematical Theory of Knots_. American Mathematical Society, 2004. — +Accessible introduction to knot theory. +* Lickorish, W.B.R. _An Introduction to Knot Theory_. Graduate Texts in +Mathematics 175, Springer, 1997. — Graduate-level treatment of knot +invariants. +* Rolfsen, D. _Knots and Links_. AMS Chelsea Publishing, 1976/2003. — +Classic reference for knot tables and enumeration. +* Murasugi, K. _Knot Theory and Its Applications_. Birkhauser, 1996. — +Applied knot theory with connections to biology and chemistry. +* Kauffman, L.H. _Knots and Physics_. 3rd ed., World Scientific, 2001. — +Jones polynomial, bracket polynomial, and physical applications. +* Cromwell, P.R. _Knots and Links_. Cambridge University Press, 2004. — +Modern computational approach to knot theory. + +==== Key Papers + +* Fox, R.H. "`Free differential calculus. I: Derivation in the free +group ring.`" _Annals of Mathematics_ 57(3), 1953, pp. 547-560. — Fox +calculus underlying Alexander polynomial computation. +* Freyd, P., Yetter, D., Hoste, J., Lickorish, W.B.R., Millett, K., & +Ocneanu, A. "`A new polynomial invariant of knots and links.`" _Bulletin +of the AMS_ 12(2), 1985, pp. 239-246. — HOMFLY-PT polynomial. +* Seifert, H. "`Uber das Geschlecht von Knoten.`" _Mathematische +Annalen_ 110, 1935, pp. 571-592. — Seifert surfaces and matrix +construction. +* Jones, V.F.R. "`A polynomial invariant for knots via von Neumann +algebras.`" _Bulletin of the AMS_ 12(1), 1985, pp. 103-111. — Jones +polynomial. + +=== License + +Palimpsest-MPL License v1.0 (MPL-2.0) – see LICENSE. diff --git a/packages/KnotTheory.jl/README.md b/packages/KnotTheory.jl/README.md deleted file mode 100644 index 2c2a74120..000000000 --- a/packages/KnotTheory.jl/README.md +++ /dev/null @@ -1,171 +0,0 @@ -# KnotTheory.jl - -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-95%25-green)](TOPOLOGY.md) -[![License](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](LICENSE) - -A comprehensive Julia toolkit for computational knot theory: planar diagram -data structures, classical invariants, polynomial invariants, Seifert theory, -Reidemeister simplification, braid word interop, and import/export helpers. - -## Installation - -### From Julia REPL -```julia -using Pkg -Pkg.add("KnotTheory") -``` - -### From Git (Development) -```julia -using Pkg -Pkg.add(url="https://github.com/hyperpolymath/KnotTheory.jl") -``` - -## Quick Start - -```julia -using KnotTheory - -k = trefoil() -println(crossing_number(k)) # 3 -println(alexander_polynomial(k)) # t^-1 - 1 + t -println(jones_polynomial(k)) # -t^-4 + t^-3 + t^-1 -``` - -## Features - -- **Planar diagram model** with oriented crossings and multi-component links. -- **Code representations**: PD code, DT/Dowker code, JSON serialization. -- **Classical invariants**: crossing number, writhe, linking number, signature, determinant. -- **Polynomial invariants**: Alexander, Jones, Conway, and HOMFLY-PT. -- **Seifert theory**: Seifert circles, Seifert matrix, braid index estimate. -- **Reidemeister simplification**: R1, R2, R3 moves and combined simplifier. -- **Braid word interop**: convert between planar diagrams and braid words (TANGLE compatibility). -- **Knot table**: built-in catalogue with named knots up to standard tables. -- **Graph conversion**: Graphs.jl integration via `to_graph`. -- **Polynomial helpers**: Polynomials.jl conversion via `to_polynomial`. -- **Optional plotting**: CairoMakie-based diagram rendering via package extension. - -## API Reference - -### Types - -| Type | Description | -|------|-------------| -| `EdgeOrientation` | Enum for edge direction (`Over`, `Under`) | -| `Crossing` | Single crossing with strand indices and orientation | -| `PlanarDiagram` | Full planar diagram with crossings and components | -| `DTCode` | Dowker-Thistlethwaite code representation | -| `Knot` | Named knot wrapper (e.g. `trefoil()`) | -| `Link` | Named link wrapper for multi-component objects | - -### Constructors - -| Function | Description | -|----------|-------------| -| `unknot()` | The unknot (zero crossings) | -| `trefoil()` | Trefoil knot (3_1) | -| `figure_eight()` | Figure-eight knot (4_1) | -| `cinquefoil()` | Cinquefoil knot (5_1) | -| `knot_table(name)` | Look up knot by standard name | -| `lookup_knot(property, value)` | Search knot table by invariant value | - -### Classical Invariants - -| Function | Description | -|----------|-------------| -| `crossing_number(k)` | Minimum crossing number | -| `writhe(pd)` | Sum of crossing signs | -| `linking_number(pd)` | Linking number for two-component links | -| `signature(k)` | Knot signature (from Seifert matrix) | -| `determinant(k)` | Knot determinant (\|det(V + V^T)\|) | - -### Polynomial Invariants - -| Function | Description | -|----------|-------------| -| `alexander_polynomial(k)` | Alexander polynomial via Seifert matrix | -| `jones_polynomial(k)` | Jones polynomial via skein relation | -| `conway_polynomial(k)` | Conway polynomial (substitution from Alexander) | -| `homfly_polynomial(k)` | HOMFLY-PT two-variable polynomial | - -### Seifert Theory - -| Function | Description | -|----------|-------------| -| `seifert_circles(pd)` | Seifert circle decomposition | -| `seifert_circles_with_map(pd)` | Seifert circles with strand-to-circle mapping | -| `seifert_matrix(pd)` | Seifert matrix computation | -| `braid_index_estimate(pd)` | Lower bound on braid index from Seifert circles | - -### Codes & Serialization - -| Function | Description | -|----------|-------------| -| `pdcode(k)` | Planar diagram code (list of crossing tuples) | -| `dtcode(k)` | Dowker-Thistlethwaite code | -| `to_dowker(pd)` | Convert planar diagram to Dowker notation | -| `write_knot_json(file, k)` | Serialize knot data to JSON | -| `read_knot_json(file)` | Deserialize knot data from JSON | - -### Simplification - -| Function | Description | -|----------|-------------| -| `simplify_pd(pd)` | Apply all Reidemeister moves until stable | -| `r1_simplify(pd)` | Reidemeister I: remove kinks | -| `r2_simplify(pd)` | Reidemeister II: cancel opposing crossings | -| `r3_simplify(pd)` | Reidemeister III: triangle move | - -### Braid Words (TANGLE Interop) - -| Function | Description | -|----------|-------------| -| `from_braid_word(word)` | Construct planar diagram from braid word | -| `to_braid_word(pd)` | Convert planar diagram to braid word | - -### Utilities - -| Function | Description | -|----------|-------------| -| `to_graph(pd)` | Convert to Graphs.jl graph structure | -| `to_polynomial(expr)` | Convert to Polynomials.jl polynomial | -| `plot_pd(pd)` | Render diagram (requires CairoMakie extension) | - -## Development - -```bash -julia --project=. -e 'using Pkg; Pkg.instantiate()' -julia --project=. -e 'using Pkg; Pkg.test()' -``` - -285 tests across 25 test sets covering all exported functions, invariant -consistency, and known values from knot tables. - -## Docs & Tutorials - -- `docs/README.md` for documentation drafts. -- `tutorials/intro.ipynb` for a minimal notebook scaffold. - -## References & Bibliography - -### Textbooks - -- Adams, C.C. _The Knot Book: An Elementary Introduction to the Mathematical Theory of Knots_. American Mathematical Society, 2004. — Accessible introduction to knot theory. -- Lickorish, W.B.R. _An Introduction to Knot Theory_. Graduate Texts in Mathematics 175, Springer, 1997. — Graduate-level treatment of knot invariants. -- Rolfsen, D. _Knots and Links_. AMS Chelsea Publishing, 1976/2003. — Classic reference for knot tables and enumeration. -- Murasugi, K. _Knot Theory and Its Applications_. Birkhauser, 1996. — Applied knot theory with connections to biology and chemistry. -- Kauffman, L.H. _Knots and Physics_. 3rd ed., World Scientific, 2001. — Jones polynomial, bracket polynomial, and physical applications. -- Cromwell, P.R. _Knots and Links_. Cambridge University Press, 2004. — Modern computational approach to knot theory. - -### Key Papers - -- Fox, R.H. "Free differential calculus. I: Derivation in the free group ring." _Annals of Mathematics_ 57(3), 1953, pp. 547-560. — Fox calculus underlying Alexander polynomial computation. -- Freyd, P., Yetter, D., Hoste, J., Lickorish, W.B.R., Millett, K., & Ocneanu, A. "A new polynomial invariant of knots and links." _Bulletin of the AMS_ 12(2), 1985, pp. 239-246. — HOMFLY-PT polynomial. -- Seifert, H. "Uber das Geschlecht von Knoten." _Mathematische Annalen_ 110, 1935, pp. 571-592. — Seifert surfaces and matrix construction. -- Jones, V.F.R. "A polynomial invariant for knots via von Neumann algebras." _Bulletin of the AMS_ 12(1), 1985, pp. 103-111. — Jones polynomial. - -## License - -Palimpsest-MPL License v1.0 (MPL-2.0) -- see [LICENSE](LICENSE). diff --git a/packages/KnotTheory.jl/ROADMAP.adoc b/packages/KnotTheory.jl/ROADMAP.adoc index 6cf5a10dd..b415c4b82 100644 --- a/packages/KnotTheory.jl/ROADMAP.adoc +++ b/packages/KnotTheory.jl/ROADMAP.adoc @@ -1,18 +1,157 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Roadmap -:revdate: 2026-02-17 - -== Release Baseline (Must) -- Package installs from a clean Julia environment (`Pkg.add`). -- Precompile, build, test, and module load smoke are gated in CI. -- Versioning stays semver and aligned with release refs/tags. - -== V2 Backlog (Should) -- Expand CI matrix (OS + Julia versions + optional dependency modes). -- Add performance baselines and regression checks. -- Improve machine-readable evidence and release artifact metadata. - -== V2 Backlog (Could) -- Add deeper formal verification evidence exports. -- Add optional accelerator/hardware strategy tracks where relevant. -- Add richer diagnostics and fault-recovery instrumentation. +== KnotTheory.jl Development Roadmap + +=== Current State (v0.1.0) + +Early development knot theory toolkit: - Planar diagram (PD) and +Dowker-Thistlethwaite (DT) codes - Basic invariants (crossing number, +writhe, linking number) - Polynomial invariants (Alexander placeholder, +Jones via Kauffman bracket) - Seifert circles and braid index estimation +- Reidemeister I simplification - JSON import/export - Optional +CairoMakie plotting (package extension) + +*Status:* Core functionality implemented with security hardening +(recursion limits, bounds checks). Alexander polynomial is a placeholder +requiring proper implementation. + +''''' + +=== v0.1.0 → v0.2.0 Roadmap (Near-term) + +==== v1.1 - Core Invariants & Performance (3-6 months) + +*MUST:* - [ ] *HOMFLY-PT polynomial* - Two-variable polynomial invariant +(more powerful than Jones) - [ ] *Khovanov homology* - Categorification +of Jones polynomial (computational challenge) - [ ] *Knot table +integration* - Import Rolfsen, HTW tables (10K+ knots up to 16 +crossings) - [ ] *Performance optimization* - Memoization, sparse +matrices, parallel Jones computation + +*SHOULD:* - [ ] *Reidemeister II & III* - Complete Reidemeister move +toolkit for diagram simplification - [ ] *Knot signatures* - +Levine-Tristram, Casson-Gordon signatures - [ ] *3-coloring detection* - +Fox n-colorings for knot diagrams - [ ] *Conway notation* - Parser for +Conway’s algebraic knot notation + +*COULD:* - [ ] *Interactive knot editor* - Makie.jl drag-and-drop +diagram manipulation - [ ] *Knot recognition* - Identify knots from +diagrams (compare against database) - [ ] *Braid word operations* - +Braid group arithmetic, Garside normal form + +==== v1.2 - Advanced Topology & Integration (6-12 months) + +*MUST:* - [ ] *Link invariants* - Linking matrix, Milnor invariants for +multi-component links - [ ] *Turaev genus* - Surface complexity measure +for knots - [ ] *Hyperbolic volume* - Compute from ideal triangulation +(SnapPy integration?) - [ ] *Knot Floer homology* - Modern +categorification (simplified combinatorial version) + +*SHOULD:* - [ ] *Virtual knots* - Extend to virtual knot theory +(Kauffman’s generalization) - [ ] *Knot cobordism* - Slice genus, +concordance invariants - [ ] *Integration with Graphs.jl* - Leverage +graph algorithms for knot properties - [ ] *3D knot visualization* - +Makie.jl 3D tube rendering of knots + +*COULD:* - [ ] *Knot energy* - Compute M�bius energy, rope-length for +knot optimization - [ ] *Random knot generation* - Sample from uniform +distribution on n-crossing knots - [ ] *Knot DNA analysis* - Apply to +DNA topology problems (supercoiling, catenanes) + +''''' + +=== v1.3+ Roadmap (Speculative) + +==== Research Frontiers + +*Computational Knot Theory:* - Quantum knot invariants +(Reshetikhin-Turaev, Witten-Chern-Simons) - Machine learning knot +recognition (neural networks trained on diagrams) - Knot diagrammatic +algebra (automated proof discovery) - GPU-accelerated polynomial +computation (CUDA.jl for large crossing numbers) + +*Higher-Dimensional Topology:* - 4-manifold invariants (Donaldson, +Seiberg-Witten) - Knot concordance (smooth vs. topological slice genus) +- Exotic 4-manifolds (Freedman-Quinn theory) - Categorification +landscape (spectral sequences, derived categories) + +*Formal Verification:* - Coq/Lean formalization of knot invariants +(certified Jones polynomial) - Integration with Axiom.jl for verified +topology theorems - Proof-producing knot equivalence (Reidemeister move +certificates) + +*Applications:* - *Molecular biology:* DNA/RNA topology (knotted +proteins, chromatin structure) - *Quantum computing:* Topological +quantum field theory, anyons, braiding - *Material science:* Knotted +polymers, entangled liquids - *Cryptography:* Topological codes, +knot-based authentication + +==== Ecosystem Integration + +* *Symbolics.jl:* Symbolic polynomial manipulation (HOMFLY-PT, Kauffman) +* *DifferentialEquations.jl:* Knot flow equations (gradient descent on +energy) +* *Makie.jl:* Advanced 3D visualization (VR knot exploration) +* *DataFrames.jl:* Large knot database queries and analysis + +==== Ambitious Features + +* *Knot foundation model* - Pre-trained on all known knots (100K+ +diagrams) +* *Automated knot theorem prover* - AI that discovers and proves new +invariant relationships +* *Virtual knot laboratory* - Interactive platform for knot manipulation +and discovery +* *Global knot census* - Distributed computation of all knots up to 20+ +crossings + +''''' + +=== Future Horizons (v2.0+) + +==== Topological Quantum Computing (TQC) + +* [ ] *Braid Circuit Simulator*: Map braid words to quantum gate +operations using the Jones representation of the braid group. +* [ ] *Anyon Braiding Emulator*: Simulate the non-Abelian statistics of +anyons in topological phases of matter. + +==== Molecular & Synthetic Biology + +* [ ] *DNA/Protein Entanglement Prediction*: Use knot energy models to +predict the probability of self-entanglement in long-chain synthetic +polymers and DNA strands. +* [ ] *Enzymatic Action Modeling*: Model how topoisomerases "`cut`" and +"`paste`" knots in biological systems using formal diagrammatic rules. + +==== Topological Cryptography + +* [ ] *Knot-Based PKI Prototypes*: Implement post-quantum cryptographic +primitives where the security is based on the hardness of the "`Knot +Recognition`" or "`Markov Problem`" for braids. +* [ ] *Topological Zero-Knowledge Proofs*: Protocols for proving +knowledge of a knot simplification without revealing the sequence of +Reidemeister moves. + +==== Axiomatic Topology + +* [ ] *Invariant Correctness Proofs*: Link with `+Axiom.jl+` to formally +prove that the implemented polynomial invariants are invariant under all +three Reidemeister moves. +* [ ] *Formalized Knot Tables*: A verified database of knots where every +invariant value is accompanied by a machine-readable proof of +correctness. + +''''' + +=== Migration Path + +*v1.0 → v1.1:* Backward compatible (new invariants and performance +improvements) *v1.1 → v1.2:* Mostly compatible (virtual knots may +require new data structures) *v1.2 → v1.3+:* Breaking changes likely +(higher-dimensional topology needs fundamental redesign) + +=== Community Goals + +* *Adoption by knot theorists* (Kauffman, Lickorish, Przytycki) by v1.2 +* *Publication in Journal of Knot Theory* by v1.2 +* *Integration with KnotInfo database* by v1.2 +* *Tutorial at Knots in Washington conference* by v1.2 diff --git a/packages/KnotTheory.jl/ROADMAP.md b/packages/KnotTheory.jl/ROADMAP.md deleted file mode 100644 index 19cee96ca..000000000 --- a/packages/KnotTheory.jl/ROADMAP.md +++ /dev/null @@ -1,134 +0,0 @@ -# KnotTheory.jl Development Roadmap - -## Current State (v0.1.0) - -Early development knot theory toolkit: -- Planar diagram (PD) and Dowker-Thistlethwaite (DT) codes -- Basic invariants (crossing number, writhe, linking number) -- Polynomial invariants (Alexander placeholder, Jones via Kauffman bracket) -- Seifert circles and braid index estimation -- Reidemeister I simplification -- JSON import/export -- Optional CairoMakie plotting (package extension) - -**Status:** Core functionality implemented with security hardening (recursion limits, bounds checks). Alexander polynomial is a placeholder requiring proper implementation. - ---- - -## v0.1.0 → v0.2.0 Roadmap (Near-term) - -### v1.1 - Core Invariants & Performance (3-6 months) - -**MUST:** -- [ ] **HOMFLY-PT polynomial** - Two-variable polynomial invariant (more powerful than Jones) -- [ ] **Khovanov homology** - Categorification of Jones polynomial (computational challenge) -- [ ] **Knot table integration** - Import Rolfsen, HTW tables (10K+ knots up to 16 crossings) -- [ ] **Performance optimization** - Memoization, sparse matrices, parallel Jones computation - -**SHOULD:** -- [ ] **Reidemeister II & III** - Complete Reidemeister move toolkit for diagram simplification -- [ ] **Knot signatures** - Levine-Tristram, Casson-Gordon signatures -- [ ] **3-coloring detection** - Fox n-colorings for knot diagrams -- [ ] **Conway notation** - Parser for Conway's algebraic knot notation - -**COULD:** -- [ ] **Interactive knot editor** - Makie.jl drag-and-drop diagram manipulation -- [ ] **Knot recognition** - Identify knots from diagrams (compare against database) -- [ ] **Braid word operations** - Braid group arithmetic, Garside normal form - -### v1.2 - Advanced Topology & Integration (6-12 months) - -**MUST:** -- [ ] **Link invariants** - Linking matrix, Milnor invariants for multi-component links -- [ ] **Turaev genus** - Surface complexity measure for knots -- [ ] **Hyperbolic volume** - Compute from ideal triangulation (SnapPy integration?) -- [ ] **Knot Floer homology** - Modern categorification (simplified combinatorial version) - -**SHOULD:** -- [ ] **Virtual knots** - Extend to virtual knot theory (Kauffman's generalization) -- [ ] **Knot cobordism** - Slice genus, concordance invariants -- [ ] **Integration with Graphs.jl** - Leverage graph algorithms for knot properties -- [ ] **3D knot visualization** - Makie.jl 3D tube rendering of knots - -**COULD:** -- [ ] **Knot energy** - Compute M�bius energy, rope-length for knot optimization -- [ ] **Random knot generation** - Sample from uniform distribution on n-crossing knots -- [ ] **Knot DNA analysis** - Apply to DNA topology problems (supercoiling, catenanes) - ---- - -## v1.3+ Roadmap (Speculative) - -### Research Frontiers - -**Computational Knot Theory:** -- Quantum knot invariants (Reshetikhin-Turaev, Witten-Chern-Simons) -- Machine learning knot recognition (neural networks trained on diagrams) -- Knot diagrammatic algebra (automated proof discovery) -- GPU-accelerated polynomial computation (CUDA.jl for large crossing numbers) - -**Higher-Dimensional Topology:** -- 4-manifold invariants (Donaldson, Seiberg-Witten) -- Knot concordance (smooth vs. topological slice genus) -- Exotic 4-manifolds (Freedman-Quinn theory) -- Categorification landscape (spectral sequences, derived categories) - -**Formal Verification:** -- Coq/Lean formalization of knot invariants (certified Jones polynomial) -- Integration with Axiom.jl for verified topology theorems -- Proof-producing knot equivalence (Reidemeister move certificates) - -**Applications:** -- **Molecular biology:** DNA/RNA topology (knotted proteins, chromatin structure) -- **Quantum computing:** Topological quantum field theory, anyons, braiding -- **Material science:** Knotted polymers, entangled liquids -- **Cryptography:** Topological codes, knot-based authentication - -### Ecosystem Integration - -- **Symbolics.jl:** Symbolic polynomial manipulation (HOMFLY-PT, Kauffman) -- **DifferentialEquations.jl:** Knot flow equations (gradient descent on energy) -- **Makie.jl:** Advanced 3D visualization (VR knot exploration) -- **DataFrames.jl:** Large knot database queries and analysis - -### Ambitious Features - -- **Knot foundation model** - Pre-trained on all known knots (100K+ diagrams) -- **Automated knot theorem prover** - AI that discovers and proves new invariant relationships -- **Virtual knot laboratory** - Interactive platform for knot manipulation and discovery -- **Global knot census** - Distributed computation of all knots up to 20+ crossings - ---- - -## Future Horizons (v2.0+) - -### Topological Quantum Computing (TQC) -- [ ] **Braid Circuit Simulator**: Map braid words to quantum gate operations using the Jones representation of the braid group. -- [ ] **Anyon Braiding Emulator**: Simulate the non-Abelian statistics of anyons in topological phases of matter. - -### Molecular & Synthetic Biology -- [ ] **DNA/Protein Entanglement Prediction**: Use knot energy models to predict the probability of self-entanglement in long-chain synthetic polymers and DNA strands. -- [ ] **Enzymatic Action Modeling**: Model how topoisomerases "cut" and "paste" knots in biological systems using formal diagrammatic rules. - -### Topological Cryptography -- [ ] **Knot-Based PKI Prototypes**: Implement post-quantum cryptographic primitives where the security is based on the hardness of the "Knot Recognition" or "Markov Problem" for braids. -- [ ] **Topological Zero-Knowledge Proofs**: Protocols for proving knowledge of a knot simplification without revealing the sequence of Reidemeister moves. - -### Axiomatic Topology -- [ ] **Invariant Correctness Proofs**: Link with `Axiom.jl` to formally prove that the implemented polynomial invariants are invariant under all three Reidemeister moves. -- [ ] **Formalized Knot Tables**: A verified database of knots where every invariant value is accompanied by a machine-readable proof of correctness. - ---- - -## Migration Path - -**v1.0 → v1.1:** Backward compatible (new invariants and performance improvements) -**v1.1 → v1.2:** Mostly compatible (virtual knots may require new data structures) -**v1.2 → v1.3+:** Breaking changes likely (higher-dimensional topology needs fundamental redesign) - -## Community Goals - -- **Adoption by knot theorists** (Kauffman, Lickorish, Przytycki) by v1.2 -- **Publication in Journal of Knot Theory** by v1.2 -- **Integration with KnotInfo database** by v1.2 -- **Tutorial at Knots in Washington conference** by v1.2 diff --git a/packages/KnotTheory.jl/SECURITY.adoc b/packages/KnotTheory.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/KnotTheory.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/KnotTheory.jl/SECURITY.md b/packages/KnotTheory.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/KnotTheory.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/KnotTheory.jl/SONNET-TASKS.adoc b/packages/KnotTheory.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..27abb0136 --- /dev/null +++ b/packages/KnotTheory.jl/SONNET-TASKS.adoc @@ -0,0 +1,817 @@ +== SONNET-TASKS.md – KnotTheory.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 62% +____ + +The Julia knot-theory library (`+src/KnotTheory.jl+`) is a genuine, +working module with real data structures, invariants, and tests that +pass. However, there are significant issues: the Alexander polynomial is +a self-described "`placeholder`" that produces wrong results, the +`+to_polynomial+` helper crashes on negative exponents (which +`+jones_polynomial+` routinely produces), several RSR template files +still have unreplaced `+{{PLACEHOLDER}}+` markers, SPDX headers use the +banned `+AGPL-3.0-or-later+` in multiple files, the +`+.machine_readable/+` directory is entirely missing, the `+examples/+` +directory contains files irrelevant to knot theory (a ReScript SafeDOM +example and a Deno JSON config), the version in `+Project.toml+` (1.0.0) +contradicts `+Manifest.toml+` (0.1.0), and three Idris2 proofs are holes +(`+?+`-prefixed). + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update STATE.scm with honest completion percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks: +`+cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e 'using Pkg; Pkg.test()'+` + +''''' + +=== TASK 1: Fix `+to_polynomial+` crash on negative exponents (CRITICAL) + +*Problem:* `+jones_polynomial+` returns a `+Dict{Int,Int}+` where keys +are often negative (e.g., `+Dict(-5 => 1, -3 => -1, -1 => 1)+`). The +`+to_polynomial+` function at line 442-452 of `+src/KnotTheory.jl+` +computes `+max_exp + 1+` and builds a `+coeffs+` array indexed +`+exp + 1+`. When `+exp+` is negative, this produces an out-of-bounds +index. This means Jones polynomial results cannot be converted to +`+Polynomials.Polynomial+` objects. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl+`, lines +442-452 + +*Fix:* Rewrite `+to_polynomial+` to handle negative exponents by using +`+min_exp+` as an offset. Shift all exponents so the lowest becomes +index 1. The resulting `+Polynomial+` should carry correct coefficients; +callers can interpret the minimum exponent separately. + +*Exact function to replace:* + +[source,julia] +---- +function to_polynomial(dict::Dict{Int, Int}) + if isempty(dict) + return Polynomial([0]) + end + max_exp = maximum(collect(keys(dict))) + coeffs = zeros(Int, max_exp + 1) + for (exp, coeff) in dict + coeffs[exp + 1] = coeff + end + Polynomial(coeffs) +end +---- + +*Replace with a version that:* 1. Computes +`+min_exp = minimum(keys(dict))+` and `+max_exp = maximum(keys(dict))+`. +2. Allocates `+coeffs+` of length `+max_exp - min_exp + 1+`. 3. Uses +`+coeffs[exp - min_exp + 1] = coeff+` for placement. 4. Returns a tuple +`+(Polynomial(coeffs), min_exp)+` so the caller knows the leading +exponent offset. Alternatively, keep the return type as just +`+Polynomial+` but document that the variable represents +`+t^min_exp * poly(t)+`. Choose the tuple approach since it is +unambiguous. 5. Update the export list and docstring accordingly. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using KnotTheory +pd = KnotTheory.pdcode([(1,2,3,4,1)]) +j = KnotTheory.jones_polynomial(pd; wr=1) +println("Jones dict: ", j) +poly, offset = KnotTheory.to_polynomial(j) +println("Polynomial: ", poly, " with offset t^", offset) +@assert poly isa KnotTheory.Polynomials.Polynomial +println("PASS: to_polynomial handles negative exponents") +' +---- + +''''' + +=== TASK 2: Fix the Alexander polynomial placeholder (HIGH) + +*Problem:* The `+alexander_polynomial+` function at lines 263-306 of +`+src/KnotTheory.jl+` is explicitly marked as a "`crude expansion`" and +a "`placeholder`". It builds a Seifert matrix `+V+` using +`+(a % n) + 1+` and `+(c % n) + 1+` as indices, which is mathematically +unjustified. It then evaluates `+det(V)+` and `+det(V - V')+` as an +approximation. This does not compute the actual Alexander polynomial for +any non-trivial knot. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl+`, lines +263-306 + +*Fix:* Implement a correct Alexander polynomial computation. The +standard approach for a planar diagram: + +[arabic] +. Build the actual Seifert matrix from the Seifert surface: for each +pair of Seifert circles (i, j), compute the linking number contribution +from each crossing that connects circles i and j. +. Compute `+det(V - t * V')+` as a polynomial in `+t+` using the +`+Polynomials+` package directly. The matrix `+V - t * V'+` is a matrix +of `+Polynomial+` entries; take its determinant symbolically. +. For small matrices (say n <= 10), a cofactor expansion or Bareiss-like +algorithm over polynomials works. For the scope of this library (up to +20 crossings), this is adequate. +. Normalize the result so the polynomial is symmetric and evaluates to 1 +at t=1 (standard normalization). +. Return a `+Dict{Int,Int}+` mapping exponent to coefficient, consistent +with the existing API. + +*Keep the signature:* +`+alexander_polynomial(pd::PlanarDiagram) -> Dict{Int,Int}+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using KnotTheory +# Trefoil knot PD code: standard positive trefoil +# PD notation: X[1,4,2,5], X[3,6,4,1], X[5,2,6,3] with all positive crossings +pd = KnotTheory.pdcode([ + (1, 4, 2, 5, 1), + (3, 6, 4, 1, 1), + (5, 2, 6, 3, 1) +]) +alex = KnotTheory.alexander_polynomial(pd) +println("Alexander poly of trefoil: ", alex) +# The Alexander polynomial of the trefoil is t^-1 - 1 + t (up to normalization) +# Verify it is non-trivial (not just {0 => 1}) +@assert length(alex) > 1 || (length(alex) == 1 && !haskey(alex, 0)) +println("PASS: Alexander polynomial is non-trivial for trefoil") +' +---- + +''''' + +=== TASK 3: Fix version mismatch between Project.toml and Manifest.toml (HIGH) + +*Problem:* `+Project.toml+` line 4 says `+version = "1.0.0"+` but +`+Manifest.toml+` line 101 says `+version = "0.1.0"+`. The README.md and +ROADMAP.md refer to this as "`v1.0`" and "`Production-ready`". This is +an early-stage library with placeholder algorithms; it is not v1.0. + +*Files:* - `+/var$REPOS_DIR/KnotTheory.jl/Project.toml+`, line 4 - +`+/var$REPOS_DIR/KnotTheory.jl/ROADMAP.md+`, line 3 and line 14 + +*Fix:* 1. Change `+Project.toml+` version to `+"0.1.0"+`. 2. Update +`+ROADMAP.md+` to say "`v0.1.0`" / "`Current State (v0.1.0)`" and remove +the claim "`Production-ready`" (replace with "`Early development`"). 3. +Regenerate `+Manifest.toml+` by running +`+julia --project=. -e 'using Pkg; Pkg.resolve()'+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using Pkg +ctx = Pkg.Types.Context() +proj = ctx.env.project +println("Project version: ", proj.version) +@assert string(proj.version) == "0.1.0" "Version should be 0.1.0, got $(proj.version)" +println("PASS: version is 0.1.0") +' +---- + +''''' + +=== TASK 4: Fix SPDX license headers – replace AGPL-3.0-or-later with MPL-2.0 (HIGH) + +*Problem:* Five files use the banned `+AGPL-3.0-or-later+` SPDX +identifier: 1. `+/var$REPOS_DIR/KnotTheory.jl/ffi/zig/build.zig+` (line +2) 2. `+/var$REPOS_DIR/KnotTheory.jl/ffi/zig/src/main.zig+` (line 6) 3. +`+/var$REPOS_DIR/KnotTheory.jl/ffi/zig/test/integration_test.zig+` (line +2) 4. `+/var$REPOS_DIR/KnotTheory.jl/examples/SafeDOMExample.res+` (line +1) 5. `+/var$REPOS_DIR/KnotTheory.jl/docs/CITATIONS.adoc+` (line 13, in +BibTeX block) + +Per CLAUDE.md: "`NEVER use AGPL-3.0`". + +*Fix:* In each file, replace `+AGPL-3.0-or-later+` with `+MPL-2.0+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + ! grep -r "AGPL" --include="*.zig" --include="*.res" --include="*.adoc" . && \ + echo "PASS: No AGPL references remain" +---- + +''''' + +=== TASK 5: Replace all unreplaced `+{{PLACEHOLDER}}+` template markers (HIGH) + +*Problem:* Ten files still contain unreplaced `+{{PROJECT}}+`, +`+{{project}}+`, `+{{OWNER}}+`, `+{{REPO}}+`, `+{{FORGE}}+`, +`+{{SECURITY_EMAIL}}+`, `+{{PGP_FINGERPRINT}}+`, `+{{PGP_KEY_URL}}+`, +`+{{WEBSITE}}+`, `+{{CURRENT_YEAR}}+`, `+{{PROJECT_NAME}}+`, +`+{{CONDUCT_EMAIL}}+`, `+{{CONDUCT_TEAM}}+`, `+{{RESPONSE_TIME}}+`, +`+{{MAIN_BRANCH}}+`, and `+{{LICENSE}}+` markers from the RSR template. +These files are: + +[arabic] +. `+/var$REPOS_DIR/KnotTheory.jl/ffi/zig/build.zig+` – `+{{PROJECT}}+`, +`+{{project}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/ffi/zig/src/main.zig+` – +`+{{PROJECT}}+`, `+{{project}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/ffi/zig/test/integration_test.zig+` – +`+{{PROJECT}}+`, `+{{project}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/src/abi/Types.idr+` – `+{{PROJECT}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/src/abi/Layout.idr+` – `+{{PROJECT}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/src/abi/Foreign.idr+` – +`+{{PROJECT}}+`, `+{{project}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/ABI-FFI-README.md+` – `+{{PROJECT}}+`, +`+{{project}}+`, `+{{LICENSE}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/SECURITY.md+` – `+{{OWNER}}+`, +`+{{REPO}}+`, `+{{SECURITY_EMAIL}}+`, `+{{PGP_FINGERPRINT}}+`, +`+{{PGP_KEY_URL}}+`, `+{{WEBSITE}}+`, `+{{CURRENT_YEAR}}+`, +`+{{PROJECT_NAME}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/CODE_OF_CONDUCT.md+` – +`+{{PROJECT_NAME}}+`, `+{{OWNER}}+`, `+{{REPO}}+`, +`+{{CONDUCT_EMAIL}}+`, `+{{CONDUCT_TEAM}}+`, `+{{RESPONSE_TIME}}+`, +`+{{CURRENT_YEAR}}+`, `+{{FORGE}}+` +. `+/var$REPOS_DIR/KnotTheory.jl/CONTRIBUTING.md+` – `+{{FORGE}}+`, +`+{{OWNER}}+`, `+{{REPO}}+`, `+{{MAIN_BRANCH}}+` + +*Fix:* Replace with these values: - `+{{PROJECT}}+` -> `+KnotTheory+` - +`+{{project}}+` -> `+knottheory+` - `+{{OWNER}}+` -> `+hyperpolymath+` - +`+{{REPO}}+` -> `+KnotTheory.jl+` - `+{{FORGE}}+` -> `+github.com+` - +`+{{SECURITY_EMAIL}}+` -> `+jonathan.jewell@open.ac.uk+` - +`+{{PGP_FINGERPRINT}}+` -> (remove the PGP section or leave a note to +fill in) - `+{{PGP_KEY_URL}}+` -> (remove the PGP section or leave a +note to fill in) - `+{{WEBSITE}}+` -> +`+https://github.com/hyperpolymath+` - `+{{CURRENT_YEAR}}+` -> `+2026+` +- `+{{PROJECT_NAME}}+` -> `+KnotTheory.jl+` - `+{{CONDUCT_EMAIL}}+` -> +`+jonathan.jewell@open.ac.uk+` - `+{{CONDUCT_TEAM}}+` -> +`+KnotTheory.jl Maintainers+` - `+{{RESPONSE_TIME}}+` -> `+48 hours+` - +`+{{MAIN_BRANCH}}+` -> `+main+` - `+{{LICENSE}}+` -> `+MPL-2.0+` + +Also delete the HTML comment blocks that say "`TEMPLATE INSTRUCTIONS +(delete this block before publishing)`" from SECURITY.md (lines 3-19) +and CODE_OF_CONDUCT.md (lines 3-21). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + ! grep -r '{{' --include="*.md" --include="*.zig" --include="*.idr" --include="*.adoc" . && \ + echo "PASS: No template placeholders remain" +---- + +''''' + +=== TASK 6: Create `+.machine_readable/+` directory with STATE.scm, META.scm, ECOSYSTEM.scm (HIGH) + +*Problem:* The `+.machine_readable/+` directory is entirely absent. Per +CLAUDE.md, SCM files MUST be in `+.machine_readable/+` only, never in +root. There are no SCM files anywhere in the repo. + +*Fix:* Create the directory and populate three files: + +==== `+.machine_readable/STATE.scm+` + +[source,scheme] +---- +(define state + `((metadata + (project . "KnotTheory.jl") + (version . "0.1.0") + (updated . "2026-02-12")) + (project-context + (description . "Julia toolkit for knot theory: planar diagrams, invariants, polynomials") + (language . "Julia") + (category . "mathematics")) + (current-position + (phase . implementation) + (maturity . alpha) + (completion-percentage . 62)) + (route-to-mvp + (milestones + ((name . "correct-alexander") + (status . incomplete) + (description . "Replace Alexander polynomial placeholder with correct Seifert matrix algorithm")) + ((name . "homfly-pt") + (status . not-started) + (description . "Implement HOMFLY-PT two-variable polynomial")) + ((name . "knot-table") + (status . incomplete) + (description . "Expand knot table beyond 3 entries")) + ((name . "reidemeister-ii-iii") + (status . not-started) + (description . "Implement Reidemeister II and III moves")))) + (blockers-and-issues + ((blocker . "Alexander polynomial is a placeholder producing wrong results") + (severity . high)) + ((blocker . "to_polynomial crashes on negative exponents from Jones polynomial") + (severity . critical))) + (critical-next-actions + ("Fix to_polynomial negative exponent handling" + "Implement correct Alexander polynomial" + "Add Reidemeister II and III simplifications" + "Expand knot table with Rolfsen data")))) +---- + +==== `+.machine_readable/META.scm+` + +[source,scheme] +---- +(define meta + `((architecture-decisions + ((id . "ADR-001") + (title . "Dict-based polynomial representation") + (status . accepted) + (rationale . "Using Dict{Int,Int} for polynomial coefficients allows negative exponents and sparse representation")) + ((id . "ADR-002") + (title . "Kauffman bracket for Jones polynomial") + (status . accepted) + (rationale . "State-sum expansion is correct for small crossing numbers; limited to 20 crossings"))) + (development-practices + (testing . "julia --project=. -e 'using Pkg; Pkg.test()'") + (language . "Julia 1.9+") + (license . "MPL-2.0")))) +---- + +==== `+.machine_readable/ECOSYSTEM.scm+` + +[source,scheme] +---- +(define ecosystem + `((version . "1.0") + (name . "KnotTheory.jl") + (type . "julia-package") + (purpose . "Knot theory computations: planar diagrams, invariants, polynomial invariants") + (position-in-ecosystem . "standalone-library") + (related-projects + ((name . "Graphs.jl") + (relationship . dependency) + (description . "Used for graph representation of planar diagrams")) + ((name . "Polynomials.jl") + (relationship . dependency) + (description . "Used for polynomial arithmetic")) + ((name . "CairoMakie") + (relationship . optional-dependency) + (description . "Used for knot diagram plotting via package extension"))))) +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + test -f .machine_readable/STATE.scm && \ + test -f .machine_readable/META.scm && \ + test -f .machine_readable/ECOSYSTEM.scm && \ + echo "PASS: .machine_readable/ directory exists with all 3 SCM files" +---- + +''''' + +=== TASK 7: Remove irrelevant example files (MEDIUM) + +*Problem:* The `+examples/+` directory contains two files that have +nothing to do with knot theory: + +[arabic] +. `+examples/SafeDOMExample.res+` – A ReScript SafeDOM example from the +RSR template. Not relevant to a Julia knot theory library. +. `+examples/web-project-deno.json+` – A Deno project config for +ReScript web projects. Not relevant. + +*Fix:* 1. Delete `+examples/SafeDOMExample.res+`. 2. Delete +`+examples/web-project-deno.json+`. 3. Create +`+examples/basic_usage.jl+` with actual knot theory examples: + +[source,julia] +---- +# SPDX-License-Identifier: CC-BY-SA-4.0 +# Basic usage examples for KnotTheory.jl + +using KnotTheory + +# --- Create knots from the built-in table --- +k = trefoil() +println("Trefoil crossing number: ", crossing_number(k)) +println("Trefoil DT code: ", dtcode(k).code) + +fe = figure_eight() +println("Figure-eight crossing number: ", crossing_number(fe)) + +# --- Build a knot from PD code --- +# Single positive crossing +pd = pdcode([(1, 2, 3, 4, 1)]) +sample = Knot(:sample, pd, nothing) +println("Sample writhe: ", writhe(sample)) + +# --- Compute invariants --- +println("Seifert circles: ", seifert_circles(pd)) +println("Braid index estimate: ", braid_index_estimate(pd)) + +# --- Jones polynomial --- +jones = jones_polynomial(pd; wr=1) +println("Jones polynomial (dict): ", jones) + +# --- Simplification --- +# A crossing with repeated arcs (R1 reducible) +pd_loop = pdcode([(1, 1, 2, 2, 1)]) +reduced = r1_simplify(pd_loop) +println("Before R1: ", length(pd_loop.crossings), " crossings") +println("After R1: ", length(reduced.crossings), " crossings") + +# --- JSON round-trip --- +path = tempname() * ".json" +write_knot_json(path, sample) +loaded = read_knot_json(path) +println("Round-tripped knot name: ", loaded.name) +rm(path) + +# --- Graph conversion --- +using Graphs +g = to_graph(pd) +println("Graph vertices: ", nv(g), ", edges: ", ne(g)) + +# --- Knot table --- +table = knot_table() +for (name, entry) in table + println(" ", name, ": ", entry.crossings, " crossings") +end +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + test ! -f examples/SafeDOMExample.res && \ + test ! -f examples/web-project-deno.json && \ + test -f examples/basic_usage.jl && \ + julia --project=. examples/basic_usage.jl && \ + echo "PASS: examples/ contains only relevant knot theory examples and they run" +---- + +''''' + +=== TASK 8: Fix CITATIONS.adoc to reference KnotTheory.jl instead of RSR-template-repo (MEDIUM) + +*Problem:* `+/var$REPOS_DIR/KnotTheory.jl/docs/CITATIONS.adoc+` still +references `+rsr-template-repo+` everywhere and uses +`+AGPL-3.0-or-later+` for the license. It also attributes authorship to +`+Polymath, Hyper+` instead of the correct `+Jewell, Jonathan D.A.+`. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/docs/CITATIONS.adoc+` + +*Fix:* Replace all occurrences of: - `+rsr-template-repo+` -> +`+KnotTheory.jl+` - `+RSR-template-repo+` -> `+KnotTheory.jl+` - +`+Polymath, Hyper+` / `+Hyper Polymath+` -> `+Jewell, Jonathan D.A.+` / +`+Jonathan D.A. Jewell+` - `+AGPL-3.0-or-later+` -> `+MPL-2.0+` - +`+2025+` -> `+2026+` (year) - Fix the title line to say +`+= KnotTheory.jl - Citation Guide+` - Fix URLs to point to +`+https://github.com/hyperpolymath/KnotTheory.jl+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + ! grep -i "rsr-template" docs/CITATIONS.adoc && \ + ! grep "AGPL" docs/CITATIONS.adoc && \ + grep "KnotTheory.jl" docs/CITATIONS.adoc > /dev/null && \ + grep "Jewell" docs/CITATIONS.adoc > /dev/null && \ + echo "PASS: CITATIONS.adoc correctly references KnotTheory.jl" +---- + +''''' + +=== TASK 9: Add Reidemeister II and III simplification (MEDIUM) + +*Problem:* Only Reidemeister I simplification is implemented +(`+r1_simplify+` at line 244). The `+simplify_pd+` function (line 257) +delegates exclusively to `+r1_simplify+`. Reidemeister II (removing two +crossings that cancel) and Reidemeister III (triangle move) are listed +in the ROADMAP as "`SHOULD`" for v1.1 but are needed for basic diagram +simplification to work on any non-trivial knot. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl+` + +*Fix:* 1. Add `+r2_simplify(pd::PlanarDiagram)::PlanarDiagram+` – detect +pairs of crossings where two arcs connect the same two crossings with +opposite signs and can be removed (bigon removal). 2. Add +`+r3_simplify(pd::PlanarDiagram)::PlanarDiagram+` – detect a triangle of +three crossings where a strand can be slid across (this is a +topology-preserving move, not a reduction, so it is optional for +simplification but should be available). 3. Update `+simplify_pd+` to +iterate R1 and R2 moves until no further reduction occurs (a fixed-point +loop). 4. Export `+r2_simplify+` and `+r3_simplify+`. 5. Add tests for +each move. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using KnotTheory +# Test R2: two crossings that form a bigon should cancel +# Construct a PD with two crossings that form an R2 pair +pd = KnotTheory.pdcode([ + (1, 2, 3, 4, 1), + (3, 4, 1, 2, -1) +]) +reduced = KnotTheory.r2_simplify(pd) +println("R2: $(length(pd.crossings)) -> $(length(reduced.crossings)) crossings") +@assert length(reduced.crossings) < length(pd.crossings) "R2 should reduce crossing count" +println("PASS: Reidemeister II simplification works") +' +---- + +''''' + +=== TASK 10: Add tests for edge cases and improve test coverage (MEDIUM) + +*Problem:* The test file (`+test/runtests.jl+`) has only 8 test sets +with basic happy-path tests. Missing coverage includes: + +[arabic] +. No test for `+linking_number+` on actual multi-component links. +. No test for `+to_dowker+` correctness. +. No test for `+jones_polynomial+` on a known knot with a known answer. +. No test for the CairoMakie extension (even a conditional test). +. No edge case tests (empty PD, single crossing, very large arc labels). +. No test for `+to_polynomial+` with negative exponents (will be needed +after Task 1). +. No test that the Alexander polynomial produces correct results for +known knots (will be needed after Task 2). + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/test/runtests.jl+` + +*Fix:* Add the following test sets: + +[arabic] +. `+@testset "Linking Number"+` – Create a Hopf link with known linking +number +/-1 and verify. +. `+@testset "Dowker Code"+` – Verify `+to_dowker+` produces correct +codes for trefoil PD. +. `+@testset "Jones Known Values"+` – Verify Jones polynomial of trefoil +PD matches the known result (up to normalization). +. `+@testset "Edge Cases"+` – Empty PD, unknot, single crossing with +repeated arcs. +. `+@testset "to_polynomial negative exponents"+` – Verify the tuple +return from Task 1 works correctly. +. `+@testset "Alexander Known Values"+` – After Task 2, verify Alexander +polynomial of trefoil matches `+t^-1 - 1 + t+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using Pkg; Pkg.test() +' 2>&1 | tail -5 +---- + +''''' + +=== TASK 11: Expand knot table beyond 3 entries (LOW) + +*Problem:* `+knot_table()+` at lines 524-530 only contains unknot, +trefoil, and figure-eight. The ROADMAP lists "`Knot table integration`" +with "`10K+ knots up to 16 crossings`" as a v1.1 goal. For a minimal +viable library, at least the prime knots through 7 crossings should be +present (15 knots total). + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl+`, lines +524-530 + +*Fix:* Expand `+knot_table()+` to include all prime knots through 7 +crossings using their DT codes. The standard Rolfsen table entries are: + +* 0_1 (unknot): DT=[] +* 3_1 (trefoil): DT=[4,6,2] +* 4_1 (figure-eight): DT=[4,6,8,2] +* 5_1: DT=[6,8,10,2,4] +* 5_2: DT=[4,8,10,2,6] +* 6_1: DT=[4,8,12,2,10,6] +* 6_2: DT=[4,8,10,12,2,6] +* 6_3: DT=[4,8,10,2,12,6] +* 7_1: DT=[8,10,12,14,2,4,6] +* 7_2: DT=[4,10,14,12,2,8,6] +* 7_3: DT=[4,12,10,14,2,8,6] +* 7_4: DT=[6,10,14,12,2,4,8] +* 7_5: DT=[6,10,14,8,2,4,12] +* 7_6: DT=[4,10,14,8,2,12,6] +* 7_7: DT=[4,12,14,8,2,10,6] + +Also update `+lookup_knot+` to handle the symbol names (e.g., +`+Symbol("5_1")+`). Add convenience constructors for each (e.g., +`+knot_5_1()+`), or at minimum ensure `+lookup_knot(Symbol("5_1"))+` +works. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using KnotTheory +table = knot_table() +@assert length(table) >= 15 "Expected at least 15 knots, got $(length(table))" +entry = lookup_knot(Symbol("5_1")) +@assert entry !== nothing "5_1 should be in the table" +@assert entry.crossings == 5 +println("PASS: Knot table has $(length(table)) entries including 5_1") +' +---- + +''''' + +=== TASK 12: Fix the intro notebook to be a useful tutorial (LOW) + +*Problem:* `+tutorials/intro.ipynb+` contains only two cells: a markdown +title and a single Julia cell `+using KnotTheory; trefoil()+`. This is +not a useful tutorial. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/tutorials/intro.ipynb+` + +*Fix:* Expand the notebook to include cells demonstrating: 1. +Installing/loading KnotTheory.jl 2. Creating knots from the table +(unknot, trefoil, figure-eight) 3. Computing crossing number and writhe +4. Building a PD code from scratch 5. Computing Alexander and Jones +polynomials 6. Simplifying diagrams with Reidemeister moves 7. JSON +import/export round-trip 8. Graph conversion + +Each section should have a markdown cell explaining the concept and a +code cell demonstrating it. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' +using JSON3 +nb = JSON3.read(read("tutorials/intro.ipynb", String)) +cells = nb["cells"] +println("Notebook has $(length(cells)) cells") +@assert length(cells) >= 10 "Tutorial should have at least 10 cells, got $(length(cells))" +println("PASS: Tutorial notebook has sufficient content") +' +---- + +''''' + +=== TASK 13: Fix Idris2 proof holes in Layout.idr (LOW) + +*Problem:* `+/var$REPOS_DIR/KnotTheory.jl/src/abi/Layout.idr+` contains +three unfinished proof holes (Idris2 `+?+`-prefixed metavariables): + +[arabic] +. Line 138: `+?fieldsAlignedProof+` in `+checkCABI+` +. Line 159: `+?exampleFieldsAligned+` in `+exampleLayoutValid+` +. Line 176: `+?offsetInBoundsProof+` in `+offsetInBounds+` + +These are admitted proofs that the Idris2 compiler will accept but are +not actually proven. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/src/abi/Layout.idr+` + +*Fix:* Either: (a) Complete the proofs properly using Idris2 proof +tactics, OR (b) If the ABI/FFI layer is not actually used by this Julia +package (it is RSR template boilerplate), add a comment +`+-- NOTE: Template proof hole; KnotTheory.jl does not use the Idris2 ABI layer+` +to each hole to make the incomplete status explicit. + +Option (b) is recommended since KnotTheory.jl is a pure Julia package +and the Idris2/Zig ABI-FFI layer is RSR template scaffolding that has no +functional connection to the knot theory code. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + grep -c "NOTE: Template proof hole" src/abi/Layout.idr | \ + xargs -I{} test {} -ge 3 && \ + echo "PASS: All proof holes annotated" +---- + +''''' + +=== TASK 14: Update CI workflow to include Julia 1.12 and fix checkout SHA (LOW) + +*Problem:* The CI workflow at `+.github/workflows/ci.yml+` tests Julia +versions `+['1.9', '1.10', '1.11']+` but the `+Manifest.toml+` was +generated with Julia 1.12.2 (line 3: `+julia_version = "1.12.2"+`). The +checkout action SHA `+b4ffde65f46336ab88eb53be808477a3936bae11+` does +not match the SHA listed in CLAUDE.md for `+actions/checkout@v4+` which +is `+34e114876b0b11c390a56381ad16ebd13914f8d5+`. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/.github/workflows/ci.yml+` + +*Fix:* 1. Add `+'1.12'+` to the Julia version matrix. 2. Replace +checkout SHA with the one from CLAUDE.md: +`+34e114876b0b11c390a56381ad16ebd13914f8d5+`. 3. Add +`+permissions: read-all+` at the workflow level (per CLAUDE.md +checklist). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + grep "1.12" .github/workflows/ci.yml > /dev/null && \ + grep "34e114876b0b11c390a56381ad16ebd13914f8d5" .github/workflows/ci.yml > /dev/null && \ + grep "permissions:" .github/workflows/ci.yml > /dev/null && \ + echo "PASS: CI workflow updated" +---- + +''''' + +=== TASK 15: Update docs/src/index.md with actual API documentation (LOW) + +*Problem:* `+docs/src/index.md+` is a 14-line stub with a single trivial +example. It does not document any of the exported functions. + +*File:* `+/var$REPOS_DIR/KnotTheory.jl/docs/src/index.md+` + +*Fix:* Expand to document all exported symbols with their signatures, +parameters, return types, and brief descriptions. Group by category: + +[arabic] +. *Types:* `+EdgeOrientation+`, `+Crossing+`, `+PlanarDiagram+`, +`+DTCode+`, `+Knot+`, `+Link+` +. *Constructors:* `+pdcode+`, `+unknot+`, `+trefoil+`, `+figure_eight+` +. *Invariants:* `+crossing_number+`, `+writhe+`, `+linking_number+`, +`+seifert_circles+`, `+braid_index_estimate+` +. *Polynomials:* `+alexander_polynomial+`, `+jones_polynomial+` +. *Simplification:* `+r1_simplify+`, `+simplify_pd+` (and +`+r2_simplify+`, `+r3_simplify+` after Task 9) +. *Code Conversion:* `+dtcode+`, `+to_dowker+` +. *I/O:* `+write_knot_json+`, `+read_knot_json+` +. *Table:* `+knot_table+`, `+lookup_knot+` +. *Utilities:* `+to_graph+`, `+to_polynomial+`, `+plot_pd+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ + wc -l docs/src/index.md | awk '{if ($1 >= 80) print "PASS: index.md has sufficient content ("$1" lines)"; else {print "FAIL: only "$1" lines"; exit 1}}' +---- + +''''' + +=== FINAL VERIFICATION + +After all tasks are complete, run this comprehensive check: + +[source,bash] +---- +cd /var$REPOS_DIR/KnotTheory.jl && \ +echo "=== 1. Full test suite ===" && \ +julia --project=. -e 'using Pkg; Pkg.test()' && \ +echo "=== 2. No AGPL references ===" && \ +! grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.idr" --include="*.res" --include="*.adoc" . && \ +echo "=== 3. No template placeholders ===" && \ +! grep -r '{{' --include="*.md" --include="*.zig" --include="*.idr" --include="*.adoc" . && \ +echo "=== 4. .machine_readable/ exists ===" && \ +test -d .machine_readable && \ +test -f .machine_readable/STATE.scm && \ +test -f .machine_readable/META.scm && \ +test -f .machine_readable/ECOSYSTEM.scm && \ +echo "=== 5. Version is 0.1.0 ===" && \ +grep 'version = "0.1.0"' Project.toml > /dev/null && \ +echo "=== 6. Examples are relevant ===" && \ +test ! -f examples/SafeDOMExample.res && \ +test -f examples/basic_usage.jl && \ +echo "=== 7. to_polynomial handles negative exponents ===" && \ +julia --project=. -e ' +using KnotTheory +pd = KnotTheory.pdcode([(1,2,3,4,1)]) +j = KnotTheory.jones_polynomial(pd; wr=1) +result = KnotTheory.to_polynomial(j) +@assert result isa Tuple +println("to_polynomial returns tuple correctly") +' && \ +echo "=== 8. Knot table has >= 15 entries ===" && \ +julia --project=. -e ' +using KnotTheory +@assert length(knot_table()) >= 15 +' && \ +echo "" && \ +echo "============================================" && \ +echo " ALL FINAL VERIFICATION CHECKS PASSED" && \ +echo "============================================" +---- diff --git a/packages/KnotTheory.jl/SONNET-TASKS.md b/packages/KnotTheory.jl/SONNET-TASKS.md deleted file mode 100644 index 48efbf07c..000000000 --- a/packages/KnotTheory.jl/SONNET-TASKS.md +++ /dev/null @@ -1,748 +0,0 @@ -# SONNET-TASKS.md -- KnotTheory.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 62% - -The Julia knot-theory library (`src/KnotTheory.jl`) is a genuine, working module with -real data structures, invariants, and tests that pass. However, there are -significant issues: the Alexander polynomial is a self-described "placeholder" -that produces wrong results, the `to_polynomial` helper crashes on negative -exponents (which `jones_polynomial` routinely produces), several RSR template -files still have unreplaced `{{PLACEHOLDER}}` markers, SPDX headers use -the banned `AGPL-3.0-or-later` in multiple files, the `.machine_readable/` -directory is entirely missing, the `examples/` directory contains files -irrelevant to knot theory (a ReScript SafeDOM example and a Deno JSON config), -the version in `Project.toml` (1.0.0) contradicts `Manifest.toml` (0.1.0), -and three Idris2 proofs are holes (`?`-prefixed). - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update STATE.scm with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks: `cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e 'using Pkg; Pkg.test()'` - ---- - -## TASK 1: Fix `to_polynomial` crash on negative exponents (CRITICAL) - -**Problem:** `jones_polynomial` returns a `Dict{Int,Int}` where keys are often -negative (e.g., `Dict(-5 => 1, -3 => -1, -1 => 1)`). The `to_polynomial` -function at line 442-452 of `src/KnotTheory.jl` computes `max_exp + 1` and -builds a `coeffs` array indexed `exp + 1`. When `exp` is negative, this -produces an out-of-bounds index. This means Jones polynomial results cannot be -converted to `Polynomials.Polynomial` objects. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl`, lines 442-452 - -**Fix:** Rewrite `to_polynomial` to handle negative exponents by using -`min_exp` as an offset. Shift all exponents so the lowest becomes index 1. -The resulting `Polynomial` should carry correct coefficients; callers can -interpret the minimum exponent separately. - -**Exact function to replace:** -```julia -function to_polynomial(dict::Dict{Int, Int}) - if isempty(dict) - return Polynomial([0]) - end - max_exp = maximum(collect(keys(dict))) - coeffs = zeros(Int, max_exp + 1) - for (exp, coeff) in dict - coeffs[exp + 1] = coeff - end - Polynomial(coeffs) -end -``` - -**Replace with a version that:** -1. Computes `min_exp = minimum(keys(dict))` and `max_exp = maximum(keys(dict))`. -2. Allocates `coeffs` of length `max_exp - min_exp + 1`. -3. Uses `coeffs[exp - min_exp + 1] = coeff` for placement. -4. Returns a tuple `(Polynomial(coeffs), min_exp)` so the caller knows the - leading exponent offset. Alternatively, keep the return type as just - `Polynomial` but document that the variable represents `t^min_exp * poly(t)`. - Choose the tuple approach since it is unambiguous. -5. Update the export list and docstring accordingly. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using KnotTheory -pd = KnotTheory.pdcode([(1,2,3,4,1)]) -j = KnotTheory.jones_polynomial(pd; wr=1) -println("Jones dict: ", j) -poly, offset = KnotTheory.to_polynomial(j) -println("Polynomial: ", poly, " with offset t^", offset) -@assert poly isa KnotTheory.Polynomials.Polynomial -println("PASS: to_polynomial handles negative exponents") -' -``` - ---- - -## TASK 2: Fix the Alexander polynomial placeholder (HIGH) - -**Problem:** The `alexander_polynomial` function at lines 263-306 of -`src/KnotTheory.jl` is explicitly marked as a "crude expansion" and a -"placeholder". It builds a Seifert matrix `V` using `(a % n) + 1` and -`(c % n) + 1` as indices, which is mathematically unjustified. It then -evaluates `det(V)` and `det(V - V')` as an approximation. This does not -compute the actual Alexander polynomial for any non-trivial knot. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl`, lines 263-306 - -**Fix:** Implement a correct Alexander polynomial computation. The standard -approach for a planar diagram: - -1. Build the actual Seifert matrix from the Seifert surface: for each pair - of Seifert circles (i, j), compute the linking number contribution from - each crossing that connects circles i and j. -2. Compute `det(V - t * V')` as a polynomial in `t` using the `Polynomials` - package directly. The matrix `V - t * V'` is a matrix of `Polynomial` - entries; take its determinant symbolically. -3. For small matrices (say n <= 10), a cofactor expansion or Bareiss-like - algorithm over polynomials works. For the scope of this library (up to - 20 crossings), this is adequate. -4. Normalize the result so the polynomial is symmetric and evaluates to 1 - at t=1 (standard normalization). -5. Return a `Dict{Int,Int}` mapping exponent to coefficient, consistent - with the existing API. - -**Keep the signature:** `alexander_polynomial(pd::PlanarDiagram) -> Dict{Int,Int}` - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using KnotTheory -# Trefoil knot PD code: standard positive trefoil -# PD notation: X[1,4,2,5], X[3,6,4,1], X[5,2,6,3] with all positive crossings -pd = KnotTheory.pdcode([ - (1, 4, 2, 5, 1), - (3, 6, 4, 1, 1), - (5, 2, 6, 3, 1) -]) -alex = KnotTheory.alexander_polynomial(pd) -println("Alexander poly of trefoil: ", alex) -# The Alexander polynomial of the trefoil is t^-1 - 1 + t (up to normalization) -# Verify it is non-trivial (not just {0 => 1}) -@assert length(alex) > 1 || (length(alex) == 1 && !haskey(alex, 0)) -println("PASS: Alexander polynomial is non-trivial for trefoil") -' -``` - ---- - -## TASK 3: Fix version mismatch between Project.toml and Manifest.toml (HIGH) - -**Problem:** `Project.toml` line 4 says `version = "1.0.0"` but -`Manifest.toml` line 101 says `version = "0.1.0"`. The README.md and -ROADMAP.md refer to this as "v1.0" and "Production-ready". This is an -early-stage library with placeholder algorithms; it is not v1.0. - -**Files:** -- `/var$REPOS_DIR/KnotTheory.jl/Project.toml`, line 4 -- `/var$REPOS_DIR/KnotTheory.jl/ROADMAP.md`, line 3 and line 14 - -**Fix:** -1. Change `Project.toml` version to `"0.1.0"`. -2. Update `ROADMAP.md` to say "v0.1.0" / "Current State (v0.1.0)" and - remove the claim "Production-ready" (replace with "Early development"). -3. Regenerate `Manifest.toml` by running `julia --project=. -e 'using Pkg; Pkg.resolve()'`. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using Pkg -ctx = Pkg.Types.Context() -proj = ctx.env.project -println("Project version: ", proj.version) -@assert string(proj.version) == "0.1.0" "Version should be 0.1.0, got $(proj.version)" -println("PASS: version is 0.1.0") -' -``` - ---- - -## TASK 4: Fix SPDX license headers -- replace AGPL-3.0-or-later with MPL-2.0 (HIGH) - -**Problem:** Five files use the banned `AGPL-3.0-or-later` SPDX identifier: -1. `/var$REPOS_DIR/KnotTheory.jl/ffi/zig/build.zig` (line 2) -2. `/var$REPOS_DIR/KnotTheory.jl/ffi/zig/src/main.zig` (line 6) -3. `/var$REPOS_DIR/KnotTheory.jl/ffi/zig/test/integration_test.zig` (line 2) -4. `/var$REPOS_DIR/KnotTheory.jl/examples/SafeDOMExample.res` (line 1) -5. `/var$REPOS_DIR/KnotTheory.jl/docs/CITATIONS.adoc` (line 13, in BibTeX block) - -Per CLAUDE.md: "NEVER use AGPL-3.0". - -**Fix:** In each file, replace `AGPL-3.0-or-later` with `MPL-2.0`. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - ! grep -r "AGPL" --include="*.zig" --include="*.res" --include="*.adoc" . && \ - echo "PASS: No AGPL references remain" -``` - ---- - -## TASK 5: Replace all unreplaced `{{PLACEHOLDER}}` template markers (HIGH) - -**Problem:** Ten files still contain unreplaced `{{PROJECT}}`, `{{project}}`, -`{{OWNER}}`, `{{REPO}}`, `{{FORGE}}`, `{{SECURITY_EMAIL}}`, `{{PGP_FINGERPRINT}}`, -`{{PGP_KEY_URL}}`, `{{WEBSITE}}`, `{{CURRENT_YEAR}}`, `{{PROJECT_NAME}}`, -`{{CONDUCT_EMAIL}}`, `{{CONDUCT_TEAM}}`, `{{RESPONSE_TIME}}`, `{{MAIN_BRANCH}}`, -and `{{LICENSE}}` markers from the RSR template. These files are: - -1. `/var$REPOS_DIR/KnotTheory.jl/ffi/zig/build.zig` -- `{{PROJECT}}`, `{{project}}` -2. `/var$REPOS_DIR/KnotTheory.jl/ffi/zig/src/main.zig` -- `{{PROJECT}}`, `{{project}}` -3. `/var$REPOS_DIR/KnotTheory.jl/ffi/zig/test/integration_test.zig` -- `{{PROJECT}}`, `{{project}}` -4. `/var$REPOS_DIR/KnotTheory.jl/src/abi/Types.idr` -- `{{PROJECT}}` -5. `/var$REPOS_DIR/KnotTheory.jl/src/abi/Layout.idr` -- `{{PROJECT}}` -6. `/var$REPOS_DIR/KnotTheory.jl/src/abi/Foreign.idr` -- `{{PROJECT}}`, `{{project}}` -7. `/var$REPOS_DIR/KnotTheory.jl/ABI-FFI-README.md` -- `{{PROJECT}}`, `{{project}}`, `{{LICENSE}}` -8. `/var$REPOS_DIR/KnotTheory.jl/SECURITY.md` -- `{{OWNER}}`, `{{REPO}}`, `{{SECURITY_EMAIL}}`, `{{PGP_FINGERPRINT}}`, `{{PGP_KEY_URL}}`, `{{WEBSITE}}`, `{{CURRENT_YEAR}}`, `{{PROJECT_NAME}}` -9. `/var$REPOS_DIR/KnotTheory.jl/CODE_OF_CONDUCT.md` -- `{{PROJECT_NAME}}`, `{{OWNER}}`, `{{REPO}}`, `{{CONDUCT_EMAIL}}`, `{{CONDUCT_TEAM}}`, `{{RESPONSE_TIME}}`, `{{CURRENT_YEAR}}`, `{{FORGE}}` -10. `/var$REPOS_DIR/KnotTheory.jl/CONTRIBUTING.md` -- `{{FORGE}}`, `{{OWNER}}`, `{{REPO}}`, `{{MAIN_BRANCH}}` - -**Fix:** Replace with these values: -- `{{PROJECT}}` -> `KnotTheory` -- `{{project}}` -> `knottheory` -- `{{OWNER}}` -> `hyperpolymath` -- `{{REPO}}` -> `KnotTheory.jl` -- `{{FORGE}}` -> `github.com` -- `{{SECURITY_EMAIL}}` -> `jonathan.jewell@open.ac.uk` -- `{{PGP_FINGERPRINT}}` -> (remove the PGP section or leave a note to fill in) -- `{{PGP_KEY_URL}}` -> (remove the PGP section or leave a note to fill in) -- `{{WEBSITE}}` -> `https://github.com/hyperpolymath` -- `{{CURRENT_YEAR}}` -> `2026` -- `{{PROJECT_NAME}}` -> `KnotTheory.jl` -- `{{CONDUCT_EMAIL}}` -> `jonathan.jewell@open.ac.uk` -- `{{CONDUCT_TEAM}}` -> `KnotTheory.jl Maintainers` -- `{{RESPONSE_TIME}}` -> `48 hours` -- `{{MAIN_BRANCH}}` -> `main` -- `{{LICENSE}}` -> `MPL-2.0` - -Also delete the HTML comment blocks that say "TEMPLATE INSTRUCTIONS (delete this block before publishing)" from SECURITY.md (lines 3-19) and CODE_OF_CONDUCT.md (lines 3-21). - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - ! grep -r '{{' --include="*.md" --include="*.zig" --include="*.idr" --include="*.adoc" . && \ - echo "PASS: No template placeholders remain" -``` - ---- - -## TASK 6: Create `.machine_readable/` directory with STATE.scm, META.scm, ECOSYSTEM.scm (HIGH) - -**Problem:** The `.machine_readable/` directory is entirely absent. Per -CLAUDE.md, SCM files MUST be in `.machine_readable/` only, never in root. -There are no SCM files anywhere in the repo. - -**Fix:** Create the directory and populate three files: - -### `.machine_readable/STATE.scm` -```scheme -(define state - `((metadata - (project . "KnotTheory.jl") - (version . "0.1.0") - (updated . "2026-02-12")) - (project-context - (description . "Julia toolkit for knot theory: planar diagrams, invariants, polynomials") - (language . "Julia") - (category . "mathematics")) - (current-position - (phase . implementation) - (maturity . alpha) - (completion-percentage . 62)) - (route-to-mvp - (milestones - ((name . "correct-alexander") - (status . incomplete) - (description . "Replace Alexander polynomial placeholder with correct Seifert matrix algorithm")) - ((name . "homfly-pt") - (status . not-started) - (description . "Implement HOMFLY-PT two-variable polynomial")) - ((name . "knot-table") - (status . incomplete) - (description . "Expand knot table beyond 3 entries")) - ((name . "reidemeister-ii-iii") - (status . not-started) - (description . "Implement Reidemeister II and III moves")))) - (blockers-and-issues - ((blocker . "Alexander polynomial is a placeholder producing wrong results") - (severity . high)) - ((blocker . "to_polynomial crashes on negative exponents from Jones polynomial") - (severity . critical))) - (critical-next-actions - ("Fix to_polynomial negative exponent handling" - "Implement correct Alexander polynomial" - "Add Reidemeister II and III simplifications" - "Expand knot table with Rolfsen data")))) -``` - -### `.machine_readable/META.scm` -```scheme -(define meta - `((architecture-decisions - ((id . "ADR-001") - (title . "Dict-based polynomial representation") - (status . accepted) - (rationale . "Using Dict{Int,Int} for polynomial coefficients allows negative exponents and sparse representation")) - ((id . "ADR-002") - (title . "Kauffman bracket for Jones polynomial") - (status . accepted) - (rationale . "State-sum expansion is correct for small crossing numbers; limited to 20 crossings"))) - (development-practices - (testing . "julia --project=. -e 'using Pkg; Pkg.test()'") - (language . "Julia 1.9+") - (license . "MPL-2.0")))) -``` - -### `.machine_readable/ECOSYSTEM.scm` -```scheme -(define ecosystem - `((version . "1.0") - (name . "KnotTheory.jl") - (type . "julia-package") - (purpose . "Knot theory computations: planar diagrams, invariants, polynomial invariants") - (position-in-ecosystem . "standalone-library") - (related-projects - ((name . "Graphs.jl") - (relationship . dependency) - (description . "Used for graph representation of planar diagrams")) - ((name . "Polynomials.jl") - (relationship . dependency) - (description . "Used for polynomial arithmetic")) - ((name . "CairoMakie") - (relationship . optional-dependency) - (description . "Used for knot diagram plotting via package extension"))))) -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - test -f .machine_readable/STATE.scm && \ - test -f .machine_readable/META.scm && \ - test -f .machine_readable/ECOSYSTEM.scm && \ - echo "PASS: .machine_readable/ directory exists with all 3 SCM files" -``` - ---- - -## TASK 7: Remove irrelevant example files (MEDIUM) - -**Problem:** The `examples/` directory contains two files that have nothing to -do with knot theory: - -1. `examples/SafeDOMExample.res` -- A ReScript SafeDOM example from the RSR - template. Not relevant to a Julia knot theory library. -2. `examples/web-project-deno.json` -- A Deno project config for ReScript web - projects. Not relevant. - -**Fix:** -1. Delete `examples/SafeDOMExample.res`. -2. Delete `examples/web-project-deno.json`. -3. Create `examples/basic_usage.jl` with actual knot theory examples: - -```julia -# SPDX-License-Identifier: CC-BY-SA-4.0 -# Basic usage examples for KnotTheory.jl - -using KnotTheory - -# --- Create knots from the built-in table --- -k = trefoil() -println("Trefoil crossing number: ", crossing_number(k)) -println("Trefoil DT code: ", dtcode(k).code) - -fe = figure_eight() -println("Figure-eight crossing number: ", crossing_number(fe)) - -# --- Build a knot from PD code --- -# Single positive crossing -pd = pdcode([(1, 2, 3, 4, 1)]) -sample = Knot(:sample, pd, nothing) -println("Sample writhe: ", writhe(sample)) - -# --- Compute invariants --- -println("Seifert circles: ", seifert_circles(pd)) -println("Braid index estimate: ", braid_index_estimate(pd)) - -# --- Jones polynomial --- -jones = jones_polynomial(pd; wr=1) -println("Jones polynomial (dict): ", jones) - -# --- Simplification --- -# A crossing with repeated arcs (R1 reducible) -pd_loop = pdcode([(1, 1, 2, 2, 1)]) -reduced = r1_simplify(pd_loop) -println("Before R1: ", length(pd_loop.crossings), " crossings") -println("After R1: ", length(reduced.crossings), " crossings") - -# --- JSON round-trip --- -path = tempname() * ".json" -write_knot_json(path, sample) -loaded = read_knot_json(path) -println("Round-tripped knot name: ", loaded.name) -rm(path) - -# --- Graph conversion --- -using Graphs -g = to_graph(pd) -println("Graph vertices: ", nv(g), ", edges: ", ne(g)) - -# --- Knot table --- -table = knot_table() -for (name, entry) in table - println(" ", name, ": ", entry.crossings, " crossings") -end -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - test ! -f examples/SafeDOMExample.res && \ - test ! -f examples/web-project-deno.json && \ - test -f examples/basic_usage.jl && \ - julia --project=. examples/basic_usage.jl && \ - echo "PASS: examples/ contains only relevant knot theory examples and they run" -``` - ---- - -## TASK 8: Fix CITATIONS.adoc to reference KnotTheory.jl instead of RSR-template-repo (MEDIUM) - -**Problem:** `/var$REPOS_DIR/KnotTheory.jl/docs/CITATIONS.adoc` -still references `rsr-template-repo` everywhere and uses -`AGPL-3.0-or-later` for the license. It also attributes authorship to -`Polymath, Hyper` instead of the correct `Jewell, Jonathan D.A.`. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/docs/CITATIONS.adoc` - -**Fix:** Replace all occurrences of: -- `rsr-template-repo` -> `KnotTheory.jl` -- `RSR-template-repo` -> `KnotTheory.jl` -- `Polymath, Hyper` / `Hyper Polymath` -> `Jewell, Jonathan D.A.` / `Jonathan D.A. Jewell` -- `AGPL-3.0-or-later` -> `MPL-2.0` -- `2025` -> `2026` (year) -- Fix the title line to say `= KnotTheory.jl - Citation Guide` -- Fix URLs to point to `https://github.com/hyperpolymath/KnotTheory.jl` - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - ! grep -i "rsr-template" docs/CITATIONS.adoc && \ - ! grep "AGPL" docs/CITATIONS.adoc && \ - grep "KnotTheory.jl" docs/CITATIONS.adoc > /dev/null && \ - grep "Jewell" docs/CITATIONS.adoc > /dev/null && \ - echo "PASS: CITATIONS.adoc correctly references KnotTheory.jl" -``` - ---- - -## TASK 9: Add Reidemeister II and III simplification (MEDIUM) - -**Problem:** Only Reidemeister I simplification is implemented (`r1_simplify` -at line 244). The `simplify_pd` function (line 257) delegates exclusively to -`r1_simplify`. Reidemeister II (removing two crossings that cancel) and -Reidemeister III (triangle move) are listed in the ROADMAP as "SHOULD" for -v1.1 but are needed for basic diagram simplification to work on any -non-trivial knot. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl` - -**Fix:** -1. Add `r2_simplify(pd::PlanarDiagram)::PlanarDiagram` -- detect pairs of - crossings where two arcs connect the same two crossings with opposite - signs and can be removed (bigon removal). -2. Add `r3_simplify(pd::PlanarDiagram)::PlanarDiagram` -- detect a triangle - of three crossings where a strand can be slid across (this is a - topology-preserving move, not a reduction, so it is optional for - simplification but should be available). -3. Update `simplify_pd` to iterate R1 and R2 moves until no further - reduction occurs (a fixed-point loop). -4. Export `r2_simplify` and `r3_simplify`. -5. Add tests for each move. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using KnotTheory -# Test R2: two crossings that form a bigon should cancel -# Construct a PD with two crossings that form an R2 pair -pd = KnotTheory.pdcode([ - (1, 2, 3, 4, 1), - (3, 4, 1, 2, -1) -]) -reduced = KnotTheory.r2_simplify(pd) -println("R2: $(length(pd.crossings)) -> $(length(reduced.crossings)) crossings") -@assert length(reduced.crossings) < length(pd.crossings) "R2 should reduce crossing count" -println("PASS: Reidemeister II simplification works") -' -``` - ---- - -## TASK 10: Add tests for edge cases and improve test coverage (MEDIUM) - -**Problem:** The test file (`test/runtests.jl`) has only 8 test sets with -basic happy-path tests. Missing coverage includes: - -1. No test for `linking_number` on actual multi-component links. -2. No test for `to_dowker` correctness. -3. No test for `jones_polynomial` on a known knot with a known answer. -4. No test for the CairoMakie extension (even a conditional test). -5. No edge case tests (empty PD, single crossing, very large arc labels). -6. No test for `to_polynomial` with negative exponents (will be needed - after Task 1). -7. No test that the Alexander polynomial produces correct results for known - knots (will be needed after Task 2). - -**File:** `/var$REPOS_DIR/KnotTheory.jl/test/runtests.jl` - -**Fix:** Add the following test sets: - -1. `@testset "Linking Number"` -- Create a Hopf link with known linking - number +/-1 and verify. -2. `@testset "Dowker Code"` -- Verify `to_dowker` produces correct codes - for trefoil PD. -3. `@testset "Jones Known Values"` -- Verify Jones polynomial of trefoil PD - matches the known result (up to normalization). -4. `@testset "Edge Cases"` -- Empty PD, unknot, single crossing with repeated - arcs. -5. `@testset "to_polynomial negative exponents"` -- Verify the tuple return - from Task 1 works correctly. -6. `@testset "Alexander Known Values"` -- After Task 2, verify Alexander - polynomial of trefoil matches `t^-1 - 1 + t`. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using Pkg; Pkg.test() -' 2>&1 | tail -5 -``` - ---- - -## TASK 11: Expand knot table beyond 3 entries (LOW) - -**Problem:** `knot_table()` at lines 524-530 only contains unknot, trefoil, -and figure-eight. The ROADMAP lists "Knot table integration" with "10K+ knots -up to 16 crossings" as a v1.1 goal. For a minimal viable library, at least -the prime knots through 7 crossings should be present (15 knots total). - -**File:** `/var$REPOS_DIR/KnotTheory.jl/src/KnotTheory.jl`, lines 524-530 - -**Fix:** Expand `knot_table()` to include all prime knots through 7 crossings -using their DT codes. The standard Rolfsen table entries are: - -- 0_1 (unknot): DT=[] -- 3_1 (trefoil): DT=[4,6,2] -- 4_1 (figure-eight): DT=[4,6,8,2] -- 5_1: DT=[6,8,10,2,4] -- 5_2: DT=[4,8,10,2,6] -- 6_1: DT=[4,8,12,2,10,6] -- 6_2: DT=[4,8,10,12,2,6] -- 6_3: DT=[4,8,10,2,12,6] -- 7_1: DT=[8,10,12,14,2,4,6] -- 7_2: DT=[4,10,14,12,2,8,6] -- 7_3: DT=[4,12,10,14,2,8,6] -- 7_4: DT=[6,10,14,12,2,4,8] -- 7_5: DT=[6,10,14,8,2,4,12] -- 7_6: DT=[4,10,14,8,2,12,6] -- 7_7: DT=[4,12,14,8,2,10,6] - -Also update `lookup_knot` to handle the symbol names (e.g., `Symbol("5_1")`). -Add convenience constructors for each (e.g., `knot_5_1()`), or at minimum -ensure `lookup_knot(Symbol("5_1"))` works. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using KnotTheory -table = knot_table() -@assert length(table) >= 15 "Expected at least 15 knots, got $(length(table))" -entry = lookup_knot(Symbol("5_1")) -@assert entry !== nothing "5_1 should be in the table" -@assert entry.crossings == 5 -println("PASS: Knot table has $(length(table)) entries including 5_1") -' -``` - ---- - -## TASK 12: Fix the intro notebook to be a useful tutorial (LOW) - -**Problem:** `tutorials/intro.ipynb` contains only two cells: a markdown -title and a single Julia cell `using KnotTheory; trefoil()`. This is not -a useful tutorial. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/tutorials/intro.ipynb` - -**Fix:** Expand the notebook to include cells demonstrating: -1. Installing/loading KnotTheory.jl -2. Creating knots from the table (unknot, trefoil, figure-eight) -3. Computing crossing number and writhe -4. Building a PD code from scratch -5. Computing Alexander and Jones polynomials -6. Simplifying diagrams with Reidemeister moves -7. JSON import/export round-trip -8. Graph conversion - -Each section should have a markdown cell explaining the concept and a code -cell demonstrating it. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && julia --project=. -e ' -using JSON3 -nb = JSON3.read(read("tutorials/intro.ipynb", String)) -cells = nb["cells"] -println("Notebook has $(length(cells)) cells") -@assert length(cells) >= 10 "Tutorial should have at least 10 cells, got $(length(cells))" -println("PASS: Tutorial notebook has sufficient content") -' -``` - ---- - -## TASK 13: Fix Idris2 proof holes in Layout.idr (LOW) - -**Problem:** `/var$REPOS_DIR/KnotTheory.jl/src/abi/Layout.idr` -contains three unfinished proof holes (Idris2 `?`-prefixed metavariables): - -1. Line 138: `?fieldsAlignedProof` in `checkCABI` -2. Line 159: `?exampleFieldsAligned` in `exampleLayoutValid` -3. Line 176: `?offsetInBoundsProof` in `offsetInBounds` - -These are admitted proofs that the Idris2 compiler will accept but are not -actually proven. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/src/abi/Layout.idr` - -**Fix:** Either: -(a) Complete the proofs properly using Idris2 proof tactics, OR -(b) If the ABI/FFI layer is not actually used by this Julia package (it is - RSR template boilerplate), add a comment `-- NOTE: Template proof hole; - KnotTheory.jl does not use the Idris2 ABI layer` to each hole to make - the incomplete status explicit. - -Option (b) is recommended since KnotTheory.jl is a pure Julia package and -the Idris2/Zig ABI-FFI layer is RSR template scaffolding that has no -functional connection to the knot theory code. - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - grep -c "NOTE: Template proof hole" src/abi/Layout.idr | \ - xargs -I{} test {} -ge 3 && \ - echo "PASS: All proof holes annotated" -``` - ---- - -## TASK 14: Update CI workflow to include Julia 1.12 and fix checkout SHA (LOW) - -**Problem:** The CI workflow at `.github/workflows/ci.yml` tests Julia -versions `['1.9', '1.10', '1.11']` but the `Manifest.toml` was generated -with Julia 1.12.2 (line 3: `julia_version = "1.12.2"`). The checkout action -SHA `b4ffde65f46336ab88eb53be808477a3936bae11` does not match the SHA -listed in CLAUDE.md for `actions/checkout@v4` which is -`34e114876b0b11c390a56381ad16ebd13914f8d5`. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/.github/workflows/ci.yml` - -**Fix:** -1. Add `'1.12'` to the Julia version matrix. -2. Replace checkout SHA with the one from CLAUDE.md: `34e114876b0b11c390a56381ad16ebd13914f8d5`. -3. Add `permissions: read-all` at the workflow level (per CLAUDE.md checklist). - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - grep "1.12" .github/workflows/ci.yml > /dev/null && \ - grep "34e114876b0b11c390a56381ad16ebd13914f8d5" .github/workflows/ci.yml > /dev/null && \ - grep "permissions:" .github/workflows/ci.yml > /dev/null && \ - echo "PASS: CI workflow updated" -``` - ---- - -## TASK 15: Update docs/src/index.md with actual API documentation (LOW) - -**Problem:** `docs/src/index.md` is a 14-line stub with a single trivial -example. It does not document any of the exported functions. - -**File:** `/var$REPOS_DIR/KnotTheory.jl/docs/src/index.md` - -**Fix:** Expand to document all exported symbols with their signatures, -parameters, return types, and brief descriptions. Group by category: - -1. **Types:** `EdgeOrientation`, `Crossing`, `PlanarDiagram`, `DTCode`, `Knot`, `Link` -2. **Constructors:** `pdcode`, `unknot`, `trefoil`, `figure_eight` -3. **Invariants:** `crossing_number`, `writhe`, `linking_number`, `seifert_circles`, `braid_index_estimate` -4. **Polynomials:** `alexander_polynomial`, `jones_polynomial` -5. **Simplification:** `r1_simplify`, `simplify_pd` (and `r2_simplify`, `r3_simplify` after Task 9) -6. **Code Conversion:** `dtcode`, `to_dowker` -7. **I/O:** `write_knot_json`, `read_knot_json` -8. **Table:** `knot_table`, `lookup_knot` -9. **Utilities:** `to_graph`, `to_polynomial`, `plot_pd` - -**Verification:** -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ - wc -l docs/src/index.md | awk '{if ($1 >= 80) print "PASS: index.md has sufficient content ("$1" lines)"; else {print "FAIL: only "$1" lines"; exit 1}}' -``` - ---- - -## FINAL VERIFICATION - -After all tasks are complete, run this comprehensive check: - -```bash -cd /var$REPOS_DIR/KnotTheory.jl && \ -echo "=== 1. Full test suite ===" && \ -julia --project=. -e 'using Pkg; Pkg.test()' && \ -echo "=== 2. No AGPL references ===" && \ -! grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.idr" --include="*.res" --include="*.adoc" . && \ -echo "=== 3. No template placeholders ===" && \ -! grep -r '{{' --include="*.md" --include="*.zig" --include="*.idr" --include="*.adoc" . && \ -echo "=== 4. .machine_readable/ exists ===" && \ -test -d .machine_readable && \ -test -f .machine_readable/STATE.scm && \ -test -f .machine_readable/META.scm && \ -test -f .machine_readable/ECOSYSTEM.scm && \ -echo "=== 5. Version is 0.1.0 ===" && \ -grep 'version = "0.1.0"' Project.toml > /dev/null && \ -echo "=== 6. Examples are relevant ===" && \ -test ! -f examples/SafeDOMExample.res && \ -test -f examples/basic_usage.jl && \ -echo "=== 7. to_polynomial handles negative exponents ===" && \ -julia --project=. -e ' -using KnotTheory -pd = KnotTheory.pdcode([(1,2,3,4,1)]) -j = KnotTheory.jones_polynomial(pd; wr=1) -result = KnotTheory.to_polynomial(j) -@assert result isa Tuple -println("to_polynomial returns tuple correctly") -' && \ -echo "=== 8. Knot table has >= 15 entries ===" && \ -julia --project=. -e ' -using KnotTheory -@assert length(knot_table()) >= 15 -' && \ -echo "" && \ -echo "============================================" && \ -echo " ALL FINAL VERIFICATION CHECKS PASSED" && \ -echo "============================================" -``` diff --git a/packages/KnotTheory.jl/TOPOLOGY.md b/packages/KnotTheory.jl/TOPOLOGY.adoc similarity index 89% rename from packages/KnotTheory.jl/TOPOLOGY.md rename to packages/KnotTheory.jl/TOPOLOGY.adoc index 8e783d012..19b4504b2 100644 --- a/packages/KnotTheory.jl/TOPOLOGY.md +++ b/packages/KnotTheory.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== KnotTheory.jl — Project Topology -# KnotTheory.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE STRUCTURES @@ -71,26 +67,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~95% Stable Implementation -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Planar Diagram ──────► Seifert Theory ──────► Polynomial Invariants │ Knot Table ──────────► Search & Lookup ────────────┤ │ Braid Words ─────────► PD Code ────────────► Simplification -``` +.... -## 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/packages/KnotTheory.jl/docs/README.adoc b/packages/KnotTheory.jl/docs/README.adoc new file mode 100644 index 000000000..97d9af627 --- /dev/null +++ b/packages/KnotTheory.jl/docs/README.adoc @@ -0,0 +1,7 @@ +== KnotTheory.jl Docs + +This folder contains lightweight documentation drafts. For a full site, +you can wire this repo up with Documenter.jl later. + +* `+src/index.md+` provides a starter overview. +* `+tutorials/intro.ipynb+` provides a minimal notebook scaffold. diff --git a/packages/KnotTheory.jl/docs/README.md b/packages/KnotTheory.jl/docs/README.md deleted file mode 100644 index 1028c9337..000000000 --- a/packages/KnotTheory.jl/docs/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# KnotTheory.jl Docs - -This folder contains lightweight documentation drafts. For a full site, you can -wire this repo up with Documenter.jl later. - -- `src/index.md` provides a starter overview. -- `tutorials/intro.ipynb` provides a minimal notebook scaffold. diff --git a/packages/KnotTheory.jl/docs/src/index.adoc b/packages/KnotTheory.jl/docs/src/index.adoc new file mode 100644 index 000000000..87f5584cc --- /dev/null +++ b/packages/KnotTheory.jl/docs/src/index.adoc @@ -0,0 +1,15 @@ +== KnotTheory.jl + +KnotTheory.jl provides core types and helpers for knot diagrams, +invariants, and lightweight analysis. This is a starter index for future +documentation. + +=== Examples + +[source,julia] +---- +using KnotTheory + +k = trefoil() +println(crossing_number(k)) +---- diff --git a/packages/KnotTheory.jl/docs/src/index.md b/packages/KnotTheory.jl/docs/src/index.md deleted file mode 100644 index 51b281173..000000000 --- a/packages/KnotTheory.jl/docs/src/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# KnotTheory.jl - -KnotTheory.jl provides core types and helpers for knot diagrams, invariants, and -lightweight analysis. This is a starter index for future documentation. - -## Examples - -```julia -using KnotTheory - -k = trefoil() -println(crossing_number(k)) -``` diff --git a/packages/Lithoglyph.jl/TOPOLOGY.md b/packages/Lithoglyph.jl/TOPOLOGY.adoc similarity index 88% rename from packages/Lithoglyph.jl/TOPOLOGY.md rename to packages/Lithoglyph.jl/TOPOLOGY.adoc index e936ea72e..be75b96b2 100644 --- a/packages/Lithoglyph.jl/TOPOLOGY.md +++ b/packages/Lithoglyph.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Lithoglyph.jl — Project Topology -# Lithoglyph.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ LITHOGLYPH FEDERATION │ ├─────────────────────────────────────────┤ @@ -42,11 +38,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE CLIENT @@ -64,26 +60,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████░░░░░░ ~40% Initial Client Interface -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Lithoglyph Core ─────► FFI Bridge ──────────► Normalization │ Client Config ───────► Lithoglyph Client ──────┤ │ Glyph Schema ────────► Register / Search ─────► COMPLETE -``` +.... -## 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/packages/LowLevel.jl/TOPOLOGY.md b/packages/LowLevel.jl/TOPOLOGY.adoc similarity index 90% rename from packages/LowLevel.jl/TOPOLOGY.md rename to packages/LowLevel.jl/TOPOLOGY.adoc index acb69fe73..5f52b7d21 100644 --- a/packages/LowLevel.jl/TOPOLOGY.md +++ b/packages/LowLevel.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== LowLevel.jl — Project Topology -# LowLevel.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ HARDWARE / BARE METAL │ ├─────────────────────────────────────────┤ @@ -48,11 +44,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── HARDWARE DISPATCH @@ -77,26 +73,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~85% Peak System (Stabilizing) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Topology Mapping ──────► Hardware Dispatch ──────► LowLevel.jl │ ASM / Intrinsics ──────► Multi-Lang Bridges ─────────┤ │ Diagnostics ───────────► Self-Healing ───────────► COMPLETE -``` +.... -## 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/packages/MacroPower.jl/TOPOLOGY.md b/packages/MacroPower.jl/TOPOLOGY.adoc similarity index 87% rename from packages/MacroPower.jl/TOPOLOGY.md rename to packages/MacroPower.jl/TOPOLOGY.adoc index 2af6f5d29..af46dbb5c 100644 --- a/packages/MacroPower.jl/TOPOLOGY.md +++ b/packages/MacroPower.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== MacroPower.jl — Project Topology -# MacroPower.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / TRIGGERS │ ├─────────────────────────────────────────┤ @@ -37,11 +33,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ENGINE @@ -59,24 +55,25 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██░░░░░░░░ ~20% Initial Scaffold -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Macro Parser ──────► Workflow Model ──────► Trigger Monitor │ Execution Engine ◀────── Action Dispatch ◀─────┘ -``` +.... -## 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/packages/MinixSDK.jl/TOPOLOGY.md b/packages/MinixSDK.jl/TOPOLOGY.adoc similarity index 87% rename from packages/MinixSDK.jl/TOPOLOGY.md rename to packages/MinixSDK.jl/TOPOLOGY.adoc index a19800811..c2e85902a 100644 --- a/packages/MinixSDK.jl/TOPOLOGY.md +++ b/packages/MinixSDK.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== MinixSDK.jl — Project Topology -# MinixSDK.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ TARGET OS / KERNEL │ ├─────────────────────────────────────────┤ @@ -37,11 +33,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE SDK @@ -59,26 +55,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █░░░░░░░░░ ~15% Research Prototype -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Julia Logic ──────► Cross-Compiler ──────► MINIX C Service │ IPC Definitions ───► IPC Wrappers ───────────┤ │ Driver Specs ──────► Boilerplate Gen ────────┘ -``` +.... -## 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/packages/PRComms.jl/ABI-FFI-README.adoc b/packages/PRComms.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..46c07c05c --- /dev/null +++ b/packages/PRComms.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/%7B%7BOWNER%7D%7D/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/PRComms.jl/ABI-FFI-README.md b/packages/PRComms.jl/ABI-FFI-README.md deleted file mode 100644 index 320b3f6fa..000000000 --- a/packages/PRComms.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/PRComms.jl/CHANGELOG.adoc b/packages/PRComms.jl/CHANGELOG.adoc new file mode 100644 index 000000000..ca1c65289 --- /dev/null +++ b/packages/PRComms.jl/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/packages/PRComms.jl/CHANGELOG.md b/packages/PRComms.jl/CHANGELOG.md deleted file mode 100644 index 810947691..000000000 --- a/packages/PRComms.jl/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/packages/PRComms.jl/CODE_OF_CONDUCT.adoc b/packages/PRComms.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/PRComms.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/PRComms.jl/CODE_OF_CONDUCT.md b/packages/PRComms.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/PRComms.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/PRComms.jl/CONTRIBUTING.adoc b/packages/PRComms.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..ad866b5ab --- /dev/null +++ b/packages/PRComms.jl/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/PRComms.jl/CONTRIBUTING.md b/packages/PRComms.jl/CONTRIBUTING.md deleted file mode 100644 index 02758c676..000000000 --- a/packages/PRComms.jl/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/PRComms.jl/GOVERNANCE.adoc b/packages/PRComms.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..6dddd7a45 --- /dev/null +++ b/packages/PRComms.jl/GOVERNANCE.adoc @@ -0,0 +1,176 @@ +== Project Governance + +This document describes the governance model for *\{\{PROJECT_NAME}}*. + +''''' + +=== Project Governance Model + +\{\{PROJECT_NAME}} follows a *Benevolent Dictator For Life (BDFL)* +governance model. This model is well-suited for solo maintainers and +small project teams where rapid, consistent decision-making is more +valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including +technical direction, release schedules, contributor access, and +community standards. + +____ +*Transition clause:* When the core team exceeds three active +maintainers, this project should transition to a *consensus-based +governance model* with documented voting procedures. That transition +should itself be recorded as an Architecture Decision Record (ADR) in +`+docs/decisions/+`. +____ + +''''' + +=== Decision Making + +==== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (bug fixes, dependency updates, minor improvements) +may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on +non-trivial changes. + +==== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new features, breaking changes, architectural +shifts) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +==== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs in +`+docs/decisions/+`. +* ADR statuses: `+proposed+`, `+accepted+`, `+deprecated+`, +`+superseded+`, `+rejected+`. +* ADRs provide a historical record of why decisions were made and what +alternatives were considered. +* See `+.machine_readable/META.a2ml+` for the machine-readable ADR +index. + +''''' + +=== Roles + +==== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project’s technical direction and long-term vision. +* Has final say on all matters, including maintainer appointments and +removals. +* Responsible for ensuring the project adheres to RSR standards. + +==== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages releases. +* Upholds code quality, security standards, and the Code of Conduct. +* Listed in MAINTAINERS.md. + +==== Contributor + +* Anyone who submits pull requests, opens issues, or participates in +discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +==== Bot + +* Automated agents managed via your bot orchestration system. +* Perform automated code review, security scanning, dependency updates, +and standards enforcement. +* Bot actions are subject to the same quality and review standards as +human contributions. +* Configure your bots in `+.machine_readable/bot_directives/+`. + +''''' + +=== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they +demonstrate: + +[arabic] +. *Sustained quality contributions* – a track record of well-crafted +pull requests that follow project conventions and require minimal +revision. +. *Understanding of RSR standards* – familiarity with the Repository +Structure Requirements, security policies, and CI/CD workflows used +across the project. +. *Constructive participation* – helpful issue triage, thoughtful code +review comments, and mentoring of other contributors. +. *Reliability* – consistent engagement over a meaningful period +(typically 3+ months of active contribution). + +==== Process + +[arabic] +. An existing maintainer nominates the candidate by opening a private +discussion with the BDFL. +. The BDFL reviews the candidate’s contribution history and community +interactions. +. The BDFL approves or declines the nomination, with reasoning provided +to the nominator. +. If approved, the new maintainer is added to MAINTAINERS.md and granted +appropriate repository access. + +''''' + +=== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more +consecutive months. The maintainer will be contacted before removal and +offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the +link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the +enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons +(e.g., repeated disregard for project standards, loss of trust). +Reasoning will be documented privately. + +Removed maintainers are moved to the Emeritus section of MAINTAINERS.md +unless removal was due to a serious Code of Conduct violation. + +''''' + +=== Code of Conduct + +All participants in this project are expected to follow the +link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to +all project spaces, including issues, pull requests, discussions, and +any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The +BDFL serves as the final arbiter in conduct disputes. + +''''' + +=== Amendments + +This governance document may be amended by the BDFL at any time. All +amendments will be: + +[arabic] +. Documented as an ADR in `+docs/decisions/+` explaining the rationale +for the change. +. Committed to the repository with a clear commit message. +. Communicated to existing maintainers and contributors via the +project’s usual channels. + +Substantive changes (e.g., changing the governance model itself) should +be discussed with the community before adoption, even though the BDFL +retains final authority. + +''''' + +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PRComms.jl/GOVERNANCE.md b/packages/PRComms.jl/GOVERNANCE.md deleted file mode 100644 index 5f082df92..000000000 --- a/packages/PRComms.jl/GOVERNANCE.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PRComms.jl/MAINTAINERS.adoc b/packages/PRComms.jl/MAINTAINERS.adoc index d829dd959..f3a0e022b 100644 --- a/packages/PRComms.jl/MAINTAINERS.adoc +++ b/packages/PRComms.jl/MAINTAINERS.adoc @@ -1,47 +1,43 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of +*\{\{PROJECT_NAME}}*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|\{\{AUTHOR}} |https://github.com/%7B%7BOWNER%7D%7D[@\{OWNER}] |BDFL +|\{\{CURRENT_DATE}} |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PRComms.jl/MAINTAINERS.md b/packages/PRComms.jl/MAINTAINERS.md deleted file mode 100644 index 32b92cc4a..000000000 --- a/packages/PRComms.jl/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **{{PROJECT_NAME}}**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| {{AUTHOR}} | [@{{OWNER}}](https://github.com/{{OWNER}}) | BDFL | {{CURRENT_DATE}} | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PRComms.jl/PLACEHOLDERS.adoc b/packages/PRComms.jl/PLACEHOLDERS.adoc new file mode 100644 index 000000000..1ec75339b --- /dev/null +++ b/packages/PRComms.jl/PLACEHOLDERS.adoc @@ -0,0 +1,191 @@ +== Template Placeholders + +All placeholders in this template follow the `+{{PLACEHOLDER}}+` +pattern. After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) +sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) +sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) +sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) +sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) +sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) +sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) +sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{AUTHOR}}+` |Full legal name |`+Jane Doe+` |SPDX headers (all +files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md + +|`+{{AUTHOR_EMAIL}}+` |Primary contact email |`+jane@example.org+` |SPDX +headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+{{AUTHOR_LAST}}+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_FIRST}}+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_INITIALS}}+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{PROJECT_NAME}}+` |Human-readable project name |`+My Project+` +|SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, +GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json + +|`+{{PROJECT_DESCRIPTION}}+` |One-line description |`+A tool for X+` +|flake.nix + +|`+{{PROJECT}}+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+{{REPO}}+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+{{OWNER}}+` |GitHub/GitLab org or username |`+my-org+` |SPDX headers, +CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, +mirror.yml, cliff.toml + +|`+{{FORGE}}+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{CURRENT_YEAR}}+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+{{CURRENT_DATE}}+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+{{DATE}}+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{SECURITY_EMAIL}}+` |Security contact email +|`+security@example.org+` |SECURITY.md + +|`+{{PGP_FINGERPRINT}}+` |40-char PGP fingerprint |`+ABCD 1234 ...+` +|SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{MAIN_BRANCH}}+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{LICENSE}}+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+{{PROJECT_PURPOSE}}+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/packages/PRComms.jl/PLACEHOLDERS.md b/packages/PRComms.jl/PLACEHOLDERS.md deleted file mode 100644 index b6c9d28cc..000000000 --- a/packages/PRComms.jl/PLACEHOLDERS.md +++ /dev/null @@ -1,120 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/packages/PRComms.jl/SECURITY.adoc b/packages/PRComms.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/PRComms.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/PRComms.jl/SECURITY.md b/packages/PRComms.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/PRComms.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/PRComms.jl/TOPOLOGY.md b/packages/PRComms.jl/TOPOLOGY.adoc similarity index 89% rename from packages/PRComms.jl/TOPOLOGY.md rename to packages/PRComms.jl/TOPOLOGY.adoc index 344048e20..a8a69f262 100644 --- a/packages/PRComms.jl/TOPOLOGY.md +++ b/packages/PRComms.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== PRComms.jl — Project Topology -# PRComms.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / CHANNELS │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE OPERATIONS @@ -67,26 +63,27 @@ INSIGHTS & INTEROP ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Operational Beta -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Message Pillars ──────► Newsroom Workflow ──────► Publication │ Strategy Planning ──────► Campaign Coord ────────┤ │ Crisis Playbooks ───────► Risk Gating ───────────► COMPLETE -``` +.... -## 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/packages/PRComms.jl/docs/AI-CONVENTIONS.adoc b/packages/PRComms.jl/docs/AI-CONVENTIONS.adoc new file mode 100644 index 000000000..ba7e4ae74 --- /dev/null +++ b/packages/PRComms.jl/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,81 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *\{\{AUTHOR}}* +* Email: *\{\{AUTHOR_EMAIL}}* +* Copyright: +`+Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>+` + +=== State Files + +State/metadata files (.a2ml) belong in `+.machine_readable/+` ONLY. +NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, +NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state diff --git a/packages/PRComms.jl/docs/AI-CONVENTIONS.md b/packages/PRComms.jl/docs/AI-CONVENTIONS.md deleted file mode 100644 index 37f594d12..000000000 --- a/packages/PRComms.jl/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,75 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state diff --git a/packages/PRComms.jl/docs/QUICKSTART.adoc b/packages/PRComms.jl/docs/QUICKSTART.adoc new file mode 100644 index 000000000..f000d4a13 --- /dev/null +++ b/packages/PRComms.jl/docs/QUICKSTART.adoc @@ -0,0 +1,70 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/{{REPO}}.git +cd {{REPO}} +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +if you get stuck. diff --git a/packages/PRComms.jl/docs/QUICKSTART.md b/packages/PRComms.jl/docs/QUICKSTART.md deleted file mode 100644 index 724d8e111..000000000 --- a/packages/PRComms.jl/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/{{OWNER}}/{{REPO}}.git -cd {{REPO}} -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/{{OWNER}}/{{REPO}}/discussions) -if you get stuck. diff --git a/packages/PRComms.jl/docs/THREAT-MODEL.adoc b/packages/PRComms.jl/docs/THREAT-MODEL.adoc new file mode 100644 index 000000000..35aa8cc8e --- /dev/null +++ b/packages/PRComms.jl/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: \{\{PROJECT_NAME}} + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |\{\{PROJECT_NAME}} +|Version |1.0 +|Last Reviewed |\{\{DATE}} +|Author |\{\{AUTHOR}} +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of \{\{PROJECT_NAME}} and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/packages/PRComms.jl/docs/THREAT-MODEL.md b/packages/PRComms.jl/docs/THREAT-MODEL.md deleted file mode 100644 index c33fe79d8..000000000 --- a/packages/PRComms.jl/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/packages/PRComms.jl/docs/decisions/0000-template.adoc b/packages/PRComms.jl/docs/decisions/0000-template.adoc new file mode 100644 index 000000000..de603adff --- /dev/null +++ b/packages/PRComms.jl/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/packages/PRComms.jl/docs/decisions/0000-template.md b/packages/PRComms.jl/docs/decisions/0000-template.md deleted file mode 100644 index 2f7fc67de..000000000 --- a/packages/PRComms.jl/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/packages/PRComms.jl/docs/decisions/0001-adopt-rsr-standard.adoc b/packages/PRComms.jl/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 000000000..8e404cbbc --- /dev/null +++ b/packages/PRComms.jl/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/packages/PRComms.jl/docs/decisions/0001-adopt-rsr-standard.md b/packages/PRComms.jl/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index 806942f67..000000000 --- a/packages/PRComms.jl/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/packages/PRComms.jl/docs/decisions/README.adoc b/packages/PRComms.jl/docs/decisions/README.adoc new file mode 100644 index 000000000..3dc7a4856 --- /dev/null +++ b/packages/PRComms.jl/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/packages/PRComms.jl/docs/decisions/README.md b/packages/PRComms.jl/docs/decisions/README.md deleted file mode 100644 index 79851eea4..000000000 --- a/packages/PRComms.jl/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/packages/PolyglotFormalisms.jl/ABI-FFI-README.adoc b/packages/PolyglotFormalisms.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..8e5244189 --- /dev/null +++ b/packages/PolyglotFormalisms.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/PolyglotFormalisms.jl/ABI-FFI-README.md b/packages/PolyglotFormalisms.jl/ABI-FFI-README.md deleted file mode 100644 index 08d35da64..000000000 --- a/packages/PolyglotFormalisms.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/PolyglotFormalisms.jl/CODE_OF_CONDUCT.adoc b/packages/PolyglotFormalisms.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/PolyglotFormalisms.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/PolyglotFormalisms.jl/CODE_OF_CONDUCT.md b/packages/PolyglotFormalisms.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/PolyglotFormalisms.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/PolyglotFormalisms.jl/CONTRIBUTING.adoc b/packages/PolyglotFormalisms.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..84cc9e8df --- /dev/null +++ b/packages/PolyglotFormalisms.jl/CONTRIBUTING.adoc @@ -0,0 +1,58 @@ +== Contributing to PolyglotFormalisms.jl + +Thank you for your interest in contributing to PolyglotFormalisms.jl! + +=== How to Contribute + +[arabic] +. *Report Issues*: Found a bug or have a feature request? Open an issue +on GitHub. +. *Submit Pull Requests*: +* Fork the repository +* Create a feature branch +* Make your changes +* Ensure all tests pass: +`+julia --project=. -e 'using Pkg; Pkg.test()'+` +* Submit a pull request + +=== Guidelines + +==== Implementation Requirements + +[arabic] +. *Match aLib Specifications*: All implementations must exactly match +the +https://github.com/hyperpolymath/aggregate-library[aggregate-library] +specifications. +. *Include Tests*: Every function must have conformance tests matching +the aLib spec test cases. +. *Document Properties*: Document all mathematical properties +(commutativity, associativity, etc.) in docstrings. +. *Formal Verification*: When Axiom.jl integration is complete, +properties should be proven with `+@prove+` macros. + +==== Code Style + +* Follow standard Julia style conventions +* Use descriptive variable names +* Include SPDX license headers +* Write clear docstrings with examples + +==== Testing + +All tests must pass before merging: + +[source,bash] +---- +julia --project=. -e 'using Pkg; Pkg.test()' +---- + +==== Commit Messages + +Use conventional commits format: - `+feat:+` for new features - `+fix:+` +for bug fixes - `+docs:+` for documentation changes - `+test:+` for test +additions/modifications + +=== Questions? + +Open a GitHub issue or discussion for any questions about contributing. diff --git a/packages/PolyglotFormalisms.jl/CONTRIBUTING.md b/packages/PolyglotFormalisms.jl/CONTRIBUTING.md deleted file mode 100644 index aa2ad5a77..000000000 --- a/packages/PolyglotFormalisms.jl/CONTRIBUTING.md +++ /dev/null @@ -1,53 +0,0 @@ -# Contributing to PolyglotFormalisms.jl - -Thank you for your interest in contributing to PolyglotFormalisms.jl! - -## How to Contribute - -1. **Report Issues**: Found a bug or have a feature request? Open an issue on GitHub. - -2. **Submit Pull Requests**: - - Fork the repository - - Create a feature branch - - Make your changes - - Ensure all tests pass: `julia --project=. -e 'using Pkg; Pkg.test()'` - - Submit a pull request - -## Guidelines - -### Implementation Requirements - -1. **Match aLib Specifications**: All implementations must exactly match the [aggregate-library](https://github.com/hyperpolymath/aggregate-library) specifications. - -2. **Include Tests**: Every function must have conformance tests matching the aLib spec test cases. - -3. **Document Properties**: Document all mathematical properties (commutativity, associativity, etc.) in docstrings. - -4. **Formal Verification**: When Axiom.jl integration is complete, properties should be proven with `@prove` macros. - -### Code Style - -- Follow standard Julia style conventions -- Use descriptive variable names -- Include SPDX license headers -- Write clear docstrings with examples - -### Testing - -All tests must pass before merging: - -```bash -julia --project=. -e 'using Pkg; Pkg.test()' -``` - -### Commit Messages - -Use conventional commits format: -- `feat:` for new features -- `fix:` for bug fixes -- `docs:` for documentation changes -- `test:` for test additions/modifications - -## Questions? - -Open a GitHub issue or discussion for any questions about contributing. diff --git a/packages/PolyglotFormalisms.jl/README.adoc b/packages/PolyglotFormalisms.jl/README.adoc index b4d454dd0..8be52b80f 100644 --- a/packages/PolyglotFormalisms.jl/README.adoc +++ b/packages/PolyglotFormalisms.jl/README.adoc @@ -1,146 +1,351 @@ -= PolyglotFormalisms.jl +== PolyglotFormalisms.jl -**Cross-Language Formal Verification in Julia** +*Julia reference implementation of the aggregate-library +(PolyglotFormalisms) Common Library with formal verification.* -*Julia reference implementation of aggregate-library with formal verification, designed for cross (programming) language verification.* +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-100%25-green[Completion +Status]] -== What is PolyglotFormalisms.jl? +image:https://img.shields.io/badge/License-MPL–2.0-blue.svg[License: +PMPL-1.0,link="`https://github.com/hyperpolymath/palimpsest-license`"] +link:[image:https://img.shields.io/badge/tests-422%20passing-brightgreen.svg[Tests: +Passing]] -PolyglotFormalisms.jl is a **Julia-based framework** for building and verifying formal specifications across multiple programming languages. It enables: +=== Overview -- **Cross-language formal verification**: Prove properties about code written in different languages. -- **Aggregate library design**: Reuse verified components across Julia, Idris2, Zig, and more. -- **ABI/FFI standards compliance**: Seamless integration with foreign function interfaces. -- **Mathematical guarantees**: Compile-time proofs for memory safety, type correctness, and interface compliance. +PolyglotFormalisms.jl provides formally verified implementations of the +minimal overlap functions specified in the +https://github.com/hyperpolymath/aggregate-library[aggregate-library] +project. This package serves as a Julia reference implementation for +cross-language semantic equivalence verification. + +=== Why PolyglotFormalisms.jl? + +The aggregate-library defines a minimal intersection of functionality +across radically different programming languages. PolyglotFormalisms.jl +adds value by: + +[arabic] +. *Formal Verification*: Mathematical properties are proven using +Axiom.jl’s `+@prove+` macro (planned) +. *Reference Implementation*: Serves as a semantically verified baseline +for other language implementations +. *Conformance Testing*: Test suite exactly matches PolyglotFormalisms +specifications +. *Cross-Language Bridge*: Enables verification that ReScript, Gleam, +Elixir implementations satisfy the same properties + +=== Installation [source,julia] ---- -using PolyglotFormalisms +using Pkg +Pkg.add("PolyglotFormalisms") +---- -# Define a verified interface -@formal interface SafeDOM - function mount(element::String, content::String) :: Bool - @ensure element ≠ "" && content ≠ "" - @prove ∀x. mount(x, "") == false - end -end +=== Usage -# Generate bindings for other languages -generate_bindings(SafeDOM, languages=[:zig, :idris]) +[source,julia] ---- +using PolyglotFormalisms -== Features - -=== Cross-Language Verification +# Arithmetic operations +Arithmetic.add(2, 3) # 5 +Arithmetic.subtract(10, 3) # 7 +Arithmetic.multiply(4, 5) # 20 +Arithmetic.divide(10, 2) # 5.0 +Arithmetic.modulo(10, 3) # 1 + +# Comparison operations +Comparison.less_than(2, 3) # true +Comparison.equal(5, 5) # true + +# Collection operations +Collection.map_items(x -> x^2, [1, 2, 3]) # [1, 4, 9] +Collection.filter_items(iseven, [1, 2, 3, 4]) # [2, 4] +Collection.fold_items(+, 0, [1, 2, 3]) # 6 + +# Conditional operations +Conditional.if_then_else(true, "yes", "no") # "yes" +Conditional.coalesce(nothing, nothing, 42) # 42 +Conditional.clamp_value(15, 0, 10) # 10 +---- -Verify properties across language boundaries: +=== Modules + +==== Arithmetic (5 operations) + +[cols=",",options="header",] +|=== +|Function |Description +|`+add(a, b)+` |Sum of two numbers +|`+subtract(a, b)+` |Difference of two numbers +|`+multiply(a, b)+` |Product of two numbers +|`+divide(a, b)+` |Quotient of two numbers +|`+modulo(a, b)+` |Remainder of division +|=== + +*Verified properties:* commutativity, associativity, identity, zero +element, distributivity. + +==== Comparison (6 operations) + +[cols=",",options="header",] +|=== +|Function |Description +|`+less_than(a, b)+` |a < b +|`+greater_than(a, b)+` |a > b +|`+equal(a, b)+` |a == b +|`+not_equal(a, b)+` |a != b +|`+less_equal(a, b)+` |a <= b +|`+greater_equal(a, b)+` |a >= b +|=== + +*Verified properties:* trichotomy, transitivity, reflexivity (for +`+equal+`, `+less_equal+`, `+greater_equal+`), antisymmetry. + +==== Logical (3 operations) + +[cols=",",options="header",] +|=== +|Function |Description +|`+and(a, b)+` |Logical conjunction +|`+or(a, b)+` |Logical disjunction +|`+not(a)+` |Logical negation +|=== + +*Verified properties:* commutativity, associativity, identity, De +Morgan’s laws, double negation, excluded middle. + +==== StringOps (14 operations) + +[cols=",",options="header",] +|=== +|Function |Description +|`+concat(a, b)+` |Concatenate two strings +|`+length(s)+` |String length +|`+substring(s, start, end_pos)+` |Extract substring +|`+index_of(s, substr)+` |Find first occurrence (0 if not found) +|`+contains(s, substr)+` |Check if string contains substring +|`+starts_with(s, prefix)+` |Check prefix +|`+ends_with(s, suffix)+` |Check suffix +|`+to_uppercase(s)+` |Convert to uppercase +|`+to_lowercase(s)+` |Convert to lowercase +|`+trim(s)+` |Remove leading/trailing whitespace +|`+split(s, delimiter)+` |Split string by delimiter +|`+join(parts, separator)+` |Join strings with separator +|`+replace(s, old, new)+` |Replace occurrences of substring +|`+is_empty(s)+` |Check if string is empty +|=== + +*Verified properties:* concat associativity, concat identity, length +non-negativity, split/join roundtrip, trim idempotence. + +==== Collection (13 operations) + +[cols=",",options="header",] +|=== +|Function |Description +|`+map_items(f, coll)+` |Apply function to each element +|`+filter_items(pred, coll)+` |Keep elements matching predicate +|`+fold_items(f, init, coll)+` |Left-fold with accumulator +|`+zip_items(a, b)+` |Pair elements positionally +|`+flat_map_items(f, coll)+` |Map and flatten results +|`+group_by(key_fn, coll)+` |Group elements by key function +|`+sort_by(compare_fn, coll)+` |Stable sort by comparison function +|`+unique_items(coll)+` |Remove duplicates (preserve order) +|`+partition_items(pred, coll)+` |Split into (matching, non-matching) +|`+take_items(n, coll)+` |Take first n elements +|`+drop_items(n, coll)+` |Drop first n elements +|`+any_item(pred, coll)+` |True if any element matches +|`+all_items(pred, coll)+` |True if all elements match +|=== + +*Verified properties:* functor identity (`+map id = id+`), functor +composition, filter/partition consistency, fold universality, take/drop +complementarity, De Morgan duality (`+any+`/`+all+`). + +==== Conditional (5 operations) + +[cols=",",options="header",] +|=== +|Function |Description +|`+if_then_else(pred, then_val, else_val)+` |Total ternary conditional +|`+when(pred, val)+` |Conditional value (`+Some+` or `+nothing+`) +|`+unless(pred, val)+` |Inverse conditional value +|`+coalesce(values...)+` |First non-nothing value +|`+clamp_value(x, lo, hi)+` |Clamp number to range [lo, hi] +|=== + +*Verified properties:* if_then_else totality, when/unless duality, +coalesce idempotence, clamp boundary conditions, clamp idempotence +within range. + +=== Conformance Testing + +Test suite exactly matches the PolyglotFormalisms specification test +cases: [source,julia] ---- -@formal contract SafeMemory - function allocate(size::Int) :: Ptr - @ensure size > 0 - @prove ∀s. s > 0 ⇒ allocate(s) ≠ C_NULL - end -end +using Test +using PolyglotFormalisms -# Generate Idris2 and Zig bindings -generate_abi(SafeMemory, "memory_abi.h") +@testset "PolyglotFormalisms Conformance" begin + # Test cases from specs/arithmetic/add.md + @test Arithmetic.add(2, 3) == 5 + @test Arithmetic.add(-5, 3) == -2 + @test Arithmetic.add(0, 0) == 0 + @test Arithmetic.add(1.5, 2.5) == 4.0 + @test Arithmetic.add(-10, -20) == -30 + + # Property verification + @test Arithmetic.add(5, 3) == Arithmetic.add(3, 5) # Commutativity + @test Arithmetic.add(Arithmetic.add(2, 3), 4) == Arithmetic.add(2, Arithmetic.add(3, 4)) # Associativity +end ---- -=== ABI/FFI Standards +Run full test suite: -All foreign function interfaces follow the **Hyperpolymath Universal Standard**: +[source,bash] +---- +julia --project=. -e 'using Pkg; Pkg.test()' +---- -- **Idris2**: Type definitions with dependent type proofs. -- **Zig**: C-compatible, memory-safe implementations. -- **Auto-generated C headers**: Bridge between Idris2 and Zig. +=== Integration with Axiom.jl -=== Directory Structure +When Axiom.jl is available as a dependency, formal proofs will be +automatically verified at compile time: -[source] +[source,julia] ---- -project/ -├── src/abi/ # Idris2 ABI definitions -├── ffi/zig/ # Zig FFI implementation -├── generated/abi/ # Auto-generated C headers -└── bindings/ # Language-specific wrappers +# Future integration: +@prove forall(a, b) do add(a, b) == add(b, a) end +@prove forall(a, b, c) do add(add(a, b), c) == add(a, add(b, c)) end +@prove forall(a) do add(a, 0) == a end ---- -=== AI CLI Integration +This enables: - *Compile-time verification* of mathematical properties - +*Automatic error detection* if implementations violate proven properties +- *Formal certificates* proving correctness for safety-critical +applications -- Use `ai-cli-crash-capture/` for automated verification. -- Mirror 6SCM files into `.machine_readable/`. -- Check `/var$REPOS_DIR/proven` for "unbreakable" Idris libraries. +=== Cross-Language Verification -== Quick Start +PolyglotFormalisms.jl serves as a formally verified reference for +semantic equivalence checking: -=== Installation +[arabic] +. *Implement in target language* (ReScript, Gleam, Elixir) +. *Run PolyglotFormalisms conformance tests* in both languages +. *Use Axiom.jl + SMTLib.jl* to prove semantic equivalence +. *Generate verification certificate* + +Example verification workflow: [source,julia] ---- -using Pkg -Pkg.add("PolyglotFormalisms") +using PolyglotFormalisms +using Axiom +using SMTLib + +# Verify ReScript implementation semantically equivalent to Julia +verify_equivalence( + julia_impl = Arithmetic.add, + rescript_impl = RescriptFFI.add, + properties = [commutativity, associativity, identity] +) ---- -=== Hello World +=== Design Philosophy -[source,julia] ----- -using PolyglotFormalisms +This implementation follows the PolyglotFormalisms specification +philosophy: - *Minimal intersection*: Only functions that work across +all target languages - *Clear semantics*: Unambiguous behavioral +specifications - *Testable*: Executable test cases for every operation - +*Provable*: Mathematical properties verified with formal methods - +*Extensible*: Each ecosystem extends through its standard library -# Define a verified interface -@formal interface MathOps - function add(a::Int, b::Int) :: Int - @ensure add(a, b) == a + b - end -end +=== Related Projects -# Generate bindings -generate_bindings(MathOps, languages=[:zig]) ----- +* https://github.com/hyperpolymath/aggregate-library[aggregate-library] +- PolyglotFormalisms specification +* https://github.com/hyperpolymath/alib-for-rescript[alib-for-rescript] +- ReScript implementation +* https://github.com/hyperpolymath/Axiom.jl[Axiom.jl] - Formal +verification for ML models +* https://github.com/hyperpolymath/SMTLib.jl[SMTLib.jl] - SMT solver +integration for Julia -== Why PolyglotFormalisms.jl? +=== References & Bibliography -=== The Problem +==== Type Theory & Formal Semantics -Cross-language projects often suffer from: -- Undetected memory errors -- Type mismatches at runtime -- Unverified foreign function interfaces +* Pierce, B.C. _Types and Programming Languages_. MIT Press, 2002. – +Type systems, operational and denotational semantics. +* Winskel, G. _The Formal Semantics of Programming Languages: An +Introduction_. MIT Press, 1993. – Denotational, operational, and +axiomatic semantics. +* Cardelli, L. & Wegner, P. "`On Understanding Types, Data Abstraction, +and Polymorphism.`" _Computing Surveys_ 17(4), 1985, pp. 471-523. – Type +theory foundations for programming languages. -=== The Solution +==== Category Theory & Algebraic Properties -PolyglotFormalisms.jl provides: -| Issue | Traditional FFI | PolyglotFormalisms.jl | -|----------------------|-----------------|-----------------------| -| Memory safety | Runtime crashes | Compile-time proofs | -| Type correctness | Manual checks | Dependent types | -| Interface compliance | Ad-hoc testing | Formal verification | +* Mac Lane, S. _Categories for the Working Mathematician_. 2nd ed., +Graduate Texts in Mathematics 5, Springer, 1998. – Category theory +foundations (functors, natural transformations, monads). +* Milewski, B. _Category Theory for Programmers_. 2019. – Functor and +monad laws applied to programming. +* Bird, R. & de Moor, O. _Algebra of Programming_. Prentice Hall, 1997. +– Fold/map fusion laws, program calculation. +* Dummit, D.S. & Foote, R.M. _Abstract Algebra_. 3rd ed., Wiley, 2004. – +Algebraic structures (groups, rings, fields) underlying arithmetic +properties. -== Project Structure +==== Parametricity & Free Theorems -[source] ----- -PolyglotFormalisms.jl/ -├── src/ # Julia source -│ ├── abi/ # ABI definitions -│ ├── ffi/ # FFI implementations -│ └── verification/ # Proof system -├── generated/ # Auto-generated headers -└── bindings/ # Language wrappers ----- +* Wadler, P. "`Theorems for free!`" In _Proceedings of FPCA ’89_, ACM, +1989, pp. 347-359. – Parametric polymorphism and free theorems from +types. + +==== Standards + +* IEEE 754-2019. _IEEE Standard for Floating-Point Arithmetic_. IEEE, +2019. – NaN/Inf handling, rounding modes, division by zero semantics. + +=== Contributing + +Contributions welcome! Please ensure: 1. Implementations match +PolyglotFormalisms specifications exactly 2. All test cases from +PolyglotFormalisms specs are included 3. Properties are documented (and +proven when Axiom.jl integration is complete) 4. Tests pass: +`+julia --project=. -e 'using Pkg; Pkg.test()'+` + +=== License + +MPL-2.0 (Palimpsest Meta-Public License) + +=== Status + +*Current*: 6 modules implemented, 422 passing tests. -== Roadmap +[cols=",,",options="header",] +|=== +|Module |Operations |Status +|Arithmetic |5 |Complete +|Comparison |6 |Complete +|Logical |3 |Complete +|StringOps |14 |Complete +|Collection |13 |Complete +|Conditional |5 |Complete +|=== -- ✅ **v0.1**: Core framework, Idris2/Zig integration -- ⬜ **v0.2**: Expanded language support (Rust, ReScript) -- ⬜ **v0.3**: Advanced proof automation -- ⬜ **v1.0**: Industry-ready certification +*Planned*: Axiom.jl integration for compile-time formal proofs. -== Acknowledgments +''''' -Built on: -- Idris2 for dependent types -- Zig for memory safety -- Julia for expressive DSLs +*Hyperpolymath Ecosystem* - Multi-language, formally verified, +semantically equivalent. diff --git a/packages/PolyglotFormalisms.jl/README.md b/packages/PolyglotFormalisms.jl/README.md deleted file mode 100644 index fc7350be0..000000000 --- a/packages/PolyglotFormalisms.jl/README.md +++ /dev/null @@ -1,282 +0,0 @@ -# PolyglotFormalisms.jl - -**Julia reference implementation of the aggregate-library (PolyglotFormalisms) Common Library with formal verification.** - -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-100%25-green)](TOPOLOGY.md) - -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -[![Tests: Passing](https://img.shields.io/badge/tests-422%20passing-brightgreen.svg)]() - -## Overview - -PolyglotFormalisms.jl provides formally verified implementations of the minimal overlap functions specified in the [aggregate-library](https://github.com/hyperpolymath/aggregate-library) project. This package serves as a Julia reference implementation for cross-language semantic equivalence verification. - -## Why PolyglotFormalisms.jl? - -The aggregate-library defines a minimal intersection of functionality across radically different programming languages. PolyglotFormalisms.jl adds value by: - -1. **Formal Verification**: Mathematical properties are proven using Axiom.jl's `@prove` macro (planned) -2. **Reference Implementation**: Serves as a semantically verified baseline for other language implementations -3. **Conformance Testing**: Test suite exactly matches PolyglotFormalisms specifications -4. **Cross-Language Bridge**: Enables verification that ReScript, Gleam, Elixir implementations satisfy the same properties - -## Installation - -```julia -using Pkg -Pkg.add("PolyglotFormalisms") -``` - -## Usage - -```julia -using PolyglotFormalisms - -# Arithmetic operations -Arithmetic.add(2, 3) # 5 -Arithmetic.subtract(10, 3) # 7 -Arithmetic.multiply(4, 5) # 20 -Arithmetic.divide(10, 2) # 5.0 -Arithmetic.modulo(10, 3) # 1 - -# Comparison operations -Comparison.less_than(2, 3) # true -Comparison.equal(5, 5) # true - -# Collection operations -Collection.map_items(x -> x^2, [1, 2, 3]) # [1, 4, 9] -Collection.filter_items(iseven, [1, 2, 3, 4]) # [2, 4] -Collection.fold_items(+, 0, [1, 2, 3]) # 6 - -# Conditional operations -Conditional.if_then_else(true, "yes", "no") # "yes" -Conditional.coalesce(nothing, nothing, 42) # 42 -Conditional.clamp_value(15, 0, 10) # 10 -``` - -## Modules - -### Arithmetic (5 operations) - -| Function | Description | -|----------|-------------| -| `add(a, b)` | Sum of two numbers | -| `subtract(a, b)` | Difference of two numbers | -| `multiply(a, b)` | Product of two numbers | -| `divide(a, b)` | Quotient of two numbers | -| `modulo(a, b)` | Remainder of division | - -**Verified properties:** commutativity, associativity, identity, zero element, distributivity. - -### Comparison (6 operations) - -| Function | Description | -|----------|-------------| -| `less_than(a, b)` | a < b | -| `greater_than(a, b)` | a > b | -| `equal(a, b)` | a == b | -| `not_equal(a, b)` | a != b | -| `less_equal(a, b)` | a <= b | -| `greater_equal(a, b)` | a >= b | - -**Verified properties:** trichotomy, transitivity, reflexivity (for `equal`, `less_equal`, `greater_equal`), antisymmetry. - -### Logical (3 operations) - -| Function | Description | -|----------|-------------| -| `and(a, b)` | Logical conjunction | -| `or(a, b)` | Logical disjunction | -| `not(a)` | Logical negation | - -**Verified properties:** commutativity, associativity, identity, De Morgan's laws, double negation, excluded middle. - -### StringOps (14 operations) - -| Function | Description | -|----------|-------------| -| `concat(a, b)` | Concatenate two strings | -| `length(s)` | String length | -| `substring(s, start, end_pos)` | Extract substring | -| `index_of(s, substr)` | Find first occurrence (0 if not found) | -| `contains(s, substr)` | Check if string contains substring | -| `starts_with(s, prefix)` | Check prefix | -| `ends_with(s, suffix)` | Check suffix | -| `to_uppercase(s)` | Convert to uppercase | -| `to_lowercase(s)` | Convert to lowercase | -| `trim(s)` | Remove leading/trailing whitespace | -| `split(s, delimiter)` | Split string by delimiter | -| `join(parts, separator)` | Join strings with separator | -| `replace(s, old, new)` | Replace occurrences of substring | -| `is_empty(s)` | Check if string is empty | - -**Verified properties:** concat associativity, concat identity, length non-negativity, split/join roundtrip, trim idempotence. - -### Collection (13 operations) - -| Function | Description | -|----------|-------------| -| `map_items(f, coll)` | Apply function to each element | -| `filter_items(pred, coll)` | Keep elements matching predicate | -| `fold_items(f, init, coll)` | Left-fold with accumulator | -| `zip_items(a, b)` | Pair elements positionally | -| `flat_map_items(f, coll)` | Map and flatten results | -| `group_by(key_fn, coll)` | Group elements by key function | -| `sort_by(compare_fn, coll)` | Stable sort by comparison function | -| `unique_items(coll)` | Remove duplicates (preserve order) | -| `partition_items(pred, coll)` | Split into (matching, non-matching) | -| `take_items(n, coll)` | Take first n elements | -| `drop_items(n, coll)` | Drop first n elements | -| `any_item(pred, coll)` | True if any element matches | -| `all_items(pred, coll)` | True if all elements match | - -**Verified properties:** functor identity (`map id = id`), functor composition, filter/partition consistency, fold universality, take/drop complementarity, De Morgan duality (`any`/`all`). - -### Conditional (5 operations) - -| Function | Description | -|----------|-------------| -| `if_then_else(pred, then_val, else_val)` | Total ternary conditional | -| `when(pred, val)` | Conditional value (`Some` or `nothing`) | -| `unless(pred, val)` | Inverse conditional value | -| `coalesce(values...)` | First non-nothing value | -| `clamp_value(x, lo, hi)` | Clamp number to range [lo, hi] | - -**Verified properties:** if_then_else totality, when/unless duality, coalesce idempotence, clamp boundary conditions, clamp idempotence within range. - -## Conformance Testing - -Test suite exactly matches the PolyglotFormalisms specification test cases: - -```julia -using Test -using PolyglotFormalisms - -@testset "PolyglotFormalisms Conformance" begin - # Test cases from specs/arithmetic/add.md - @test Arithmetic.add(2, 3) == 5 - @test Arithmetic.add(-5, 3) == -2 - @test Arithmetic.add(0, 0) == 0 - @test Arithmetic.add(1.5, 2.5) == 4.0 - @test Arithmetic.add(-10, -20) == -30 - - # Property verification - @test Arithmetic.add(5, 3) == Arithmetic.add(3, 5) # Commutativity - @test Arithmetic.add(Arithmetic.add(2, 3), 4) == Arithmetic.add(2, Arithmetic.add(3, 4)) # Associativity -end -``` - -Run full test suite: -```bash -julia --project=. -e 'using Pkg; Pkg.test()' -``` - -## Integration with Axiom.jl - -When Axiom.jl is available as a dependency, formal proofs will be automatically verified at compile time: - -```julia -# Future integration: -@prove forall(a, b) do add(a, b) == add(b, a) end -@prove forall(a, b, c) do add(add(a, b), c) == add(a, add(b, c)) end -@prove forall(a) do add(a, 0) == a end -``` - -This enables: -- **Compile-time verification** of mathematical properties -- **Automatic error detection** if implementations violate proven properties -- **Formal certificates** proving correctness for safety-critical applications - -## Cross-Language Verification - -PolyglotFormalisms.jl serves as a formally verified reference for semantic equivalence checking: - -1. **Implement in target language** (ReScript, Gleam, Elixir) -2. **Run PolyglotFormalisms conformance tests** in both languages -3. **Use Axiom.jl + SMTLib.jl** to prove semantic equivalence -4. **Generate verification certificate** - -Example verification workflow: -```julia -using PolyglotFormalisms -using Axiom -using SMTLib - -# Verify ReScript implementation semantically equivalent to Julia -verify_equivalence( - julia_impl = Arithmetic.add, - rescript_impl = RescriptFFI.add, - properties = [commutativity, associativity, identity] -) -``` - -## Design Philosophy - -This implementation follows the PolyglotFormalisms specification philosophy: -- **Minimal intersection**: Only functions that work across all target languages -- **Clear semantics**: Unambiguous behavioral specifications -- **Testable**: Executable test cases for every operation -- **Provable**: Mathematical properties verified with formal methods -- **Extensible**: Each ecosystem extends through its standard library - -## Related Projects - -- [aggregate-library](https://github.com/hyperpolymath/aggregate-library) - PolyglotFormalisms specification -- [alib-for-rescript](https://github.com/hyperpolymath/alib-for-rescript) - ReScript implementation -- [Axiom.jl](https://github.com/hyperpolymath/Axiom.jl) - Formal verification for ML models -- [SMTLib.jl](https://github.com/hyperpolymath/SMTLib.jl) - SMT solver integration for Julia - -## References & Bibliography - -### Type Theory & Formal Semantics - -- Pierce, B.C. _Types and Programming Languages_. MIT Press, 2002. -- Type systems, operational and denotational semantics. -- Winskel, G. _The Formal Semantics of Programming Languages: An Introduction_. MIT Press, 1993. -- Denotational, operational, and axiomatic semantics. -- Cardelli, L. & Wegner, P. "On Understanding Types, Data Abstraction, and Polymorphism." _Computing Surveys_ 17(4), 1985, pp. 471-523. -- Type theory foundations for programming languages. - -### Category Theory & Algebraic Properties - -- Mac Lane, S. _Categories for the Working Mathematician_. 2nd ed., Graduate Texts in Mathematics 5, Springer, 1998. -- Category theory foundations (functors, natural transformations, monads). -- Milewski, B. _Category Theory for Programmers_. 2019. -- Functor and monad laws applied to programming. -- Bird, R. & de Moor, O. _Algebra of Programming_. Prentice Hall, 1997. -- Fold/map fusion laws, program calculation. -- Dummit, D.S. & Foote, R.M. _Abstract Algebra_. 3rd ed., Wiley, 2004. -- Algebraic structures (groups, rings, fields) underlying arithmetic properties. - -### Parametricity & Free Theorems - -- Wadler, P. "Theorems for free!" In _Proceedings of FPCA '89_, ACM, 1989, pp. 347-359. -- Parametric polymorphism and free theorems from types. - -### Standards - -- IEEE 754-2019. _IEEE Standard for Floating-Point Arithmetic_. IEEE, 2019. -- NaN/Inf handling, rounding modes, division by zero semantics. - -## Contributing - -Contributions welcome! Please ensure: -1. Implementations match PolyglotFormalisms specifications exactly -2. All test cases from PolyglotFormalisms specs are included -3. Properties are documented (and proven when Axiom.jl integration is complete) -4. Tests pass: `julia --project=. -e 'using Pkg; Pkg.test()'` - -## License - -MPL-2.0 (Palimpsest Meta-Public License) - -## Status - -**Current**: 6 modules implemented, 422 passing tests. - -| Module | Operations | Status | -|--------|-----------|--------| -| Arithmetic | 5 | Complete | -| Comparison | 6 | Complete | -| Logical | 3 | Complete | -| StringOps | 14 | Complete | -| Collection | 13 | Complete | -| Conditional | 5 | Complete | - -**Planned**: Axiom.jl integration for compile-time formal proofs. - ---- - -**Hyperpolymath Ecosystem** - Multi-language, formally verified, semantically equivalent. diff --git a/packages/PolyglotFormalisms.jl/ROADMAP.adoc b/packages/PolyglotFormalisms.jl/ROADMAP.adoc index b595ac16b..f4cd11312 100644 --- a/packages/PolyglotFormalisms.jl/ROADMAP.adoc +++ b/packages/PolyglotFormalisms.jl/ROADMAP.adoc @@ -1,36 +1,97 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Roadmap -:revdate: 2026-02-17 - -== Release Baseline (Must) -- Package installs from a clean Julia environment (`Pkg.add`). -- Precompile, build, test, and module load smoke are gated in CI. -- Versioning stays semver and aligned with release refs/tags. - -== V2 Backlog (Should) -- Expand CI matrix (OS + Julia versions + optional dependency modes). -- Add performance baselines and regression checks. -- Improve machine-readable evidence and release artifact metadata. - -== V2 Backlog (Could) -- Add deeper formal verification evidence exports. -- Add optional accelerator/hardware strategy tracks where relevant. -- Add richer diagnostics and fault-recovery instrumentation. - -== Future Horizons (v2.0+) - -=== Automated Semantic Equivalence -* [ ] **Cross-Language Proof Runner**: A unified dashboard that visualizes proof status across all `aggregate-library` implementations (Julia, ReScript, Elixir, etc.). -* [ ] **Implementation Synthesis**: Automatically generate "correct-by-construction" code in multiple languages from a single PolyglotFormalisms specification. - -=== Hardware-Level Formalisms -* [ ] **Instruction Set Alignment**: Formally verify that `Arithmetic` operations are correctly lowered to specific hardware (e.g., RISC-V) without introducing overflow or precision errors. -* [ ] **Formal Memory Models**: Define and prove cross-language memory consistency models for concurrent operations. - -=== Recursive Formalism -* [ ] **Verified Compiler Gates**: Use PolyglotFormalisms to verify the translation logic between different language IRs (Intermediate Representations). -* [ ] **Self-Verifying Registry**: A package registry where every implementation must provide a PolyglotFormalisms proof of compliance before acceptance. - -=== AI & Reasoning Formalisms -* [ ] **Neural Property Formalism**: Standardized, formally verified properties for describing neural network behavior (e.g., "Non-increasing monotonicity"). -* [ ] **Axiomatic Agent Logic**: Formal definitions for agent intent, value alignment, and safety boundaries (linking to `Axiology.jl`). +== PolyglotFormalisms.jl Development Roadmap + +=== Current State (v1.0) + +Formally verified Julia reference implementation of the +https://github.com/hyperpolymath/aggregate-library[aggregate-library] +common specification: - Core modules: Arithmetic, Comparison, Logical, +StringOps, Collection, Conditional. - 422+ passing conformance tests +matching the cross-language spec. - Semantic alignment with ReScript, +Gleam, and Elixir implementations. + +*Status:* Stable core implementation. High test coverage. Ready for +formal proof integration. + +''''' + +=== v1.1 - Formal Proof Integration (3-6 months) + +*MUST:* - [ ] *Axiom.jl Core Integration*: Add `+Axiom.jl+` as a +dependency and implement `+@prove+` blocks for all `+Arithmetic+` and +`+Comparison+` properties. - [ ] *Algebraic Property Verification*: +Formally prove commutativity, associativity, and identity laws for all +supported types. - [ ] *String Invariant Proofs*: Prove properties like +length non-negativity and split/join roundtrip consistency. + +*SHOULD:* - [ ] *SMT-LIB Evidence Export*: Generate machine-readable +SMT-LIB 2.0 proof obligations for each module. - [ ] *Proof Certificate +Generation*: Integrate with `+Axiom.jl+` to export signed verification +certificates for each release. - [ ] *Boundary Condition Verification*: +Formally verify behavior for edge cases (NaN, Inf, empty collections, +UTF-8 normalization). + +*COULD:* - [ ] *Collection Universality Proofs*: Prove the "`Free +Theorems`" for map/filter/fold operations using parametricity. - [ ] +*Equivalence Checking Bridge*: Tooling to run semantic equivalence +checks between Julia and ReScript/Elixir implementations via a shared +SMT backend. + +''''' + +=== v1.2 - Domain Expansion (6-12 months) + +*MUST:* - [ ] *Probabilistic Operations*: Add verified modules for +probabilistic arithmetic (linking to `+ZeroProb.jl+`). - [ ] *Causal +Logic Extension*: Add formalisms for causal necessity and sufficiency +(linking to `+Causals.jl+`). - [ ] *Error Handling Formalism*: Implement +a verified `+Result/Either+` type system that works consistently across +languages. + +*SHOULD:* - [ ] *DateTime Formalism*: A cross-language, formally +verified date and time manipulation module. - [ ] *JSON/Binary Schema +Verification*: Formally verified serialization and deserialization +against shared schemas. - [ ] *Network Protocol Formalism*: Verified +state machine definitions for common protocol headers. + +*COULD:* - [ ] *Graph/Topology Formalism*: Verified graph operations and +knot-theoretic invariants (linking to `+KnotTheory.jl+`). - [ ] +*Physics/Units Formalism*: Formally verified unit conversion and +dimensional analysis. + +''''' + +=== Future Horizons (v2.0+) + +==== Automated Semantic Equivalence + +* [ ] *Cross-Language Proof Runner*: A unified dashboard that visualizes +proof status across all `+aggregate-library+` implementations (Julia, +ReScript, Elixir, etc.). +* [ ] *Implementation Synthesis*: Automatically generate +"`correct-by-construction`" code in multiple languages from a single +PolyglotFormalisms specification. + +==== Hardware-Level Formalisms + +* [ ] *Instruction Set Alignment*: Formally verify that `+Arithmetic+` +operations are correctly lowered to specific hardware (e.g., RISC-V) +without introducing overflow or precision errors. +* [ ] *Formal Memory Models*: Define and prove cross-language memory +consistency models for concurrent operations. + +==== Recursive Formalism + +* [ ] *Verified Compiler Gates*: Use PolyglotFormalisms to verify the +translation logic between different language IRs (Intermediate +Representations). +* [ ] *Self-Verifying Registry*: A package registry where every +implementation must provide a PolyglotFormalisms proof of compliance +before acceptance. + +==== AI & Reasoning Formalisms + +* [ ] *Neural Property Formalism*: Standardized, formally verified +properties for describing neural network behavior (e.g., +"`Non-increasing monotonicity`"). +* [ ] *Axiomatic Agent Logic*: Formal definitions for agent intent, +value alignment, and safety boundaries (linking to `+Axiology.jl+`). diff --git a/packages/PolyglotFormalisms.jl/ROADMAP.md b/packages/PolyglotFormalisms.jl/ROADMAP.md deleted file mode 100644 index de20391c1..000000000 --- a/packages/PolyglotFormalisms.jl/ROADMAP.md +++ /dev/null @@ -1,66 +0,0 @@ -# PolyglotFormalisms.jl Development Roadmap - -## Current State (v1.0) - -Formally verified Julia reference implementation of the [aggregate-library](https://github.com/hyperpolymath/aggregate-library) common specification: -- Core modules: Arithmetic, Comparison, Logical, StringOps, Collection, Conditional. -- 422+ passing conformance tests matching the cross-language spec. -- Semantic alignment with ReScript, Gleam, and Elixir implementations. - -**Status:** Stable core implementation. High test coverage. Ready for formal proof integration. - ---- - -## v1.1 - Formal Proof Integration (3-6 months) - -**MUST:** -- [ ] **Axiom.jl Core Integration**: Add `Axiom.jl` as a dependency and implement `@prove` blocks for all `Arithmetic` and `Comparison` properties. -- [ ] **Algebraic Property Verification**: Formally prove commutativity, associativity, and identity laws for all supported types. -- [ ] **String Invariant Proofs**: Prove properties like length non-negativity and split/join roundtrip consistency. - -**SHOULD:** -- [ ] **SMT-LIB Evidence Export**: Generate machine-readable SMT-LIB 2.0 proof obligations for each module. -- [ ] **Proof Certificate Generation**: Integrate with `Axiom.jl` to export signed verification certificates for each release. -- [ ] **Boundary Condition Verification**: Formally verify behavior for edge cases (NaN, Inf, empty collections, UTF-8 normalization). - -**COULD:** -- [ ] **Collection Universality Proofs**: Prove the "Free Theorems" for map/filter/fold operations using parametricity. -- [ ] **Equivalence Checking Bridge**: Tooling to run semantic equivalence checks between Julia and ReScript/Elixir implementations via a shared SMT backend. - ---- - -## v1.2 - Domain Expansion (6-12 months) - -**MUST:** -- [ ] **Probabilistic Operations**: Add verified modules for probabilistic arithmetic (linking to `ZeroProb.jl`). -- [ ] **Causal Logic Extension**: Add formalisms for causal necessity and sufficiency (linking to `Causals.jl`). -- [ ] **Error Handling Formalism**: Implement a verified `Result/Either` type system that works consistently across languages. - -**SHOULD:** -- [ ] **DateTime Formalism**: A cross-language, formally verified date and time manipulation module. -- [ ] **JSON/Binary Schema Verification**: Formally verified serialization and deserialization against shared schemas. -- [ ] **Network Protocol Formalism**: Verified state machine definitions for common protocol headers. - -**COULD:** -- [ ] **Graph/Topology Formalism**: Verified graph operations and knot-theoretic invariants (linking to `KnotTheory.jl`). -- [ ] **Physics/Units Formalism**: Formally verified unit conversion and dimensional analysis. - ---- - -## Future Horizons (v2.0+) - -### Automated Semantic Equivalence -- [ ] **Cross-Language Proof Runner**: A unified dashboard that visualizes proof status across all `aggregate-library` implementations (Julia, ReScript, Elixir, etc.). -- [ ] **Implementation Synthesis**: Automatically generate "correct-by-construction" code in multiple languages from a single PolyglotFormalisms specification. - -### Hardware-Level Formalisms -- [ ] **Instruction Set Alignment**: Formally verify that `Arithmetic` operations are correctly lowered to specific hardware (e.g., RISC-V) without introducing overflow or precision errors. -- [ ] **Formal Memory Models**: Define and prove cross-language memory consistency models for concurrent operations. - -### Recursive Formalism -- [ ] **Verified Compiler Gates**: Use PolyglotFormalisms to verify the translation logic between different language IRs (Intermediate Representations). -- [ ] **Self-Verifying Registry**: A package registry where every implementation must provide a PolyglotFormalisms proof of compliance before acceptance. - -### AI & Reasoning Formalisms -- [ ] **Neural Property Formalism**: Standardized, formally verified properties for describing neural network behavior (e.g., "Non-increasing monotonicity"). -- [ ] **Axiomatic Agent Logic**: Formal definitions for agent intent, value alignment, and safety boundaries (linking to `Axiology.jl`). diff --git a/packages/PolyglotFormalisms.jl/SECURITY.adoc b/packages/PolyglotFormalisms.jl/SECURITY.adoc new file mode 100644 index 000000000..0569a2363 --- /dev/null +++ b/packages/PolyglotFormalisms.jl/SECURITY.adoc @@ -0,0 +1,31 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|0.1.x |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +If you discover a security vulnerability in PolyglotFormalisms.jl, +please report it by: + +[arabic] +. *Email*: j.d.a.jewell@open.ac.uk +. *GitHub Security Advisory*: Use the "`Security`" tab to report +privately + +Please include: - Description of the vulnerability - Steps to reproduce +- Potential impact - Suggested fix (if any) + +We aim to respond to security reports within 48 hours. + +=== Security Practices + +* All GitHub Actions are SHA-pinned to prevent supply chain attacks +* Dependencies are minimal (Test stdlib only) +* OpenSSF Scorecard runs weekly +* CodeQL analysis enabled diff --git a/packages/PolyglotFormalisms.jl/SECURITY.md b/packages/PolyglotFormalisms.jl/SECURITY.md deleted file mode 100644 index f36d9f341..000000000 --- a/packages/PolyglotFormalisms.jl/SECURITY.md +++ /dev/null @@ -1,29 +0,0 @@ -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| 0.1.x | :white_check_mark: | - -## Reporting a Vulnerability - -If you discover a security vulnerability in PolyglotFormalisms.jl, please report it by: - -1. **Email**: j.d.a.jewell@open.ac.uk -2. **GitHub Security Advisory**: Use the "Security" tab to report privately - -Please include: -- Description of the vulnerability -- Steps to reproduce -- Potential impact -- Suggested fix (if any) - -We aim to respond to security reports within 48 hours. - -## Security Practices - -- All GitHub Actions are SHA-pinned to prevent supply chain attacks -- Dependencies are minimal (Test stdlib only) -- OpenSSF Scorecard runs weekly -- CodeQL analysis enabled diff --git a/packages/PolyglotFormalisms.jl/SONNET-TASKS.adoc b/packages/PolyglotFormalisms.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..b34148ce4 --- /dev/null +++ b/packages/PolyglotFormalisms.jl/SONNET-TASKS.adoc @@ -0,0 +1,641 @@ +== SONNET-TASKS.md — PolyglotFormalisms.jl Completion Tasks + +____ +*Generated:* 2026-02-12 by Opus audit *Purpose:* Unambiguous +instructions for Sonnet to complete all stubs, TODOs, and placeholder +code. *Honest completion before this file:* 62% +____ + +The code that exists (Arithmetic, Comparison, Logical, StringOps) is +functional and well-documented. However: two modules are entirely +missing (Collection, Conditional), the String module has a typo-bug, +STATE.scm claims String is 0% complete when it is actually implemented +and tested, the README.md is stale (claims modules are "`Planned`" that +already exist), the ABI/FFI layer is entirely unsubstituted template +placeholders, and there is a SPDX license violation in three files. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this entire file before starting any task. +. Do tasks in order listed. Earlier tasks unblock later ones. +. After each task, run the verification command. If it fails, fix before +moving on. +. Do NOT mark done unless verification passes. +. Update `+.machine_readable/STATE.scm+` with honest completion +percentages after each task. +. Commit after each task: `+fix(component): complete +` +. Run full test suite after every 3 tasks. + +''''' + +=== TASK 1: Fix StringOps module closing comment typo (CRITICAL) + +*File:* `+/var$REPOS_DIR/PolyglotFormalisms.jl/src/string.jl+` *Line:* +390 + +The module closing comment reads `+end # module StringOpsOps+` but the +module is named `+StringOps+`. This is a copy-paste typo that will +confuse tooling and developers. + +*Action:* Change line 390 from: + +[source,julia] +---- +end # module StringOpsOps +---- + +to: + +[source,julia] +---- +end # module StringOps +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep -n "StringOpsOps" src/string.jl +# Expected: no output (zero matches) +grep -n "end # module StringOps$" src/string.jl +# Expected: exactly one match at line 390 +---- + +''''' + +=== TASK 2: Fix SPDX license headers in ABI/FFI template files (CRITICAL) + +Three files use `+AGPL-3.0-or-later+` instead of `+MPL-2.0+`. Per +CLAUDE.md policy, AGPL-3.0 is the OLD license and must NEVER be used. + +*Files to fix:* 1. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/src/main.zig+` — line 6 +2. `+/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/build.zig+` — line 2 +3. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/test/integration_test.zig+` +— line 2 + +*Also fix:* 4. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/examples/SafeDOMExample.res+` — +line 1 + +*Action:* In each file, replace: + +.... +SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +with: + +.... +SPDX-License-Identifier: CC-BY-SA-4.0 +.... + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep -rn "AGPL" ffi/ examples/ src/abi/ +# Expected: no output (zero matches) +grep -rn "MPL-2.0" ffi/ examples/ +# Expected: 4 matches (one per file) +---- + +''''' + +=== TASK 3: Substitute ABI/FFI template placeholders (HIGH) + +All three Idris2 ABI files and all three Zig FFI files contain +unsubstituted `+{{PROJECT}}+` and `+{{project}}+` placeholders from +rsr-template-repo. These files cannot compile. + +*Files with `+{{PROJECT}}+` or `+{{project}}+` placeholders:* 1. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/src/abi/Types.idr+` — line 11 +(`+{{PROJECT}}.ABI.Types+`) 2. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/src/abi/Layout.idr+` — lines 8, +10 (`+{{PROJECT}}.ABI.Layout+`, `+{{PROJECT}}.ABI.Types+`) 3. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/src/abi/Foreign.idr+` — lines 9, +11, 12, 23, 35, 49, 72, 77, 98, 125, 152, 164, 185, 211 (many instances) +4. `+/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/src/main.zig+` — lines +1, 12, 54, 73, 89, 113, 135, 148, 184, 198, 203, 215, 246, 256, 263, +267, 271 5. `+/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/build.zig+` — +lines 1, 13, 23, 34, 82 6. +`+/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/test/integration_test.zig+` +— lines 1, 10-17, 24, 25, 31, 32, 34, 39, 48, 49, 51, 56, etc. + +*Action:* In all six files, perform global find-and-replace: - +`+{{PROJECT}}+` -> `+PolyglotFormalisms+` - `+{{project}}+` -> +`+polyglot_formalisms+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep -rn '{{PROJECT}}\|{{project}}' src/abi/ ffi/ +# Expected: no output (zero matches) +grep -c "PolyglotFormalisms" src/abi/Types.idr +# Expected: at least 1 +grep -c "polyglot_formalisms" ffi/zig/src/main.zig +# Expected: at least 10 +---- + +''''' + +=== TASK 4: Create Collection module (HIGH) + +*Why:* The main module at `+src/PolyglotFormalisms.jl+` line 54 exports +`+Collection+` and line 60 has `+# include("collection.jl")+` commented +out. The module docstring (line 24) documents it. STATE.scm lists it at +0%. The spec requires `+map+`, `+filter+`, `+fold+`, `+contains+`. + +*File to create:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/src/collection.jl+` + +*Required functions (matching aggregate-library spec):* + +[source,julia] +---- +module Collection +export map_items, filter_items, fold_items, contains_item + +# map_items: Apply function to each element +# Signature: map_items(f::Function, items::Vector) -> Vector +# Properties: map(id, xs) == xs; map(f . g, xs) == map(f, map(g, xs)) + +# filter_items: Keep elements matching predicate +# Signature: filter_items(pred::Function, items::Vector) -> Vector +# Properties: filter(const_true, xs) == xs; filter(const_false, xs) == [] + +# fold_items: Reduce collection to single value (left fold) +# Signature: fold_items(f::Function, init, items::Vector) -> Any +# Properties: fold(f, z, []) == z; fold(f, z, [x]) == f(z, x) + +# contains_item: Check if element is in collection +# Signature: contains_item(items::Vector, item) -> Bool +# Properties: contains([], x) == false; contains([x, ...], x) == true +end +---- + +*Important:* Use `+map_items+`, `+filter_items+`, `+fold_items+`, +`+contains_item+` to avoid shadowing Base functions `+map+`, `+filter+`, +`+foldl+`, `+in+`. + +Each function MUST have: - Full docstring in the same style as +`+src/arithmetic.jl+` (interface signature, behavioral semantics, +mathematical properties, examples, edge cases) - SPDX header: +`+# SPDX-License-Identifier: CC-BY-SA-4.0+` - Implementation using Julia +standard library (`+Base.map+`, `+Base.filter+`, `+Base.foldl+`, +`+Base.in+`) + +*Also uncomment in `+src/PolyglotFormalisms.jl+` line 60:* + +[source,julia] +---- +include("collection.jl") +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +julia --project=. -e ' +using PolyglotFormalisms +@assert Collection.map_items(x -> x * 2, [1, 2, 3]) == [2, 4, 6] +@assert Collection.filter_items(x -> x > 2, [1, 2, 3, 4]) == [3, 4] +@assert Collection.fold_items(+, 0, [1, 2, 3]) == 6 +@assert Collection.contains_item([1, 2, 3], 2) == true +@assert Collection.contains_item([1, 2, 3], 5) == false +println("Collection module OK") +' +---- + +''''' + +=== TASK 5: Create Collection module tests (HIGH) + +*File to create:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/test/collection_tests.jl+` + +*Required test sets (minimum 30 tests):* - `+map_items+`: basic mapping, +identity function, composition, empty collection, type preservation - +`+filter_items+`: basic filtering, always-true predicate, always-false +predicate, empty collection - `+fold_items+`: sum, product, string +concatenation, empty collection returns init, single-element - +`+contains_item+`: present element, absent element, empty collection, +first/last element - Property tests: map preserves length, filter result +is subset, fold over empty returns init + +*Style:* Match existing test files exactly (SPDX header, docstring, +`+@testset+` blocks). + +*Also add to `+test/runtests.jl+`:* + +[source,julia] +---- +include("collection_tests.jl") +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +julia --project=. -e 'using Pkg; Pkg.test()' +# Expected: all tests pass, including new collection tests +---- + +''''' + +=== TASK 6: Create Conditional module (HIGH) + +*Why:* The main module at `+src/PolyglotFormalisms.jl+` line 54 exports +`+Conditional+` and line 61 has `+# include("conditional.jl")+` +commented out. The module docstring (line 25) documents it. STATE.scm +lists it at 0%. The spec requires `+if_then_else+`. + +*File to create:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/src/conditional.jl+` + +*Required function:* + +[source,julia] +---- +module Conditional +export if_then_else + +# if_then_else: Conditional evaluation +# Signature: if_then_else(condition::Bool, then_val, else_val) -> Any +# Behavioral semantics: +# - If condition is true, returns then_val +# - If condition is false, returns else_val +# Properties: +# - if_then_else(true, a, b) == a +# - if_then_else(false, a, b) == b +# - if_then_else(c, a, a) == a (constant case) +end +---- + +Each function MUST have: - Full docstring in the same style as +`+src/arithmetic.jl+` - SPDX header - Implementation: +`+if_then_else(cond::Bool, then_val, else_val) = cond ? then_val : else_val+` + +*Also uncomment in `+src/PolyglotFormalisms.jl+` line 61:* + +[source,julia] +---- +include("conditional.jl") +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +julia --project=. -e ' +using PolyglotFormalisms +@assert Conditional.if_then_else(true, "yes", "no") == "yes" +@assert Conditional.if_then_else(false, "yes", "no") == "no" +@assert Conditional.if_then_else(true, 42, 0) == 42 +@assert Conditional.if_then_else(false, 42, 0) == 0 +println("Conditional module OK") +' +---- + +''''' + +=== TASK 7: Create Conditional module tests (HIGH) + +*File to create:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/test/conditional_tests.jl+` + +*Required test sets (minimum 15 tests):* - `+if_then_else+`: true +condition, false condition, integer values, string values, +nothing/missing values - Property tests: constant case +(`+if_then_else(c, a, a) == a+`), true branch, false branch - Type +tests: works with mixed types, works with collections, works with +functions as values - Edge cases: nested if_then_else + +*Also add to `+test/runtests.jl+`:* + +[source,julia] +---- +include("conditional_tests.jl") +---- + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +julia --project=. -e 'using Pkg; Pkg.test()' +# Expected: all tests pass, including new conditional tests +---- + +''''' + +=== TASK 8: Update README.md to reflect actual status (MEDIUM) + +*File:* `+/var$REPOS_DIR/PolyglotFormalisms.jl/README.md+` + +The README has multiple stale claims: + +[arabic] +. *Lines 62-66*: Lists Comparison, Logical, String as `+*(Planned)*+` — +they are all IMPLEMENTED. Fix: Remove `+*(Planned)*+` from Comparison, +Logical, String. Keep `+*(Planned)*+` only on Collection and Conditional +until Tasks 4-7 are done, then update those too. +. *Line 164*: Says "`Current: Arithmetic module complete with 59 passing +tests`" — this is the v0.1.0 status. After Tasks 4-7 there will be 6 +modules complete. Update to actual test count. +. *Line 166*: Says "`Planned: Comparison, Logical, String, Collection, +Conditional modules`" — three of those are done. Update. +. *Lines 57*: The "`(Properties are proven when Axiom.jl integration is +complete…)`" note is accurate but should be kept. + +*Action:* Update the Modules section to show actual completion status: + +[source,markdown] +---- +## Modules + +- **Arithmetic**: `add`, `subtract`, `multiply`, `divide`, `modulo` +- **Comparison**: `less_than`, `greater_than`, `equal`, `not_equal`, `less_equal`, `greater_equal` +- **Logical**: `and`, `or`, `not` +- **StringOps**: `concat`, `length`, `substring`, `index_of`, `contains`, `starts_with`, `ends_with`, `to_uppercase`, `to_lowercase`, `trim`, `split`, `join`, `replace`, `is_empty` +- **Collection**: `map_items`, `filter_items`, `fold_items`, `contains_item` +- **Conditional**: `if_then_else` +---- + +Update the Status section to reflect the actual test count (run tests +first to get exact number). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep -c "Planned" README.md +# Expected: 0 (after all modules are implemented) +grep "Current" README.md +# Expected: reflects actual status with correct test count +---- + +''''' + +=== TASK 9: Update STATE.scm to reflect actual completion (MEDIUM) + +*File:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/.machine_readable/STATE.scm+` + +STATE.scm has these inaccuracies: + +[arabic] +. *Line 21*: `+(overall-completion 50)+` — after Tasks 4-7, this should +be `+100+` (all 6 modules). +. *Lines 32-39*: String listed as +`+(completion . 0) (status . "planned")+` — but `+src/string.jl+` exists +with 14 functions and `+test/string_tests.jl+` has 89 tests. This should +be `+(completion . 100) (status . "complete")+`. +. *Lines 35-39*: Collection and Conditional listed as 0% — update to +100% after Tasks 4-7. +. *Line 9*: `+(updated "2026-01-23T20:00:00Z")+` — update to today’s +date. +. *Line 45*: Test count `+198+` needs updating to include string tests +(89) and new module tests. +. *Milestone-3*: Should be marked complete after Tasks 4-7. + +*Action:* Update all completion values, statuses, dates, and test counts +to reflect reality. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep "overall-completion" .machine_readable/STATE.scm +# Expected: (overall-completion 100) +grep -A2 '"String"' .machine_readable/STATE.scm +# Expected: (completion . 100) (status . "complete") +---- + +''''' + +=== TASK 10: Update ROADMAP.scm to reflect actual progress (MEDIUM) + +*File:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/.machine_readable/ROADMAP.scm+` + +The ROADMAP.scm was last updated `+2025-01-23+` and still shows v0.2.0 +as "`planned`" when it was released on 2026-01-23. After Tasks 4-7: + +[arabic] +. Mark v0.2.0 as `+(status . "released")+` +. Mark v0.3.0 as `+(status . "released")+` (String + Collection done) +. Update Conditional to reflect completion +. Update the themes section milestones with checkmarks + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep -A3 '"0.2.0"' .machine_readable/ROADMAP.scm +# Expected: (status . "released") +grep -A3 '"0.3.0"' .machine_readable/ROADMAP.scm +# Expected: (status . "released") or (status . "complete") +---- + +''''' + +=== TASK 11: Update CHANGELOG.scm with new release entry (MEDIUM) + +*File:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/.machine_readable/CHANGELOG.scm+` + +Add entries for the work done in Tasks 1-7: + +[arabic] +. Add a v0.3.0 release entry documenting: +* String module (14 operations, 89 tests) +* Collection module (4 operations) +* Conditional module (1 operation) +* ABI/FFI template placeholder substitution +* SPDX license fixes + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep '"0.3.0"' .machine_readable/CHANGELOG.scm +# Expected: at least one match +---- + +''''' + +=== TASK 12: Update CrossLanguageStatus.md (LOW) + +*File:* +`+/var$REPOS_DIR/PolyglotFormalisms.jl/docs/CrossLanguageStatus.md+` + +Line 9 claims version `+0.3.0+` with `+287/287+` tests and "`Complete`" +status. After Tasks 4-7, the test count will increase. Update line 72 +with actual total test count. + +Also update line 9 if the version changes. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +# Run actual test count +julia --project=. -e 'using Pkg; Pkg.test()' 2>&1 | tail -5 +# Compare test count with what CrossLanguageStatus.md claims +---- + +''''' + +=== TASK 13: Fix Manifest.toml stale package name reference (LOW) + +*File:* `+/var$REPOS_DIR/PolyglotFormalisms.jl/Manifest.toml+` + +Lines 52-55 contain a stale reference to the old package name `+aLib+`: + +[source,toml] +---- +[[deps.aLib]] +path = "." +uuid = "8fd979ee-625c-447d-87f1-33af4d789de5" +version = "0.1.0" +---- + +The package was renamed to `+PolyglotFormalisms+` (Project.toml says +`+name = "PolyglotFormalisms"+` at version `+1.0.0+`). The Manifest.toml +still references the old name at version `+0.1.0+`. + +*Action:* Regenerate Manifest.toml: + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +julia --project=. -e 'using Pkg; Pkg.resolve()' +---- + +If that does not fix the `+aLib+` reference, manually rename `+aLib+` to +`+PolyglotFormalisms+` and update version to `+1.0.0+` in the +Manifest.toml. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +grep "aLib" Manifest.toml +# Expected: no output (zero matches) +grep "PolyglotFormalisms" Manifest.toml +# Expected: at least one match +---- + +''''' + +=== TASK 14: Reconcile version number confusion (LOW) + +There is a version inconsistency across the repository: + +[cols=",",options="header",] +|=== +|Location |Version claimed +|`+Project.toml+` |`+1.0.0+` +|Git tags |`+v0.1.0+`, `+v0.1.1+`, `+v0.2.0+`, `+v1.0.0+` +|`+STATE.scm+` metadata |`+"1.0"+` +|`+META.scm+` |`+"0.1.0"+` +|`+Manifest.toml+` deps.aLib |`+"0.1.0"+` +|`+CHANGELOG.scm+` latest release |`+"0.2.0"+` +|`+CrossLanguageStatus.md+` |`+"0.3.0"+` +|`+ffi/zig/src/main.zig+` VERSION |`+"0.1.0"+` +|`+ffi/zig/build.zig+` lib.version |`+0.1.0+` +|=== + +The Project.toml says `+1.0.0+` and there is a `+v1.0.0+` git tag, but +the code is clearly NOT at 1.0.0 maturity (missing modules, template +placeholders, no Axiom.jl integration). + +*Action:* Decide on the correct version. Given the state after Tasks +1-13, `+0.3.0+` seems appropriate (all 6 core modules complete, no +formal verification yet). Update all files to use a consistent version. + +If keeping `+1.0.0+`, update all references. If reverting to `+0.3.0+`: +- `+Project.toml+`: `+version = "0.3.0"+` - `+META.scm+`: +`+(version . "0.3.0")+` - `+ffi/zig+` VERSION constant: `+"0.3.0"+` - +`+ffi/zig+` build.zig version: +`+.{ .major = 0, .minor = 3, .patch = 0 }+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl +# All version references should be consistent +grep -rn 'version.*"0\.' Project.toml .machine_readable/META.scm ffi/zig/src/main.zig +# Expected: all show the same version +---- + +''''' + +=== FINAL VERIFICATION + +After completing all tasks, run this full verification sequence: + +[source,bash] +---- +cd /var$REPOS_DIR/PolyglotFormalisms.jl + +# 1. Full test suite passes +julia --project=. -e 'using Pkg; Pkg.test()' + +# 2. All modules load without error +julia --project=. -e ' +using PolyglotFormalisms +println("Arithmetic: ", methods(Arithmetic.add)) +println("Comparison: ", methods(Comparison.less_than)) +println("Logical: ", methods(Logical.and)) +println("StringOps: ", methods(StringOps.concat)) +println("Collection: ", methods(Collection.map_items)) +println("Conditional: ", methods(Conditional.if_then_else)) +println("All 6 modules loaded successfully") +' + +# 3. No template placeholders remain +grep -rn '{{PROJECT}}\|{{project}}\|{{PLACEHOLDER}}\|{{REPO}}\|{{OWNER}}\|{{FORGE}}' \ + src/ ffi/ test/ examples/ +# Expected: no output + +# 4. No AGPL license references +grep -rn 'AGPL' src/ ffi/ test/ examples/ +# Expected: no output + +# 5. No StringOpsOps typo +grep -rn 'StringOpsOps' src/ +# Expected: no output + +# 6. STATE.scm shows 100% completion +grep 'overall-completion' .machine_readable/STATE.scm +# Expected: (overall-completion 100) + +# 7. No stale "Planned" markers for implemented modules in README +grep 'Planned' README.md +# Expected: 0 matches (or only for future features like Axiom.jl) + +# 8. Consistent version across all files +echo "=== Version check ===" +grep '^version' Project.toml +grep 'version.*"[0-9]' .machine_readable/META.scm +---- diff --git a/packages/PolyglotFormalisms.jl/SONNET-TASKS.md b/packages/PolyglotFormalisms.jl/SONNET-TASKS.md deleted file mode 100644 index b4a28da34..000000000 --- a/packages/PolyglotFormalisms.jl/SONNET-TASKS.md +++ /dev/null @@ -1,538 +0,0 @@ -# SONNET-TASKS.md — PolyglotFormalisms.jl Completion Tasks - -> **Generated:** 2026-02-12 by Opus audit -> **Purpose:** Unambiguous instructions for Sonnet to complete all stubs, TODOs, and placeholder code. -> **Honest completion before this file:** 62% - -The code that exists (Arithmetic, Comparison, Logical, StringOps) is functional and well-documented. -However: two modules are entirely missing (Collection, Conditional), the String module has a typo-bug, -STATE.scm claims String is 0% complete when it is actually implemented and tested, -the README.md is stale (claims modules are "Planned" that already exist), -the ABI/FFI layer is entirely unsubstituted template placeholders, -and there is a SPDX license violation in three files. - ---- - -## GROUND RULES FOR SONNET - -1. Read this entire file before starting any task. -2. Do tasks in order listed. Earlier tasks unblock later ones. -3. After each task, run the verification command. If it fails, fix before moving on. -4. Do NOT mark done unless verification passes. -5. Update `.machine_readable/STATE.scm` with honest completion percentages after each task. -6. Commit after each task: `fix(component): complete ` -7. Run full test suite after every 3 tasks. - ---- - -## TASK 1: Fix StringOps module closing comment typo (CRITICAL) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/src/string.jl` -**Line:** 390 - -The module closing comment reads `end # module StringOpsOps` but the module is named `StringOps`. -This is a copy-paste typo that will confuse tooling and developers. - -**Action:** Change line 390 from: -```julia -end # module StringOpsOps -``` -to: -```julia -end # module StringOps -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep -n "StringOpsOps" src/string.jl -# Expected: no output (zero matches) -grep -n "end # module StringOps$" src/string.jl -# Expected: exactly one match at line 390 -``` - ---- - -## TASK 2: Fix SPDX license headers in ABI/FFI template files (CRITICAL) - -Three files use `AGPL-3.0-or-later` instead of `MPL-2.0`. Per CLAUDE.md policy, -AGPL-3.0 is the OLD license and must NEVER be used. - -**Files to fix:** -1. `/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/src/main.zig` — line 6 -2. `/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/build.zig` — line 2 -3. `/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/test/integration_test.zig` — line 2 - -**Also fix:** -4. `/var$REPOS_DIR/PolyglotFormalisms.jl/examples/SafeDOMExample.res` — line 1 - -**Action:** In each file, replace: -``` -SPDX-License-Identifier: CC-BY-SA-4.0 -``` -with: -``` -SPDX-License-Identifier: CC-BY-SA-4.0 -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep -rn "AGPL" ffi/ examples/ src/abi/ -# Expected: no output (zero matches) -grep -rn "MPL-2.0" ffi/ examples/ -# Expected: 4 matches (one per file) -``` - ---- - -## TASK 3: Substitute ABI/FFI template placeholders (HIGH) - -All three Idris2 ABI files and all three Zig FFI files contain unsubstituted `{{PROJECT}}` -and `{{project}}` placeholders from rsr-template-repo. These files cannot compile. - -**Files with `{{PROJECT}}` or `{{project}}` placeholders:** -1. `/var$REPOS_DIR/PolyglotFormalisms.jl/src/abi/Types.idr` — line 11 (`{{PROJECT}}.ABI.Types`) -2. `/var$REPOS_DIR/PolyglotFormalisms.jl/src/abi/Layout.idr` — lines 8, 10 (`{{PROJECT}}.ABI.Layout`, `{{PROJECT}}.ABI.Types`) -3. `/var$REPOS_DIR/PolyglotFormalisms.jl/src/abi/Foreign.idr` — lines 9, 11, 12, 23, 35, 49, 72, 77, 98, 125, 152, 164, 185, 211 (many instances) -4. `/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/src/main.zig` — lines 1, 12, 54, 73, 89, 113, 135, 148, 184, 198, 203, 215, 246, 256, 263, 267, 271 -5. `/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/build.zig` — lines 1, 13, 23, 34, 82 -6. `/var$REPOS_DIR/PolyglotFormalisms.jl/ffi/zig/test/integration_test.zig` — lines 1, 10-17, 24, 25, 31, 32, 34, 39, 48, 49, 51, 56, etc. - -**Action:** In all six files, perform global find-and-replace: -- `{{PROJECT}}` -> `PolyglotFormalisms` -- `{{project}}` -> `polyglot_formalisms` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep -rn '{{PROJECT}}\|{{project}}' src/abi/ ffi/ -# Expected: no output (zero matches) -grep -c "PolyglotFormalisms" src/abi/Types.idr -# Expected: at least 1 -grep -c "polyglot_formalisms" ffi/zig/src/main.zig -# Expected: at least 10 -``` - ---- - -## TASK 4: Create Collection module (HIGH) - -**Why:** The main module at `src/PolyglotFormalisms.jl` line 54 exports `Collection` and line 60 -has `# include("collection.jl")` commented out. The module docstring (line 24) documents it. -STATE.scm lists it at 0%. The spec requires `map`, `filter`, `fold`, `contains`. - -**File to create:** `/var$REPOS_DIR/PolyglotFormalisms.jl/src/collection.jl` - -**Required functions (matching aggregate-library spec):** - -```julia -module Collection -export map_items, filter_items, fold_items, contains_item - -# map_items: Apply function to each element -# Signature: map_items(f::Function, items::Vector) -> Vector -# Properties: map(id, xs) == xs; map(f . g, xs) == map(f, map(g, xs)) - -# filter_items: Keep elements matching predicate -# Signature: filter_items(pred::Function, items::Vector) -> Vector -# Properties: filter(const_true, xs) == xs; filter(const_false, xs) == [] - -# fold_items: Reduce collection to single value (left fold) -# Signature: fold_items(f::Function, init, items::Vector) -> Any -# Properties: fold(f, z, []) == z; fold(f, z, [x]) == f(z, x) - -# contains_item: Check if element is in collection -# Signature: contains_item(items::Vector, item) -> Bool -# Properties: contains([], x) == false; contains([x, ...], x) == true -end -``` - -**Important:** Use `map_items`, `filter_items`, `fold_items`, `contains_item` to avoid -shadowing Base functions `map`, `filter`, `foldl`, `in`. - -Each function MUST have: -- Full docstring in the same style as `src/arithmetic.jl` (interface signature, behavioral semantics, mathematical properties, examples, edge cases) -- SPDX header: `# SPDX-License-Identifier: CC-BY-SA-4.0` -- Implementation using Julia standard library (`Base.map`, `Base.filter`, `Base.foldl`, `Base.in`) - -**Also uncomment in `src/PolyglotFormalisms.jl` line 60:** -```julia -include("collection.jl") -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -julia --project=. -e ' -using PolyglotFormalisms -@assert Collection.map_items(x -> x * 2, [1, 2, 3]) == [2, 4, 6] -@assert Collection.filter_items(x -> x > 2, [1, 2, 3, 4]) == [3, 4] -@assert Collection.fold_items(+, 0, [1, 2, 3]) == 6 -@assert Collection.contains_item([1, 2, 3], 2) == true -@assert Collection.contains_item([1, 2, 3], 5) == false -println("Collection module OK") -' -``` - ---- - -## TASK 5: Create Collection module tests (HIGH) - -**File to create:** `/var$REPOS_DIR/PolyglotFormalisms.jl/test/collection_tests.jl` - -**Required test sets (minimum 30 tests):** -- `map_items`: basic mapping, identity function, composition, empty collection, type preservation -- `filter_items`: basic filtering, always-true predicate, always-false predicate, empty collection -- `fold_items`: sum, product, string concatenation, empty collection returns init, single-element -- `contains_item`: present element, absent element, empty collection, first/last element -- Property tests: map preserves length, filter result is subset, fold over empty returns init - -**Style:** Match existing test files exactly (SPDX header, docstring, `@testset` blocks). - -**Also add to `test/runtests.jl`:** -```julia -include("collection_tests.jl") -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -julia --project=. -e 'using Pkg; Pkg.test()' -# Expected: all tests pass, including new collection tests -``` - ---- - -## TASK 6: Create Conditional module (HIGH) - -**Why:** The main module at `src/PolyglotFormalisms.jl` line 54 exports `Conditional` and line 61 -has `# include("conditional.jl")` commented out. The module docstring (line 25) documents it. -STATE.scm lists it at 0%. The spec requires `if_then_else`. - -**File to create:** `/var$REPOS_DIR/PolyglotFormalisms.jl/src/conditional.jl` - -**Required function:** - -```julia -module Conditional -export if_then_else - -# if_then_else: Conditional evaluation -# Signature: if_then_else(condition::Bool, then_val, else_val) -> Any -# Behavioral semantics: -# - If condition is true, returns then_val -# - If condition is false, returns else_val -# Properties: -# - if_then_else(true, a, b) == a -# - if_then_else(false, a, b) == b -# - if_then_else(c, a, a) == a (constant case) -end -``` - -Each function MUST have: -- Full docstring in the same style as `src/arithmetic.jl` -- SPDX header -- Implementation: `if_then_else(cond::Bool, then_val, else_val) = cond ? then_val : else_val` - -**Also uncomment in `src/PolyglotFormalisms.jl` line 61:** -```julia -include("conditional.jl") -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -julia --project=. -e ' -using PolyglotFormalisms -@assert Conditional.if_then_else(true, "yes", "no") == "yes" -@assert Conditional.if_then_else(false, "yes", "no") == "no" -@assert Conditional.if_then_else(true, 42, 0) == 42 -@assert Conditional.if_then_else(false, 42, 0) == 0 -println("Conditional module OK") -' -``` - ---- - -## TASK 7: Create Conditional module tests (HIGH) - -**File to create:** `/var$REPOS_DIR/PolyglotFormalisms.jl/test/conditional_tests.jl` - -**Required test sets (minimum 15 tests):** -- `if_then_else`: true condition, false condition, integer values, string values, nothing/missing values -- Property tests: constant case (`if_then_else(c, a, a) == a`), true branch, false branch -- Type tests: works with mixed types, works with collections, works with functions as values -- Edge cases: nested if_then_else - -**Also add to `test/runtests.jl`:** -```julia -include("conditional_tests.jl") -``` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -julia --project=. -e 'using Pkg; Pkg.test()' -# Expected: all tests pass, including new conditional tests -``` - ---- - -## TASK 8: Update README.md to reflect actual status (MEDIUM) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/README.md` - -The README has multiple stale claims: - -1. **Lines 62-66**: Lists Comparison, Logical, String as `*(Planned)*` — they are all IMPLEMENTED. - Fix: Remove `*(Planned)*` from Comparison, Logical, String. Keep `*(Planned)*` only on - Collection and Conditional until Tasks 4-7 are done, then update those too. - -2. **Line 164**: Says "Current: Arithmetic module complete with 59 passing tests" — this is the - v0.1.0 status. After Tasks 4-7 there will be 6 modules complete. Update to actual test count. - -3. **Line 166**: Says "Planned: Comparison, Logical, String, Collection, Conditional modules" — - three of those are done. Update. - -4. **Lines 57**: The "(Properties are proven when Axiom.jl integration is complete...)" note is - accurate but should be kept. - -**Action:** Update the Modules section to show actual completion status: -```markdown -## Modules - -- **Arithmetic**: `add`, `subtract`, `multiply`, `divide`, `modulo` -- **Comparison**: `less_than`, `greater_than`, `equal`, `not_equal`, `less_equal`, `greater_equal` -- **Logical**: `and`, `or`, `not` -- **StringOps**: `concat`, `length`, `substring`, `index_of`, `contains`, `starts_with`, `ends_with`, `to_uppercase`, `to_lowercase`, `trim`, `split`, `join`, `replace`, `is_empty` -- **Collection**: `map_items`, `filter_items`, `fold_items`, `contains_item` -- **Conditional**: `if_then_else` -``` - -Update the Status section to reflect the actual test count (run tests first to get exact number). - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep -c "Planned" README.md -# Expected: 0 (after all modules are implemented) -grep "Current" README.md -# Expected: reflects actual status with correct test count -``` - ---- - -## TASK 9: Update STATE.scm to reflect actual completion (MEDIUM) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/.machine_readable/STATE.scm` - -STATE.scm has these inaccuracies: - -1. **Line 21**: `(overall-completion 50)` — after Tasks 4-7, this should be `100` (all 6 modules). -2. **Lines 32-39**: String listed as `(completion . 0) (status . "planned")` — but `src/string.jl` - exists with 14 functions and `test/string_tests.jl` has 89 tests. This should be `(completion . 100) (status . "complete")`. -3. **Lines 35-39**: Collection and Conditional listed as 0% — update to 100% after Tasks 4-7. -4. **Line 9**: `(updated "2026-01-23T20:00:00Z")` — update to today's date. -5. **Line 45**: Test count `198` needs updating to include string tests (89) and new module tests. -6. **Milestone-3**: Should be marked complete after Tasks 4-7. - -**Action:** Update all completion values, statuses, dates, and test counts to reflect reality. - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep "overall-completion" .machine_readable/STATE.scm -# Expected: (overall-completion 100) -grep -A2 '"String"' .machine_readable/STATE.scm -# Expected: (completion . 100) (status . "complete") -``` - ---- - -## TASK 10: Update ROADMAP.scm to reflect actual progress (MEDIUM) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/.machine_readable/ROADMAP.scm` - -The ROADMAP.scm was last updated `2025-01-23` and still shows v0.2.0 as "planned" when -it was released on 2026-01-23. After Tasks 4-7: - -1. Mark v0.2.0 as `(status . "released")` -2. Mark v0.3.0 as `(status . "released")` (String + Collection done) -3. Update Conditional to reflect completion -4. Update the themes section milestones with checkmarks - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep -A3 '"0.2.0"' .machine_readable/ROADMAP.scm -# Expected: (status . "released") -grep -A3 '"0.3.0"' .machine_readable/ROADMAP.scm -# Expected: (status . "released") or (status . "complete") -``` - ---- - -## TASK 11: Update CHANGELOG.scm with new release entry (MEDIUM) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/.machine_readable/CHANGELOG.scm` - -Add entries for the work done in Tasks 1-7: - -1. Add a v0.3.0 release entry documenting: - - String module (14 operations, 89 tests) - - Collection module (4 operations) - - Conditional module (1 operation) - - ABI/FFI template placeholder substitution - - SPDX license fixes - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep '"0.3.0"' .machine_readable/CHANGELOG.scm -# Expected: at least one match -``` - ---- - -## TASK 12: Update CrossLanguageStatus.md (LOW) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/docs/CrossLanguageStatus.md` - -Line 9 claims version `0.3.0` with `287/287` tests and "Complete" status. After Tasks 4-7, -the test count will increase. Update line 72 with actual total test count. - -Also update line 9 if the version changes. - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -# Run actual test count -julia --project=. -e 'using Pkg; Pkg.test()' 2>&1 | tail -5 -# Compare test count with what CrossLanguageStatus.md claims -``` - ---- - -## TASK 13: Fix Manifest.toml stale package name reference (LOW) - -**File:** `/var$REPOS_DIR/PolyglotFormalisms.jl/Manifest.toml` - -Lines 52-55 contain a stale reference to the old package name `aLib`: -```toml -[[deps.aLib]] -path = "." -uuid = "8fd979ee-625c-447d-87f1-33af4d789de5" -version = "0.1.0" -``` - -The package was renamed to `PolyglotFormalisms` (Project.toml says `name = "PolyglotFormalisms"` -at version `1.0.0`). The Manifest.toml still references the old name at version `0.1.0`. - -**Action:** Regenerate Manifest.toml: -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -julia --project=. -e 'using Pkg; Pkg.resolve()' -``` - -If that does not fix the `aLib` reference, manually rename `aLib` to `PolyglotFormalisms` -and update version to `1.0.0` in the Manifest.toml. - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -grep "aLib" Manifest.toml -# Expected: no output (zero matches) -grep "PolyglotFormalisms" Manifest.toml -# Expected: at least one match -``` - ---- - -## TASK 14: Reconcile version number confusion (LOW) - -There is a version inconsistency across the repository: - -| Location | Version claimed | -|----------|----------------| -| `Project.toml` | `1.0.0` | -| Git tags | `v0.1.0`, `v0.1.1`, `v0.2.0`, `v1.0.0` | -| `STATE.scm` metadata | `"1.0"` | -| `META.scm` | `"0.1.0"` | -| `Manifest.toml` deps.aLib | `"0.1.0"` | -| `CHANGELOG.scm` latest release | `"0.2.0"` | -| `CrossLanguageStatus.md` | `"0.3.0"` | -| `ffi/zig/src/main.zig` VERSION | `"0.1.0"` | -| `ffi/zig/build.zig` lib.version | `0.1.0` | - -The Project.toml says `1.0.0` and there is a `v1.0.0` git tag, but the code is clearly NOT -at 1.0.0 maturity (missing modules, template placeholders, no Axiom.jl integration). - -**Action:** Decide on the correct version. Given the state after Tasks 1-13, `0.3.0` seems -appropriate (all 6 core modules complete, no formal verification yet). Update all files to -use a consistent version. - -If keeping `1.0.0`, update all references. If reverting to `0.3.0`: -- `Project.toml`: `version = "0.3.0"` -- `META.scm`: `(version . "0.3.0")` -- `ffi/zig` VERSION constant: `"0.3.0"` -- `ffi/zig` build.zig version: `.{ .major = 0, .minor = 3, .patch = 0 }` - -**Verification:** -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl -# All version references should be consistent -grep -rn 'version.*"0\.' Project.toml .machine_readable/META.scm ffi/zig/src/main.zig -# Expected: all show the same version -``` - ---- - -## FINAL VERIFICATION - -After completing all tasks, run this full verification sequence: - -```bash -cd /var$REPOS_DIR/PolyglotFormalisms.jl - -# 1. Full test suite passes -julia --project=. -e 'using Pkg; Pkg.test()' - -# 2. All modules load without error -julia --project=. -e ' -using PolyglotFormalisms -println("Arithmetic: ", methods(Arithmetic.add)) -println("Comparison: ", methods(Comparison.less_than)) -println("Logical: ", methods(Logical.and)) -println("StringOps: ", methods(StringOps.concat)) -println("Collection: ", methods(Collection.map_items)) -println("Conditional: ", methods(Conditional.if_then_else)) -println("All 6 modules loaded successfully") -' - -# 3. No template placeholders remain -grep -rn '{{PROJECT}}\|{{project}}\|{{PLACEHOLDER}}\|{{REPO}}\|{{OWNER}}\|{{FORGE}}' \ - src/ ffi/ test/ examples/ -# Expected: no output - -# 4. No AGPL license references -grep -rn 'AGPL' src/ ffi/ test/ examples/ -# Expected: no output - -# 5. No StringOpsOps typo -grep -rn 'StringOpsOps' src/ -# Expected: no output - -# 6. STATE.scm shows 100% completion -grep 'overall-completion' .machine_readable/STATE.scm -# Expected: (overall-completion 100) - -# 7. No stale "Planned" markers for implemented modules in README -grep 'Planned' README.md -# Expected: 0 matches (or only for future features like Axiom.jl) - -# 8. Consistent version across all files -echo "=== Version check ===" -grep '^version' Project.toml -grep 'version.*"[0-9]' .machine_readable/META.scm -``` diff --git a/packages/PolyglotFormalisms.jl/TOPOLOGY.md b/packages/PolyglotFormalisms.jl/TOPOLOGY.adoc similarity index 89% rename from packages/PolyglotFormalisms.jl/TOPOLOGY.md rename to packages/PolyglotFormalisms.jl/TOPOLOGY.adoc index 7b76c5d4f..56fc872d2 100644 --- a/packages/PolyglotFormalisms.jl/TOPOLOGY.md +++ b/packages/PolyglotFormalisms.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== PolyglotFormalisms.jl — Project Topology -# PolyglotFormalisms.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── COMMON MODULES @@ -69,26 +65,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Module Feature Complete -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Arithmetic ─────────► Comparison ─────────► Logical │ StringOps ──────────► Collection ─────────► Conditional │ Conformance Tests ────► Axiom Integration ──► COMPLETE -``` +.... -## 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/packages/PolyglotFormalisms.jl/docs/CrossLanguageStatus.adoc b/packages/PolyglotFormalisms.jl/docs/CrossLanguageStatus.adoc new file mode 100644 index 000000000..fd04e6106 --- /dev/null +++ b/packages/PolyglotFormalisms.jl/docs/CrossLanguageStatus.adoc @@ -0,0 +1,297 @@ +== Cross-Language Implementation Status + +This document tracks the implementation status of PolyglotFormalisms +Common Library operations across multiple programming languages. + +=== Implementation Summary + +[width="99%",cols="21%,21%,17%,15%,13%,13%",options="header",] +|=== +|Language |Repository |Version |Status |Tests |Notes +|*Julia* +|https://github.com/hyperpolymath/PolyglotFormalisms.jl[PolyglotFormalisms.jl] +|0.3.0 |✅ Complete |287/287 |Reference implementation + +|*ReScript* +|https://github.com/hyperpolymath/alib-for-rescript[alib-for-rescript] +|0.3.0 |✅ Complete |Full coverage |packages/common/ + +|*Gleam* +|https://github.com/hyperpolymath/polyglot_formalisms_gleam[polyglot_formalisms_gleam] +|0.3.0 |✅ Complete |131/131 |BEAM runtime, gleeunit tests + +|*Elixir* +|https://github.com/hyperpolymath/polyglot_formalisms_elixir[polyglot_formalisms_elixir] +|0.3.0 |✅ Complete |253/253 |120 doctests + 133 unit tests +|=== + +=== Module Completion Status + +==== Arithmetic Module + +[cols=",,,,,",options="header",] +|=== +|Operation |Julia |ReScript |Gleam |Elixir |Notes +|`+add+` |✅ |✅ |✅ |✅ |Float operation +|`+subtract+` |✅ |✅ |✅ |✅ |Float operation +|`+multiply+` |✅ |✅ |✅ |✅ |Float operation +|`+divide+` |✅ |✅ |✅ |✅ |Float operation +|`+modulo+` |✅ |✅ |✅ |✅ |Integer operation +|=== + +==== Comparison Module + +[cols=",,,,,",options="header",] +|=== +|Operation |Julia |ReScript |Gleam |Elixir |Notes +|`+less_than+` |✅ |✅ |✅ |✅ |Float comparison +|`+greater_than+` |✅ |✅ |✅ |✅ |Float comparison +|`+equal+` |✅ |✅ |✅ |✅ |Float comparison +|`+not_equal+` |✅ |✅ |✅ |✅ |Float comparison +|`+less_equal+` |✅ |✅ |✅ |✅ |Float comparison +|`+greater_equal+` |✅ |✅ |✅ |✅ |Float comparison +|=== + +==== Logical Module + +[width="100%",cols="22%,14%,20%,14%,16%,14%",options="header",] +|=== +|Operation |Julia |ReScript |Gleam |Elixir |Notes +|`+and+` |✅ |✅ |✅ |✅ `+logical_and+` |Elixir renamed due to keyword +conflict + +|`+or+` |✅ |✅ |✅ |✅ `+logical_or+` |Elixir renamed due to keyword +conflict + +|`+not+` |✅ |✅ |✅ |✅ `+logical_not+` |Elixir renamed due to keyword +conflict +|=== + +==== String Module + +[width="100%",cols="22%,14%,20%,14%,16%,14%",options="header",] +|=== +|Operation |Julia |ReScript |Gleam |Elixir |Notes +|`+concat+` |✅ |✅ |✅ |✅ |String concatenation + +|`+length+` |✅ |✅ |✅ |✅ `+string_length+` |Elixir renamed to avoid +stdlib conflict + +|`+substring+` |✅ |✅ |✅ |✅ |Julia/Elixir: 1-based; ReScript/Gleam: +0-based + +|`+index_of+` |✅ |✅ |✅ |✅ |Julia/Elixir: returns 0 when not found; +ReScript/Gleam: returns -1 + +|`+contains+` |✅ |✅ |✅ |✅ `+string_contains+` |Elixir renamed to +avoid stdlib conflict + +|`+starts_with+` |✅ |✅ |✅ |✅ |Prefix check + +|`+ends_with+` |✅ |✅ |✅ |✅ |Suffix check + +|`+to_uppercase+` |✅ |✅ |✅ |✅ |Unicode-aware + +|`+to_lowercase+` |✅ |✅ |✅ |✅ |Unicode-aware + +|`+trim+` |✅ |✅ |✅ |✅ `+string_trim+` |Elixir renamed to avoid +stdlib conflict + +|`+split+` |✅ |✅ |✅ |✅ `+string_split+` |Elixir renamed to avoid +stdlib conflict + +|`+join+` |✅ |✅ |✅ |✅ `+string_join+` |Elixir renamed to avoid +stdlib conflict + +|`+replace+` |✅ |✅ |✅ |✅ `+string_replace+` |Elixir renamed to avoid +stdlib conflict + +|`+is_empty+` |✅ |✅ |✅ |✅ |Boolean check +|=== + +=== Language-Specific Implementation Notes + +==== Julia (Reference Implementation) + +* *File locations*: `+src/arithmetic.jl+`, `+src/comparison.jl+`, +`+src/logical.jl+`, `+src/string.jl+` +* *Test locations*: `+test/arithmetic_tests.jl+`, +`+test/comparison_tests.jl+`, `+test/logical_tests.jl+`, +`+test/string_tests.jl+` +* *Operators*: Standard Julia operators (`+++`, `+-+`, `+*+`, `+/+`, +`+mod+`, `+<+`, `+>+`, `+==+`, `+&&+`, `+||+`, `+!+`) +* *Type system*: Generic `+Number+` and `+Bool+` types, +`+AbstractString+` for strings +* *Test framework*: Test.jl with `+@testset+` and `+@test+` macros +* *Total tests*: 287 (59 arithmetic + 98 comparison + 41 logical + 89 +string) +* *String indexing*: 1-based (Julia convention) + +==== ReScript + +* *File locations*: `+packages/common/Arithmetic.res+`, +`+packages/common/Comparison.res+`, `+packages/common/Logical.res+`, +`+packages/common/String.res+` +* *Test locations*: `+tests/Arithmetic_test.res+`, +`+tests/Comparison_test.res+`, `+tests/Logical_test.res+`, +`+tests/String_test.res+` +* *Operators*: Float-specific operators (`++.+`, `+-.+`, `+*.+`, `+/.+`, +standard comparison, `+&&+`, `+||+`, `+!+`) +* *Type system*: Explicit `+float+`, `+bool+`, and `+string+` types +* *Test framework*: RescriptMocha +* *Modulo*: Uses `+mod_float+` for float modulo operation +* *String indexing*: 0-based (JavaScript/ReScript convention) +* *String operators*: Uses `++++` for concatenation, standard String +module functions + +==== Gleam + +* *File locations*: `+src/arithmetic.gleam+`, `+src/comparison.gleam+`, +`+src/logical.gleam+`, `+src/string_ops.gleam+` +* *Test locations*: `+test/arithmetic_test.gleam+`, +`+test/comparison_test.gleam+`, `+test/logical_test.gleam+`, +`+test/string_ops_test.gleam+` +* *Operators*: +** Arithmetic: `++.+`, `+-.+`, `+*.+`, `+/.+` (dot required for floats) +** Ordering: `+<.+`, `+>.+`, `+<=.+`, `+>=.+` (dot required for floats) +** Equality: `+==+`, `+!=+` (no dot, works for all types) +** Logical: `+&&+`, `+||+`, `+!+` +** String: `+<>+` for concatenation +* *Type system*: Separate `+Float+`, `+Int+`, `+Bool+`, and `+String+` +types +* *Runtime*: BEAM (Erlang VM) or JavaScript +* *Modulo*: Integer operation using `+%+` +* *Test framework*: Gleeunit +* *Total tests*: 131 (28 arithmetic + 35 comparison + 22 logical + 7 +property tests + 39 string) +* *String indexing*: 0-based (Gleam convention) +* *String graphemes*: Uses grapheme-aware length and splitting + +==== Elixir + +* *File locations*: `+lib/arithmetic.ex+`, `+lib/comparison.ex+`, +`+lib/logical.ex+`, `+lib/string_ops.ex+` +* *Test locations*: `+test/arithmetic_test.exs+`, +`+test/comparison_test.exs+`, `+test/logical_test.exs+`, +`+test/string_ops_test.exs+` +* *Operators*: Standard Elixir operators (automatically promoted to +float for division), `+<>+` for string concatenation +* *Type system*: Dynamic with guards and `+@spec+` annotations +* *Runtime*: BEAM (Erlang VM) +* *Modulo*: Uses `+rem+` for remainder (Erlang semantics) +* *Test framework*: ExUnit with doctests +* *Total tests*: 253 (120 doctests + 133 unit tests) +* *Naming exceptions*: +** Logical: `+logical_and+`, `+logical_or+`, `+logical_not+` (to avoid +Kernel keyword conflicts) +** String: `+string_length+`, `+string_contains+`, `+string_trim+`, +`+string_split+`, `+string_join+`, `+string_replace+` (to avoid stdlib +conflicts) +* *String indexing*: 1-based (matching Julia for cross-language +consistency) +* *String graphemes*: Uses grapheme-aware operations + +=== Operator Comparison Table + +[cols=",,,,",options="header",] +|=== +|Operation |Julia |ReScript |Gleam |Elixir +|Float addition |`+++` |`++.+` |`++.+` |`+++` +|Float subtraction |`+-+` |`+-.+` |`+-.+` |`+-+` +|Float multiplication |`+*+` |`+*.+` |`+*.+` |`+*+` +|Float division |`+/+` |`+/.+` |`+/.+` |`+/+` +|Integer modulo |`+mod+` |`+mod+` |`+%+` |`+rem+` +|Less than (float) |`+<+` |`+<+` |`+<.+` |`+<+` +|Greater than (float) |`+>+` |`+>+` |`+>.+` |`+>+` +|Equal (any type) |`+==+` |`+==+` |`+==+` |`+==+` +|Not equal (any type) |`+!=+` |`+!=+` |`+!=+` |`+!=+` +|Less or equal (float) |`+<=+` |`+<=+` |`+<=.+` |`+<=+` +|Greater or equal (float) |`+>=+` |`+>=+` |`+>=.+` |`+>=+` +|Logical AND |`+&&+` |`+&&+` |`+&&+` |`+and+` +|Logical OR |`+\|\|+` |`+\|\|+` |`+\|\|+` |`+or+` +|Logical NOT |`+!+` |`+!+` |`+!+` |`+not+` +|=== + +*Note:* Gleam uses dotted operators (`++.+`, `+<.+`, etc.) only for +arithmetic and float ordering comparisons, but not for equality (`+==+`, +`+!=+`), which works for all types. + +=== Semantic Equivalence + +All implementations maintain semantic equivalence across languages: + +==== Behavioral Consistency + +[arabic] +. *Mathematical properties preserved*: +* Commutativity, associativity, distributivity (where applicable) +* Identity elements and annihilators +* Transitivity, reflexivity, symmetry (for comparisons) +* Boolean algebra laws (De Morgan’s, excluded middle, non-contradiction) +. *IEEE 754 floating-point semantics*: +* Division by zero behavior +* NaN propagation +* Infinity handling +* Signed zeros +. *Edge cases handled consistently*: +* All languages follow their runtime’s floating-point model +* Integer operations respect overflow/underflow behavior +* Modulo follows BEAM `+rem+` semantics (Gleam/Elixir) or +language-specific + +==== Verification Strategy + +Cross-language verification is achieved through: + +[arabic] +. *Property-based testing*: All implementations test the same +mathematical properties +. *Canonical test suite*: Test cases match across all languages +. *Edge case coverage*: Identical edge case handling (NaN, Inf, signed +zeros) +. *Documentation*: All implementations document the same behavioral +semantics + +=== Future Work + +==== Pending Implementations + +* *Python* (planned) +* *Rust* (planned) +* *Haskell* (planned) +* *OCaml* (planned) + +==== Pending Tasks + +[arabic] +. Create Gleam test suite (gleeunit) +. Formal verification proofs (using Isabelle/HOL or Coq) +. Property-based tests using QuickCheck-style frameworks +. Cross-language fuzzing for edge case discovery +. Performance benchmarks across implementations +. Automated semantic equivalence verification + +=== License + +All implementations use MPL-2.0 (Palimpsest Meta-Public License). + +=== Contributing + +When adding a new language implementation: + +[arabic] +. Create a new repository following naming convention: +`+polyglot_formalisms_{language}+` +. Implement all three modules (Arithmetic, Comparison, Logical) +. Maintain semantic equivalence with reference implementation +. Include comprehensive test suite (unit tests + property tests) +. Document language-specific considerations +. Update this status document + +=== References + +* https://github.com/hyperpolymath/PolyglotFormalisms.jl[PolyglotFormalisms +Specification] +* https://ieeexplore.ieee.org/document/8766229[IEEE 754 Floating-Point +Standard] +* https://en.wikipedia.org/wiki/Boolean_algebra[Boolean Algebra] diff --git a/packages/PolyglotFormalisms.jl/docs/CrossLanguageStatus.md b/packages/PolyglotFormalisms.jl/docs/CrossLanguageStatus.md deleted file mode 100644 index 444774b98..000000000 --- a/packages/PolyglotFormalisms.jl/docs/CrossLanguageStatus.md +++ /dev/null @@ -1,204 +0,0 @@ -# Cross-Language Implementation Status - -This document tracks the implementation status of PolyglotFormalisms Common Library operations across multiple programming languages. - -## Implementation Summary - -| Language | Repository | Version | Status | Tests | Notes | -|----------|-----------|---------|--------|-------|-------| -| **Julia** | [PolyglotFormalisms.jl](https://github.com/hyperpolymath/PolyglotFormalisms.jl) | 0.3.0 | ✅ Complete | 287/287 | Reference implementation | -| **ReScript** | [alib-for-rescript](https://github.com/hyperpolymath/alib-for-rescript) | 0.3.0 | ✅ Complete | Full coverage | packages/common/ | -| **Gleam** | [polyglot_formalisms_gleam](https://github.com/hyperpolymath/polyglot_formalisms_gleam) | 0.3.0 | ✅ Complete | 131/131 | BEAM runtime, gleeunit tests | -| **Elixir** | [polyglot_formalisms_elixir](https://github.com/hyperpolymath/polyglot_formalisms_elixir) | 0.3.0 | ✅ Complete | 253/253 | 120 doctests + 133 unit tests | - -## Module Completion Status - -### Arithmetic Module - -| Operation | Julia | ReScript | Gleam | Elixir | Notes | -|-----------|-------|----------|-------|--------|-------| -| `add` | ✅ | ✅ | ✅ | ✅ | Float operation | -| `subtract` | ✅ | ✅ | ✅ | ✅ | Float operation | -| `multiply` | ✅ | ✅ | ✅ | ✅ | Float operation | -| `divide` | ✅ | ✅ | ✅ | ✅ | Float operation | -| `modulo` | ✅ | ✅ | ✅ | ✅ | Integer operation | - -### Comparison Module - -| Operation | Julia | ReScript | Gleam | Elixir | Notes | -|-----------|-------|----------|-------|--------|-------| -| `less_than` | ✅ | ✅ | ✅ | ✅ | Float comparison | -| `greater_than` | ✅ | ✅ | ✅ | ✅ | Float comparison | -| `equal` | ✅ | ✅ | ✅ | ✅ | Float comparison | -| `not_equal` | ✅ | ✅ | ✅ | ✅ | Float comparison | -| `less_equal` | ✅ | ✅ | ✅ | ✅ | Float comparison | -| `greater_equal` | ✅ | ✅ | ✅ | ✅ | Float comparison | - -### Logical Module - -| Operation | Julia | ReScript | Gleam | Elixir | Notes | -|-----------|-------|----------|-------|--------|-------| -| `and` | ✅ | ✅ | ✅ | ✅ `logical_and` | Elixir renamed due to keyword conflict | -| `or` | ✅ | ✅ | ✅ | ✅ `logical_or` | Elixir renamed due to keyword conflict | -| `not` | ✅ | ✅ | ✅ | ✅ `logical_not` | Elixir renamed due to keyword conflict | - -### String Module - -| Operation | Julia | ReScript | Gleam | Elixir | Notes | -|-----------|-------|----------|-------|--------|-------| -| `concat` | ✅ | ✅ | ✅ | ✅ | String concatenation | -| `length` | ✅ | ✅ | ✅ | ✅ `string_length` | Elixir renamed to avoid stdlib conflict | -| `substring` | ✅ | ✅ | ✅ | ✅ | Julia/Elixir: 1-based; ReScript/Gleam: 0-based | -| `index_of` | ✅ | ✅ | ✅ | ✅ | Julia/Elixir: returns 0 when not found; ReScript/Gleam: returns -1 | -| `contains` | ✅ | ✅ | ✅ | ✅ `string_contains` | Elixir renamed to avoid stdlib conflict | -| `starts_with` | ✅ | ✅ | ✅ | ✅ | Prefix check | -| `ends_with` | ✅ | ✅ | ✅ | ✅ | Suffix check | -| `to_uppercase` | ✅ | ✅ | ✅ | ✅ | Unicode-aware | -| `to_lowercase` | ✅ | ✅ | ✅ | ✅ | Unicode-aware | -| `trim` | ✅ | ✅ | ✅ | ✅ `string_trim` | Elixir renamed to avoid stdlib conflict | -| `split` | ✅ | ✅ | ✅ | ✅ `string_split` | Elixir renamed to avoid stdlib conflict | -| `join` | ✅ | ✅ | ✅ | ✅ `string_join` | Elixir renamed to avoid stdlib conflict | -| `replace` | ✅ | ✅ | ✅ | ✅ `string_replace` | Elixir renamed to avoid stdlib conflict | -| `is_empty` | ✅ | ✅ | ✅ | ✅ | Boolean check | - -## Language-Specific Implementation Notes - -### Julia (Reference Implementation) -- **File locations**: `src/arithmetic.jl`, `src/comparison.jl`, `src/logical.jl`, `src/string.jl` -- **Test locations**: `test/arithmetic_tests.jl`, `test/comparison_tests.jl`, `test/logical_tests.jl`, `test/string_tests.jl` -- **Operators**: Standard Julia operators (`+`, `-`, `*`, `/`, `mod`, `<`, `>`, `==`, `&&`, `||`, `!`) -- **Type system**: Generic `Number` and `Bool` types, `AbstractString` for strings -- **Test framework**: Test.jl with `@testset` and `@test` macros -- **Total tests**: 287 (59 arithmetic + 98 comparison + 41 logical + 89 string) -- **String indexing**: 1-based (Julia convention) - -### ReScript -- **File locations**: `packages/common/Arithmetic.res`, `packages/common/Comparison.res`, `packages/common/Logical.res`, `packages/common/String.res` -- **Test locations**: `tests/Arithmetic_test.res`, `tests/Comparison_test.res`, `tests/Logical_test.res`, `tests/String_test.res` -- **Operators**: Float-specific operators (`+.`, `-.`, `*.`, `/.`, standard comparison, `&&`, `||`, `!`) -- **Type system**: Explicit `float`, `bool`, and `string` types -- **Test framework**: RescriptMocha -- **Modulo**: Uses `mod_float` for float modulo operation -- **String indexing**: 0-based (JavaScript/ReScript convention) -- **String operators**: Uses `++` for concatenation, standard String module functions - -### Gleam -- **File locations**: `src/arithmetic.gleam`, `src/comparison.gleam`, `src/logical.gleam`, `src/string_ops.gleam` -- **Test locations**: `test/arithmetic_test.gleam`, `test/comparison_test.gleam`, `test/logical_test.gleam`, `test/string_ops_test.gleam` -- **Operators**: - - Arithmetic: `+.`, `-.`, `*.`, `/.` (dot required for floats) - - Ordering: `<.`, `>.`, `<=.`, `>=.` (dot required for floats) - - Equality: `==`, `!=` (no dot, works for all types) - - Logical: `&&`, `||`, `!` - - String: `<>` for concatenation -- **Type system**: Separate `Float`, `Int`, `Bool`, and `String` types -- **Runtime**: BEAM (Erlang VM) or JavaScript -- **Modulo**: Integer operation using `%` -- **Test framework**: Gleeunit -- **Total tests**: 131 (28 arithmetic + 35 comparison + 22 logical + 7 property tests + 39 string) -- **String indexing**: 0-based (Gleam convention) -- **String graphemes**: Uses grapheme-aware length and splitting - -### Elixir -- **File locations**: `lib/arithmetic.ex`, `lib/comparison.ex`, `lib/logical.ex`, `lib/string_ops.ex` -- **Test locations**: `test/arithmetic_test.exs`, `test/comparison_test.exs`, `test/logical_test.exs`, `test/string_ops_test.exs` -- **Operators**: Standard Elixir operators (automatically promoted to float for division), `<>` for string concatenation -- **Type system**: Dynamic with guards and `@spec` annotations -- **Runtime**: BEAM (Erlang VM) -- **Modulo**: Uses `rem` for remainder (Erlang semantics) -- **Test framework**: ExUnit with doctests -- **Total tests**: 253 (120 doctests + 133 unit tests) -- **Naming exceptions**: - - Logical: `logical_and`, `logical_or`, `logical_not` (to avoid Kernel keyword conflicts) - - String: `string_length`, `string_contains`, `string_trim`, `string_split`, `string_join`, `string_replace` (to avoid stdlib conflicts) -- **String indexing**: 1-based (matching Julia for cross-language consistency) -- **String graphemes**: Uses grapheme-aware operations - -## Operator Comparison Table - -| Operation | Julia | ReScript | Gleam | Elixir | -|-----------|-------|----------|-------|--------| -| Float addition | `+` | `+.` | `+.` | `+` | -| Float subtraction | `-` | `-.` | `-.` | `-` | -| Float multiplication | `*` | `*.` | `*.` | `*` | -| Float division | `/` | `/.` | `/.` | `/` | -| Integer modulo | `mod` | `mod` | `%` | `rem` | -| Less than (float) | `<` | `<` | `<.` | `<` | -| Greater than (float) | `>` | `>` | `>.` | `>` | -| Equal (any type) | `==` | `==` | `==` | `==` | -| Not equal (any type) | `!=` | `!=` | `!=` | `!=` | -| Less or equal (float) | `<=` | `<=` | `<=.` | `<=` | -| Greater or equal (float) | `>=` | `>=` | `>=.` | `>=` | -| Logical AND | `&&` | `&&` | `&&` | `and` | -| Logical OR | `\|\|` | `\|\|` | `\|\|` | `or` | -| Logical NOT | `!` | `!` | `!` | `not` | - -**Note:** Gleam uses dotted operators (`+.`, `<.`, etc.) only for arithmetic and float ordering comparisons, but not for equality (`==`, `!=`), which works for all types. - -## Semantic Equivalence - -All implementations maintain semantic equivalence across languages: - -### Behavioral Consistency -1. **Mathematical properties preserved**: - - Commutativity, associativity, distributivity (where applicable) - - Identity elements and annihilators - - Transitivity, reflexivity, symmetry (for comparisons) - - Boolean algebra laws (De Morgan's, excluded middle, non-contradiction) - -2. **IEEE 754 floating-point semantics**: - - Division by zero behavior - - NaN propagation - - Infinity handling - - Signed zeros - -3. **Edge cases handled consistently**: - - All languages follow their runtime's floating-point model - - Integer operations respect overflow/underflow behavior - - Modulo follows BEAM `rem` semantics (Gleam/Elixir) or language-specific - -### Verification Strategy - -Cross-language verification is achieved through: - -1. **Property-based testing**: All implementations test the same mathematical properties -2. **Canonical test suite**: Test cases match across all languages -3. **Edge case coverage**: Identical edge case handling (NaN, Inf, signed zeros) -4. **Documentation**: All implementations document the same behavioral semantics - -## Future Work - -### Pending Implementations -- **Python** (planned) -- **Rust** (planned) -- **Haskell** (planned) -- **OCaml** (planned) - -### Pending Tasks -1. Create Gleam test suite (gleeunit) -2. Formal verification proofs (using Isabelle/HOL or Coq) -3. Property-based tests using QuickCheck-style frameworks -4. Cross-language fuzzing for edge case discovery -5. Performance benchmarks across implementations -6. Automated semantic equivalence verification - -## License - -All implementations use MPL-2.0 (Palimpsest Meta-Public License). - -## Contributing - -When adding a new language implementation: - -1. Create a new repository following naming convention: `polyglot_formalisms_{language}` -2. Implement all three modules (Arithmetic, Comparison, Logical) -3. Maintain semantic equivalence with reference implementation -4. Include comprehensive test suite (unit tests + property tests) -5. Document language-specific considerations -6. Update this status document - -## References - -- [PolyglotFormalisms Specification](https://github.com/hyperpolymath/PolyglotFormalisms.jl) -- [IEEE 754 Floating-Point Standard](https://ieeexplore.ieee.org/document/8766229) -- [Boolean Algebra](https://en.wikipedia.org/wiki/Boolean_algebra) diff --git a/packages/PostDisciplinary.jl/ABI-FFI-README.adoc b/packages/PostDisciplinary.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..46c07c05c --- /dev/null +++ b/packages/PostDisciplinary.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/%7B%7BOWNER%7D%7D/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/PostDisciplinary.jl/ABI-FFI-README.md b/packages/PostDisciplinary.jl/ABI-FFI-README.md deleted file mode 100644 index 320b3f6fa..000000000 --- a/packages/PostDisciplinary.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/PostDisciplinary.jl/CHANGELOG.adoc b/packages/PostDisciplinary.jl/CHANGELOG.adoc new file mode 100644 index 000000000..ca1c65289 --- /dev/null +++ b/packages/PostDisciplinary.jl/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/packages/PostDisciplinary.jl/CHANGELOG.md b/packages/PostDisciplinary.jl/CHANGELOG.md deleted file mode 100644 index 810947691..000000000 --- a/packages/PostDisciplinary.jl/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/packages/PostDisciplinary.jl/CODE_OF_CONDUCT.adoc b/packages/PostDisciplinary.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/PostDisciplinary.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/PostDisciplinary.jl/CODE_OF_CONDUCT.md b/packages/PostDisciplinary.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/PostDisciplinary.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/PostDisciplinary.jl/CONTRIBUTING.adoc b/packages/PostDisciplinary.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..ad866b5ab --- /dev/null +++ b/packages/PostDisciplinary.jl/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/PostDisciplinary.jl/CONTRIBUTING.md b/packages/PostDisciplinary.jl/CONTRIBUTING.md deleted file mode 100644 index 02758c676..000000000 --- a/packages/PostDisciplinary.jl/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/PostDisciplinary.jl/GOVERNANCE.adoc b/packages/PostDisciplinary.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..6dddd7a45 --- /dev/null +++ b/packages/PostDisciplinary.jl/GOVERNANCE.adoc @@ -0,0 +1,176 @@ +== Project Governance + +This document describes the governance model for *\{\{PROJECT_NAME}}*. + +''''' + +=== Project Governance Model + +\{\{PROJECT_NAME}} follows a *Benevolent Dictator For Life (BDFL)* +governance model. This model is well-suited for solo maintainers and +small project teams where rapid, consistent decision-making is more +valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including +technical direction, release schedules, contributor access, and +community standards. + +____ +*Transition clause:* When the core team exceeds three active +maintainers, this project should transition to a *consensus-based +governance model* with documented voting procedures. That transition +should itself be recorded as an Architecture Decision Record (ADR) in +`+docs/decisions/+`. +____ + +''''' + +=== Decision Making + +==== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (bug fixes, dependency updates, minor improvements) +may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on +non-trivial changes. + +==== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new features, breaking changes, architectural +shifts) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +==== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs in +`+docs/decisions/+`. +* ADR statuses: `+proposed+`, `+accepted+`, `+deprecated+`, +`+superseded+`, `+rejected+`. +* ADRs provide a historical record of why decisions were made and what +alternatives were considered. +* See `+.machine_readable/META.a2ml+` for the machine-readable ADR +index. + +''''' + +=== Roles + +==== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project’s technical direction and long-term vision. +* Has final say on all matters, including maintainer appointments and +removals. +* Responsible for ensuring the project adheres to RSR standards. + +==== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages releases. +* Upholds code quality, security standards, and the Code of Conduct. +* Listed in MAINTAINERS.md. + +==== Contributor + +* Anyone who submits pull requests, opens issues, or participates in +discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +==== Bot + +* Automated agents managed via your bot orchestration system. +* Perform automated code review, security scanning, dependency updates, +and standards enforcement. +* Bot actions are subject to the same quality and review standards as +human contributions. +* Configure your bots in `+.machine_readable/bot_directives/+`. + +''''' + +=== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they +demonstrate: + +[arabic] +. *Sustained quality contributions* – a track record of well-crafted +pull requests that follow project conventions and require minimal +revision. +. *Understanding of RSR standards* – familiarity with the Repository +Structure Requirements, security policies, and CI/CD workflows used +across the project. +. *Constructive participation* – helpful issue triage, thoughtful code +review comments, and mentoring of other contributors. +. *Reliability* – consistent engagement over a meaningful period +(typically 3+ months of active contribution). + +==== Process + +[arabic] +. An existing maintainer nominates the candidate by opening a private +discussion with the BDFL. +. The BDFL reviews the candidate’s contribution history and community +interactions. +. The BDFL approves or declines the nomination, with reasoning provided +to the nominator. +. If approved, the new maintainer is added to MAINTAINERS.md and granted +appropriate repository access. + +''''' + +=== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more +consecutive months. The maintainer will be contacted before removal and +offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the +link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the +enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons +(e.g., repeated disregard for project standards, loss of trust). +Reasoning will be documented privately. + +Removed maintainers are moved to the Emeritus section of MAINTAINERS.md +unless removal was due to a serious Code of Conduct violation. + +''''' + +=== Code of Conduct + +All participants in this project are expected to follow the +link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to +all project spaces, including issues, pull requests, discussions, and +any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The +BDFL serves as the final arbiter in conduct disputes. + +''''' + +=== Amendments + +This governance document may be amended by the BDFL at any time. All +amendments will be: + +[arabic] +. Documented as an ADR in `+docs/decisions/+` explaining the rationale +for the change. +. Committed to the repository with a clear commit message. +. Communicated to existing maintainers and contributors via the +project’s usual channels. + +Substantive changes (e.g., changing the governance model itself) should +be discussed with the community before adoption, even though the BDFL +retains final authority. + +''''' + +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PostDisciplinary.jl/GOVERNANCE.md b/packages/PostDisciplinary.jl/GOVERNANCE.md deleted file mode 100644 index 5f082df92..000000000 --- a/packages/PostDisciplinary.jl/GOVERNANCE.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PostDisciplinary.jl/MAINTAINERS.adoc b/packages/PostDisciplinary.jl/MAINTAINERS.adoc index d829dd959..f3a0e022b 100644 --- a/packages/PostDisciplinary.jl/MAINTAINERS.adoc +++ b/packages/PostDisciplinary.jl/MAINTAINERS.adoc @@ -1,47 +1,43 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of +*\{\{PROJECT_NAME}}*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|\{\{AUTHOR}} |https://github.com/%7B%7BOWNER%7D%7D[@\{OWNER}] |BDFL +|\{\{CURRENT_DATE}} |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PostDisciplinary.jl/MAINTAINERS.md b/packages/PostDisciplinary.jl/MAINTAINERS.md deleted file mode 100644 index 32b92cc4a..000000000 --- a/packages/PostDisciplinary.jl/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **{{PROJECT_NAME}}**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| {{AUTHOR}} | [@{{OWNER}}](https://github.com/{{OWNER}}) | BDFL | {{CURRENT_DATE}} | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/PostDisciplinary.jl/PLACEHOLDERS.adoc b/packages/PostDisciplinary.jl/PLACEHOLDERS.adoc new file mode 100644 index 000000000..1ec75339b --- /dev/null +++ b/packages/PostDisciplinary.jl/PLACEHOLDERS.adoc @@ -0,0 +1,191 @@ +== Template Placeholders + +All placeholders in this template follow the `+{{PLACEHOLDER}}+` +pattern. After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) +sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) +sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) +sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) +sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) +sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) +sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) +sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{AUTHOR}}+` |Full legal name |`+Jane Doe+` |SPDX headers (all +files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md + +|`+{{AUTHOR_EMAIL}}+` |Primary contact email |`+jane@example.org+` |SPDX +headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+{{AUTHOR_LAST}}+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_FIRST}}+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_INITIALS}}+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{PROJECT_NAME}}+` |Human-readable project name |`+My Project+` +|SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, +GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json + +|`+{{PROJECT_DESCRIPTION}}+` |One-line description |`+A tool for X+` +|flake.nix + +|`+{{PROJECT}}+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+{{REPO}}+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+{{OWNER}}+` |GitHub/GitLab org or username |`+my-org+` |SPDX headers, +CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, +mirror.yml, cliff.toml + +|`+{{FORGE}}+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{CURRENT_YEAR}}+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+{{CURRENT_DATE}}+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+{{DATE}}+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{SECURITY_EMAIL}}+` |Security contact email +|`+security@example.org+` |SECURITY.md + +|`+{{PGP_FINGERPRINT}}+` |40-char PGP fingerprint |`+ABCD 1234 ...+` +|SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{MAIN_BRANCH}}+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{LICENSE}}+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+{{PROJECT_PURPOSE}}+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/packages/PostDisciplinary.jl/PLACEHOLDERS.md b/packages/PostDisciplinary.jl/PLACEHOLDERS.md deleted file mode 100644 index b6c9d28cc..000000000 --- a/packages/PostDisciplinary.jl/PLACEHOLDERS.md +++ /dev/null @@ -1,120 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/packages/PostDisciplinary.jl/SECURITY.adoc b/packages/PostDisciplinary.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/PostDisciplinary.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/PostDisciplinary.jl/SECURITY.md b/packages/PostDisciplinary.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/PostDisciplinary.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/PostDisciplinary.jl/TOPOLOGY.md b/packages/PostDisciplinary.jl/TOPOLOGY.adoc similarity index 90% rename from packages/PostDisciplinary.jl/TOPOLOGY.md rename to packages/PostDisciplinary.jl/TOPOLOGY.adoc index dd2aafed5..7c390b772 100644 --- a/packages/PostDisciplinary.jl/TOPOLOGY.md +++ b/packages/PostDisciplinary.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== PostDisciplinary.jl — Project Topology -# PostDisciplinary.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -48,11 +44,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ORCHESTRATION @@ -76,26 +72,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~60% Initial Orchestration Layer -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Universal Ontology ──────► Research Project ──────► Cross-Theory Verification │ Synthesis Engine ◀──────── Meta-Analysis ◀──────────┘ │ Impact Tracking ──────► Synthesis Report ─────► COMPLETE -``` +.... -## 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/packages/PostDisciplinary.jl/docs/AI-CONVENTIONS.adoc b/packages/PostDisciplinary.jl/docs/AI-CONVENTIONS.adoc new file mode 100644 index 000000000..ba7e4ae74 --- /dev/null +++ b/packages/PostDisciplinary.jl/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,81 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *\{\{AUTHOR}}* +* Email: *\{\{AUTHOR_EMAIL}}* +* Copyright: +`+Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>+` + +=== State Files + +State/metadata files (.a2ml) belong in `+.machine_readable/+` ONLY. +NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, +NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state diff --git a/packages/PostDisciplinary.jl/docs/AI-CONVENTIONS.md b/packages/PostDisciplinary.jl/docs/AI-CONVENTIONS.md deleted file mode 100644 index 37f594d12..000000000 --- a/packages/PostDisciplinary.jl/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,75 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state diff --git a/packages/PostDisciplinary.jl/docs/QUICKSTART.adoc b/packages/PostDisciplinary.jl/docs/QUICKSTART.adoc new file mode 100644 index 000000000..f000d4a13 --- /dev/null +++ b/packages/PostDisciplinary.jl/docs/QUICKSTART.adoc @@ -0,0 +1,70 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/{{REPO}}.git +cd {{REPO}} +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +if you get stuck. diff --git a/packages/PostDisciplinary.jl/docs/QUICKSTART.md b/packages/PostDisciplinary.jl/docs/QUICKSTART.md deleted file mode 100644 index 724d8e111..000000000 --- a/packages/PostDisciplinary.jl/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/{{OWNER}}/{{REPO}}.git -cd {{REPO}} -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/{{OWNER}}/{{REPO}}/discussions) -if you get stuck. diff --git a/packages/PostDisciplinary.jl/docs/THREAT-MODEL.adoc b/packages/PostDisciplinary.jl/docs/THREAT-MODEL.adoc new file mode 100644 index 000000000..35aa8cc8e --- /dev/null +++ b/packages/PostDisciplinary.jl/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: \{\{PROJECT_NAME}} + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |\{\{PROJECT_NAME}} +|Version |1.0 +|Last Reviewed |\{\{DATE}} +|Author |\{\{AUTHOR}} +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of \{\{PROJECT_NAME}} and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/packages/PostDisciplinary.jl/docs/THREAT-MODEL.md b/packages/PostDisciplinary.jl/docs/THREAT-MODEL.md deleted file mode 100644 index c33fe79d8..000000000 --- a/packages/PostDisciplinary.jl/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/packages/PostDisciplinary.jl/docs/decisions/0000-template.adoc b/packages/PostDisciplinary.jl/docs/decisions/0000-template.adoc new file mode 100644 index 000000000..de603adff --- /dev/null +++ b/packages/PostDisciplinary.jl/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/packages/PostDisciplinary.jl/docs/decisions/0000-template.md b/packages/PostDisciplinary.jl/docs/decisions/0000-template.md deleted file mode 100644 index 2f7fc67de..000000000 --- a/packages/PostDisciplinary.jl/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/packages/PostDisciplinary.jl/docs/decisions/0001-adopt-rsr-standard.adoc b/packages/PostDisciplinary.jl/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 000000000..8e404cbbc --- /dev/null +++ b/packages/PostDisciplinary.jl/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/packages/PostDisciplinary.jl/docs/decisions/0001-adopt-rsr-standard.md b/packages/PostDisciplinary.jl/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index 806942f67..000000000 --- a/packages/PostDisciplinary.jl/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/packages/PostDisciplinary.jl/docs/decisions/README.adoc b/packages/PostDisciplinary.jl/docs/decisions/README.adoc new file mode 100644 index 000000000..3dc7a4856 --- /dev/null +++ b/packages/PostDisciplinary.jl/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/packages/PostDisciplinary.jl/docs/decisions/README.md b/packages/PostDisciplinary.jl/docs/decisions/README.md deleted file mode 100644 index 79851eea4..000000000 --- a/packages/PostDisciplinary.jl/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/packages/ProvenCrypto.jl/ABI-FFI-README.md b/packages/ProvenCrypto.jl/ABI-FFI-README.adoc similarity index 74% rename from packages/ProvenCrypto.jl/ABI-FFI-README.md rename to packages/ProvenCrypto.jl/ABI-FFI-README.adoc index 25c0a3246..3d414453c 100644 --- a/packages/ProvenCrypto.jl/ABI-FFI-README.md +++ b/packages/ProvenCrypto.jl/ABI-FFI-README.adoc @@ -1,19 +1,22 @@ -{{~ Aditionally delete this line and fill out the template below ~}} +\{\{~ Aditionally delete this line and fill out the template below ~}} -# ProvenCrypto ABI/FFI Documentation +== ProvenCrypto ABI/FFI Documentation -## Overview +=== Overview -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -## Architecture +=== Architecture -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -45,11 +48,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... provencrypto/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -77,15 +80,17 @@ provencrypto/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -97,13 +102,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -111,13 +117,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -125,13 +132,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -140,71 +148,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -215,13 +230,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "{{project}}.h" int main() { @@ -237,16 +253,19 @@ int main() { {{project}}_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -l{{project}} -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import {{PROJECT}}.ABI.Foreign main : IO () @@ -259,11 +278,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "{{project}}")] extern "C" { fn {{project}}_init() -> *mut std::ffi::c_void; @@ -282,11 +302,12 @@ fn main() { {{project}}_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const lib{{project}} = "lib{{project}}" function init() @@ -312,27 +333,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -342,44 +366,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/ProvenCrypto.jl/CHANGELOG.adoc b/packages/ProvenCrypto.jl/CHANGELOG.adoc new file mode 100644 index 000000000..b6b90eafb --- /dev/null +++ b/packages/ProvenCrypto.jl/CHANGELOG.adoc @@ -0,0 +1,90 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/[Keep a Changelog], +and this project adheres to +https://semver.org/semver/1.0.0.html[Semantic Versioning]. + +''''' + +=== [Unreleased] + +==== Added + +* Placeholder for future changes. + +''''' + +=== [0.1.1] - 2026-01-27 + +==== Fixed + +* *Backend Detection*: Resolved duplicate `+cuda_available()+` method +definition, ensuring GPU extensions load correctly. +* *Precompilation*: Eliminated method overwriting errors during module +precompilation. +* *Fallback Logic*: Improved automatic fallback to CPU with +SIMD/multithreading support when GPU backends are unavailable. + +==== Changed + +* *Dependencies*: Added `+Preferences.jl+` for user-configurable +fallback behavior (e.g., force CPU-only mode). +* *Documentation*: Clarified installation instructions for GPU backends +(CUDA/ROCm/Metal) in `+README.md+`. +* *Version Bump*: Updated to `+0.1.1+` to reflect fixes and +compatibility improvements. + +==== Added + +* *Automatic SIMD Detection*: Robust detection of AVX2/AVX512/NEON/SVE +for CPU fallback. +* *Thread Auto-Detection*: Automatically leverages all available CPU +threads (`+Threads.nthreads()+`). +* *Extension System*: Formalized `+ext/+` directory for optional GPU +backends (CUDA, ROCm, Metal, oneAPI). + +==== Security + +* *Isolation*: Ensured GPU extensions respect *rootless container* +environments (compatible with *svalinn/vordr*, *nerdctl*, and +*SELinux/AppArmor*). +* *Zero Trust Alignment*: GPU backends are *optional* and +*non-proprietary*, loading only when explicitly available. + +==== Deployment + +* *Compatibility*: Tested with *Julia 1.9+*, aligning with +*ReScript/Hypatia* toolchains. +* *Containerization*: Validated for *OCI-standard* deployments (e.g., +*Chainguard images* via *podman*). + +''''' + +=== [0.1.0] - 2026-01-25 + +==== Added + +* *Initial Release*: Core cryptographic backend abstraction for: +** NVIDIA CUDA (Tensor cores). +** AMD ROCm (Matrix cores). +** Apple Metal (Neural Engine). +** Intel oneAPI (NPU/GPU). +** CPU SIMD (AVX2, AVX-512, NEON, SVE). +* *Extensions*: Modular support for optional hardware backends. +* *Formal Methods*: Weak dependency on `+SMTLib.jl+` for verification +integration. +* *Project Structure*: `+src/+`, `+ext/+`, and `+Project.toml+` for +modular deployment. + +==== Notes + +* Designed for integration with *Hypatia* (CI/CD) and *ReScript* +projects. +* Defaults to *CPU fallback* in *Software-Defined Perimeter (SDP)* +environments (e.g., behind *Cloudflare Zero Trust*). +* Container-ready: Compatible with *rootless containers* and *WASM +proxies*. + +''''' diff --git a/packages/ProvenCrypto.jl/CHANGELOG.md b/packages/ProvenCrypto.jl/CHANGELOG.md deleted file mode 100644 index 73c8e6444..000000000 --- a/packages/ProvenCrypto.jl/CHANGELOG.md +++ /dev/null @@ -1,58 +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/), -and this project adheres to [Semantic Versioning](https://semver.org/semver/1.0.0.html). - ---- - -## [Unreleased] -### Added -- Placeholder for future changes. - ---- - -## [0.1.1] - 2026-01-27 -### Fixed -- **Backend Detection**: Resolved duplicate `cuda_available()` method definition, ensuring GPU extensions load correctly. -- **Precompilation**: Eliminated method overwriting errors during module precompilation. -- **Fallback Logic**: Improved automatic fallback to CPU with SIMD/multithreading support when GPU backends are unavailable. - -### Changed -- **Dependencies**: Added `Preferences.jl` for user-configurable fallback behavior (e.g., force CPU-only mode). -- **Documentation**: Clarified installation instructions for GPU backends (CUDA/ROCm/Metal) in `README.md`. -- **Version Bump**: Updated to `0.1.1` to reflect fixes and compatibility improvements. - -### Added -- **Automatic SIMD Detection**: Robust detection of AVX2/AVX512/NEON/SVE for CPU fallback. -- **Thread Auto-Detection**: Automatically leverages all available CPU threads (`Threads.nthreads()`). -- **Extension System**: Formalized `ext/` directory for optional GPU backends (CUDA, ROCm, Metal, oneAPI). - -### Security -- **Isolation**: Ensured GPU extensions respect **rootless container** environments (compatible with **svalinn/vordr**, **nerdctl**, and **SELinux/AppArmor**). -- **Zero Trust Alignment**: GPU backends are **optional** and **non-proprietary**, loading only when explicitly available. - -### Deployment -- **Compatibility**: Tested with **Julia 1.9+**, aligning with **ReScript/Hypatia** toolchains. -- **Containerization**: Validated for **OCI-standard** deployments (e.g., **Chainguard images** via **podman**). - ---- - -## [0.1.0] - 2026-01-25 -### Added -- **Initial Release**: Core cryptographic backend abstraction for: - - NVIDIA CUDA (Tensor cores). - - AMD ROCm (Matrix cores). - - Apple Metal (Neural Engine). - - Intel oneAPI (NPU/GPU). - - CPU SIMD (AVX2, AVX-512, NEON, SVE). -- **Extensions**: Modular support for optional hardware backends. -- **Formal Methods**: Weak dependency on `SMTLib.jl` for verification integration. -- **Project Structure**: `src/`, `ext/`, and `Project.toml` for modular deployment. - -### Notes -- Designed for integration with **Hypatia** (CI/CD) and **ReScript** projects. -- Defaults to **CPU fallback** in **Software-Defined Perimeter (SDP)** environments (e.g., behind **Cloudflare Zero Trust**). -- Container-ready: Compatible with **rootless containers** and **WASM proxies**. - ---- diff --git a/packages/ProvenCrypto.jl/CODE_OF_CONDUCT.adoc b/packages/ProvenCrypto.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/ProvenCrypto.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/ProvenCrypto.jl/CODE_OF_CONDUCT.md b/packages/ProvenCrypto.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/ProvenCrypto.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/ProvenCrypto.jl/CONTRIBUTING.adoc b/packages/ProvenCrypto.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/ProvenCrypto.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/ProvenCrypto.jl/CONTRIBUTING.md b/packages/ProvenCrypto.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/ProvenCrypto.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/ProvenCrypto.jl/README.adoc b/packages/ProvenCrypto.jl/README.adoc index 24c42a015..fd1d080c2 100644 --- a/packages/ProvenCrypto.jl/README.adoc +++ b/packages/ProvenCrypto.jl/README.adoc @@ -1,50 +1,60 @@ -= ProvenCrypto.jl: Formally Verified Cryptographic Protocols for Julia -:toc: macro -:toc-title: -:toclevels: 3 +== ProvenCrypto.jl -toc::[] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Project +Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-90%25-green[Completion +Status]] -== Overview +.... +╔═══════════════════════════╗ +║ IDRIS INSIDE 🟦 ║ +║ Formally Verified ║ +║ Dependent Type Checked ║ +╚═══════════════════════════╝ +.... -ProvenCrypto.jl provides a Julia library of *formally verified* cryptographic protocols and post-quantum primitives. This project is part of the hyperpolymath ecosystem, emphasizing mathematical proofs of correctness, security, and robustness. +Formally verified cryptographic protocols and post-quantum primitives +for Julia. -== Features +=== Features -* **Formal Verification**: All cryptographic primitives are accompanied by machine-checked proofs of security properties. -* **Post-Quantum Security**: Includes algorithms resistant to quantum computing attacks. -* **Julia Integration**: Designed for high performance and seamless integration with the Julia scientific computing ecosystem. -* **Interoperability**: Follows the Hyperpolymath Universal Standard for ABI/FFI, ensuring compatibility with other languages and systems. +==== Post-Quantum Cryptography -== Directory Structure +* *Kyber*: KEM (Key Encapsulation Mechanism) - NIST PQC winner +* *Dilithium*: Digital signatures - NIST PQC winner +* *SPHINCS+*: Hash-based signatures (conservative security) -[source] ----- -ProvenCrypto.jl/ -├── src/ # Main Julia source code -├── proofs/ # Formal proofs (Idris2/Lean/Coq) -├── bindings/ # Language bindings (optional) -├── test/ # Unit and property tests -├── docs/ # Documentation -└── examples/ # Usage examples ----- +==== Protocol Implementations + +* *Noise Protocol Framework*: Modern secure channel (WireGuard, +Lightning) +* *Signal Protocol*: Double Ratchet for messaging +* *TLS 1.3*: Reference implementation (educational) -== Core Components +==== Zero-Knowledge Proofs -=== 1. Cryptographic Primitives +* *zk-SNARKs*: Groth16, PLONK, Halo2 +* *zk-STARKs*: Transparent, post-quantum secure -* **Symmetric Encryption**: AES, ChaCha20 (with formal proofs) -* **Asymmetric Encryption**: Kyber, Dilithium (post-quantum) -* **Hash Functions**: SHA-3, BLAKE3 (with collision resistance proofs) -* **Signatures**: Ed25519, SPHINCS+ (post-quantum) +==== Threshold Cryptography -=== 2. Formal Proofs +* *Shamir Secret Sharing*: M-of-N key recovery +* *Distributed Key Generation*: Multi-party computation -* **Correctness**: Proofs that implementations match their mathematical specifications. -* **Security**: Proofs of resistance to known attacks (e.g., side-channel, quantum). -* **Interoperability**: Proofs of ABI/FFI compliance for cross-language use. +==== Hardware Acceleration -== Usage +* *GPU*: CUDA (NVIDIA), ROCm (AMD), Metal (Apple) +* *NPU/TPU*: Intel oneAPI, Google TPU, Apple Neural Engine +* *Crypto Instructions*: AES-NI, SHA extensions, Intel QAT +* *Secure Enclaves*: Intel SGX, AMD SEV, ARM TrustZone +* *Multi-platform*: x86, ARM, RISC-V, Apple Silicon + +==== Formal Verification + +* *SMT Integration*: Z3, CVC5, Yices, MathSAT +* *Proof Assistants*: Idris 2, Lean 4, Coq, Isabelle/HOL +* *Property Verification*: Correctness, security properties +* *Proof Export*: Long-term formalization === Installation @@ -54,39 +64,238 @@ using Pkg Pkg.add(url="https://github.com/hyperpolymath/ProvenCrypto.jl") ---- -=== Example: Secure Key Exchange +==== System Dependencies + +===== libsodium (required for primitives) + +[source,bash] +---- +# macOS +brew install libsodium + +# Ubuntu/Debian +sudo apt install libsodium-dev + +# Fedora +sudo dnf install libsodium-devel + +# Arch +sudo pacman -S libsodium +---- + +=== Usage + +==== Post-Quantum Key Exchange (Kyber) + +[source,julia] +---- +using ProvenCrypto + +# Generate keypair +(pk, sk) = kyber_keygen(768) # AES-192 equivalent security + +# Sender: Encapsulate shared secret +(ciphertext, shared_secret_sender) = kyber_encapsulate(pk) + +# Receiver: Decapsulate +shared_secret_receiver = kyber_decapsulate(sk, ciphertext) + +@assert shared_secret_sender == shared_secret_receiver +---- + +==== Post-Quantum Signatures (Dilithium) + +[source,julia] +---- +using ProvenCrypto + +# Generate signing keypair +(pk, sk) = dilithium_keygen(3) # AES-192 equivalent security + +# Sign message +message = b"Hello, post-quantum world!" +signature = dilithium_sign(sk, message) + +# Verify +is_valid = dilithium_verify(pk, message, signature) +@assert is_valid +---- + +==== Authenticated Encryption (libsodium FFI) [source,julia] ---- using ProvenCrypto -# Generate a post-quantum key pair -(sk, pk) = generate_keypair(:kyber) +# Generate key and nonce +key = rand(UInt8, 32) +nonce = rand(UInt8, 12) # Must be unique per message! -# Encrypt/decrypt with formal guarantees -ciphertext = encrypt(pk, "secret message") -plaintext = decrypt(sk, ciphertext) +# Encrypt +plaintext = b"Secret message" +ciphertext = aead_encrypt(key, nonce, plaintext) + +# Decrypt +recovered = aead_decrypt(key, nonce, ciphertext) +@assert recovered == plaintext +---- + +==== Hardware-Accelerated Operations + +[source,julia] ---- +using ProvenCrypto + +# Detect available hardware +backend = detect_hardware() +println(backend) +# Output: MetalBackend(M3 + Neural Engine) +# or: CUDABackend(device=0, CC=8.9) +# or: CPUBackend(avx512, 16 threads) + +# Operations automatically use best backend +features = detect_hardware_features() +print_hardware_report(features) +---- + +=== Security Warnings + +==== ⚠️ Production Use -== Verification +*This library is for research and educational purposes.* -All proofs are available in the `proofs/` directory and can be checked using: +For production systems, use: - *Symmetric crypto*: libsodium (via FFI +wrappers in this library) - *Classical asymmetric*: OpenSSL FIPS module +- *Memory-hard KDFs*: Argon2 C library (via FFI in this library) -* Idris2 (for ABI/FFI correctness) -* Lean/Coq (for cryptographic properties) +==== ⚠️ Not FIPS-Certified + +Pure Julia implementations are NOT FIPS 140-2/3 certified. For +compliance-critical systems, use FIPS-certified libraries via FFI. + +==== ✅ What’s Safe + +* FFI wrappers to proven libraries (libsodium, BoringSSL) +* Post-quantum reference implementations (research, interoperability) +* Protocol verification and formal analysis +* Standards compliance testing + +=== Containerized Execution + +For maximum security isolation, run cryptographic operations in the +verified container: + +[source,bash] +---- +# Build container +cd verified-container-spec/examples/proven-crypto-runner +podman build -t proven-crypto-runner -f Containerfile + +# Run with svalinn/vordr security policy +svalinn run --policy svalinn-policy.json \ + -v ./ProvenCrypto.jl:/crypto/provencrypto:ro \ + proven-crypto-runner keygen + +# Interactive REPL +podman run -it -v ./ProvenCrypto.jl:/crypto/provencrypto:ro \ + proven-crypto-runner repl +---- + +Security features: - Process isolation (PID, network, mount, IPC, UTS, +user namespaces) - Seccomp filters (syscall allowlist) - Resource limits +(1 CPU, 2GB RAM, 512 processes) - No capabilities (runs with minimal +privileges) - Reproducible builds (Guix + Nix fallback) + +=== Formal Verification + +Export verification certificates to proof assistants: + +[source,julia] +---- +using ProvenCrypto + +# Create verification certificate +cert = ProofCertificate( + property="Kyber decapsulation correctness", + specification="∀pk,sk,c,ss. decapsulate(sk, fst(encapsulate(pk))) = snd(encapsulate(pk))", + verified=true, + verifier="SMT-Z3", + timestamp=now(), + 證明=nothing, + metadata=Dict() +) + +# Export to Idris 2 +export_idris(cert, "proofs/kyber_correctness.idr") + +# Export to Lean 4 +export_lean(cert, "proofs/kyber_correctness.lean") + +# Export to Coq +export_coq(cert, "proofs/kyber_correctness.v") + +# Display Idris Inside badge +println(idris_inside_badge()) +---- + +=== Architecture + +==== Layer 1: Verified Primitives (FFI) + +* libsodium: Authenticated encryption, hashing +* BoringSSL: Classical asymmetric crypto +* Argon2: Memory-hard KDF + +==== Layer 2: Protocols (Pure Julia) + +* Noise, Signal, TLS 1.3 implementations +* Uses Layer 1 primitives via FFI + +==== Layer 3: Post-Quantum (Pure Julia + Verification) + +* Kyber, Dilithium, SPHINCS+ +* Hardware-accelerated (NTT via GPU/TPU/NPU) +* Formal verification claims + +=== Development + +==== Running Tests + +[source,bash] +---- +julia --project -e 'using Pkg; Pkg.test("ProvenCrypto")' +---- + +==== Benchmarks + +[source,bash] +---- +julia --project benchmark/benchmarks.jl +---- + +==== Building Documentation + +[source,bash] +---- +julia --project docs/make.jl +---- -== Standards Compliance +=== License -* **ABI/FFI**: Follows the Hyperpolymath Universal Standard for cross-language compatibility. -* **AI CLI**: Includes crash capture and contractile support for automated verification. +MPL-2.0 (Polymathematical Meta-Public License) -== Contributing +=== Author -Contributions are welcome! Please ensure all new code includes: -1. Formal proofs of correctness and security. -2. Comprehensive tests. -3. Documentation updates. +Jonathan D.A. Jewell jonathan.jewell@open.ac.uk -== License +=== References -MIT +* https://csrc.nist.gov/projects/post-quantum-cryptography[NIST +Post-Quantum Cryptography] +* https://pq-crystals.org/kyber/[Kyber Specification] +* https://pq-crystals.org/dilithium/[Dilithium Specification] +* https://sphincs.org/[SPHINCS+ Specification] +* https://noiseprotocol.org/[Noise Protocol Framework] +* https://signal.org/docs/[Signal Protocol] +* https://libsodium.org/[libsodium] +* https://www.idris-lang.org/[Idris 2] diff --git a/packages/ProvenCrypto.jl/README.md b/packages/ProvenCrypto.jl/README.md deleted file mode 100644 index 0383b1db3..000000000 --- a/packages/ProvenCrypto.jl/README.md +++ /dev/null @@ -1,276 +0,0 @@ -# ProvenCrypto.jl - -[![Project Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![Completion Status](https://img.shields.io/badge/Completion-90%25-green)](TOPOLOGY.md) - -``` -╔═══════════════════════════╗ -║ IDRIS INSIDE 🟦 ║ -║ Formally Verified ║ -║ Dependent Type Checked ║ -╚═══════════════════════════╝ -``` - -Formally verified cryptographic protocols and post-quantum primitives for Julia. - -## Features - -### Post-Quantum Cryptography -- **Kyber**: KEM (Key Encapsulation Mechanism) - NIST PQC winner -- **Dilithium**: Digital signatures - NIST PQC winner -- **SPHINCS+**: Hash-based signatures (conservative security) - -### Protocol Implementations -- **Noise Protocol Framework**: Modern secure channel (WireGuard, Lightning) -- **Signal Protocol**: Double Ratchet for messaging -- **TLS 1.3**: Reference implementation (educational) - -### Zero-Knowledge Proofs -- **zk-SNARKs**: Groth16, PLONK, Halo2 -- **zk-STARKs**: Transparent, post-quantum secure - -### Threshold Cryptography -- **Shamir Secret Sharing**: M-of-N key recovery -- **Distributed Key Generation**: Multi-party computation - -### Hardware Acceleration -- **GPU**: CUDA (NVIDIA), ROCm (AMD), Metal (Apple) -- **NPU/TPU**: Intel oneAPI, Google TPU, Apple Neural Engine -- **Crypto Instructions**: AES-NI, SHA extensions, Intel QAT -- **Secure Enclaves**: Intel SGX, AMD SEV, ARM TrustZone -- **Multi-platform**: x86, ARM, RISC-V, Apple Silicon - -### Formal Verification -- **SMT Integration**: Z3, CVC5, Yices, MathSAT -- **Proof Assistants**: Idris 2, Lean 4, Coq, Isabelle/HOL -- **Property Verification**: Correctness, security properties -- **Proof Export**: Long-term formalization - -## Installation - -```julia -using Pkg -Pkg.add(url="https://github.com/hyperpolymath/ProvenCrypto.jl") -``` - -### System Dependencies - -#### libsodium (required for primitives) -```bash -# macOS -brew install libsodium - -# Ubuntu/Debian -sudo apt install libsodium-dev - -# Fedora -sudo dnf install libsodium-devel - -# Arch -sudo pacman -S libsodium -``` - -## Usage - -### Post-Quantum Key Exchange (Kyber) - -```julia -using ProvenCrypto - -# Generate keypair -(pk, sk) = kyber_keygen(768) # AES-192 equivalent security - -# Sender: Encapsulate shared secret -(ciphertext, shared_secret_sender) = kyber_encapsulate(pk) - -# Receiver: Decapsulate -shared_secret_receiver = kyber_decapsulate(sk, ciphertext) - -@assert shared_secret_sender == shared_secret_receiver -``` - -### Post-Quantum Signatures (Dilithium) - -```julia -using ProvenCrypto - -# Generate signing keypair -(pk, sk) = dilithium_keygen(3) # AES-192 equivalent security - -# Sign message -message = b"Hello, post-quantum world!" -signature = dilithium_sign(sk, message) - -# Verify -is_valid = dilithium_verify(pk, message, signature) -@assert is_valid -``` - -### Authenticated Encryption (libsodium FFI) - -```julia -using ProvenCrypto - -# Generate key and nonce -key = rand(UInt8, 32) -nonce = rand(UInt8, 12) # Must be unique per message! - -# Encrypt -plaintext = b"Secret message" -ciphertext = aead_encrypt(key, nonce, plaintext) - -# Decrypt -recovered = aead_decrypt(key, nonce, ciphertext) -@assert recovered == plaintext -``` - -### Hardware-Accelerated Operations - -```julia -using ProvenCrypto - -# Detect available hardware -backend = detect_hardware() -println(backend) -# Output: MetalBackend(M3 + Neural Engine) -# or: CUDABackend(device=0, CC=8.9) -# or: CPUBackend(avx512, 16 threads) - -# Operations automatically use best backend -features = detect_hardware_features() -print_hardware_report(features) -``` - -## Security Warnings - -### ⚠️ Production Use - -**This library is for research and educational purposes.** - -For production systems, use: -- **Symmetric crypto**: libsodium (via FFI wrappers in this library) -- **Classical asymmetric**: OpenSSL FIPS module -- **Memory-hard KDFs**: Argon2 C library (via FFI in this library) - -### ⚠️ Not FIPS-Certified - -Pure Julia implementations are NOT FIPS 140-2/3 certified. For compliance-critical systems, use FIPS-certified libraries via FFI. - -### ✅ What's Safe - -- FFI wrappers to proven libraries (libsodium, BoringSSL) -- Post-quantum reference implementations (research, interoperability) -- Protocol verification and formal analysis -- Standards compliance testing - -## Containerized Execution - -For maximum security isolation, run cryptographic operations in the verified container: - -```bash -# Build container -cd verified-container-spec/examples/proven-crypto-runner -podman build -t proven-crypto-runner -f Containerfile - -# Run with svalinn/vordr security policy -svalinn run --policy svalinn-policy.json \ - -v ./ProvenCrypto.jl:/crypto/provencrypto:ro \ - proven-crypto-runner keygen - -# Interactive REPL -podman run -it -v ./ProvenCrypto.jl:/crypto/provencrypto:ro \ - proven-crypto-runner repl -``` - -Security features: -- Process isolation (PID, network, mount, IPC, UTS, user namespaces) -- Seccomp filters (syscall allowlist) -- Resource limits (1 CPU, 2GB RAM, 512 processes) -- No capabilities (runs with minimal privileges) -- Reproducible builds (Guix + Nix fallback) - -## Formal Verification - -Export verification certificates to proof assistants: - -```julia -using ProvenCrypto - -# Create verification certificate -cert = ProofCertificate( - property="Kyber decapsulation correctness", - specification="∀pk,sk,c,ss. decapsulate(sk, fst(encapsulate(pk))) = snd(encapsulate(pk))", - verified=true, - verifier="SMT-Z3", - timestamp=now(), - 證明=nothing, - metadata=Dict() -) - -# Export to Idris 2 -export_idris(cert, "proofs/kyber_correctness.idr") - -# Export to Lean 4 -export_lean(cert, "proofs/kyber_correctness.lean") - -# Export to Coq -export_coq(cert, "proofs/kyber_correctness.v") - -# Display Idris Inside badge -println(idris_inside_badge()) -``` - -## Architecture - -### Layer 1: Verified Primitives (FFI) -- libsodium: Authenticated encryption, hashing -- BoringSSL: Classical asymmetric crypto -- Argon2: Memory-hard KDF - -### Layer 2: Protocols (Pure Julia) -- Noise, Signal, TLS 1.3 implementations -- Uses Layer 1 primitives via FFI - -### Layer 3: Post-Quantum (Pure Julia + Verification) -- Kyber, Dilithium, SPHINCS+ -- Hardware-accelerated (NTT via GPU/TPU/NPU) -- Formal verification claims - -## Development - -### Running Tests - -```bash -julia --project -e 'using Pkg; Pkg.test("ProvenCrypto")' -``` - -### Benchmarks - -```bash -julia --project benchmark/benchmarks.jl -``` - -### Building Documentation - -```bash -julia --project docs/make.jl -``` - -## License - -MPL-2.0 (Polymathematical Meta-Public License) - -## Author - -Jonathan D.A. Jewell - -## References - -- [NIST Post-Quantum Cryptography](https://csrc.nist.gov/projects/post-quantum-cryptography) -- [Kyber Specification](https://pq-crystals.org/kyber/) -- [Dilithium Specification](https://pq-crystals.org/dilithium/) -- [SPHINCS+ Specification](https://sphincs.org/) -- [Noise Protocol Framework](https://noiseprotocol.org/) -- [Signal Protocol](https://signal.org/docs/) -- [libsodium](https://libsodium.org/) -- [Idris 2](https://www.idris-lang.org/) diff --git a/packages/ProvenCrypto.jl/SECURITY.adoc b/packages/ProvenCrypto.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/ProvenCrypto.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/ProvenCrypto.jl/SECURITY.md b/packages/ProvenCrypto.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/ProvenCrypto.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/ProvenCrypto.jl/SONNET-TASKS.adoc b/packages/ProvenCrypto.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..aa2259ff4 --- /dev/null +++ b/packages/ProvenCrypto.jl/SONNET-TASKS.adoc @@ -0,0 +1,1029 @@ +== SONNET-TASKS: ProvenCrypto.jl + +*Date:* 2026-02-12 *Auditor:* Claude Opus 4.6 *Honest Completion:* ~15% + +The README and CHANGELOG claim a functioning post-quantum cryptography +library with hardware acceleration, protocol implementations, +zero-knowledge proofs, threshold cryptography, and formal verification +export. In reality, every single cryptographic algorithm is a stub +returning placeholder data. The only code that actually works is: (1) +hardware backend detection (CPU SIMD level), (2) libsodium FFI wrappers +for AEAD/hashing/KDF (if libsodium is installed), and (3) proof export +to files (but the spec-to-prover translation functions are hardcoded +examples, not real translators). Everything else – Kyber, Dilithium, +SPHINCS+, Noise, Signal, TLS 1.3, zk-SNARKs, zk-STARKs, Shamir, GPU +backends – is empty structs and functions returning empty arrays or +identity values. + +There is also a module load crash: two `+__init__()+` functions compete, +three declared extensions have no source files, the advanced hardware +module is never included but tests reference it, and template +placeholders `+{{PROJECT}}+` are never replaced in 13 files. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Do NOT just add more stubs. Every function body you write must do real +computation. +. Do NOT skip verification blocks. Every task must be testable with the +commands given. +. Do NOT claim completion without running the tests. Julia must load the +module and pass all tests without errors. +. If a task says "`implement X per the NIST spec,`" you must follow the +actual spec, not invent a simplified version. +. Constant-time operations are required where noted. Using `+rand()+` as +a placeholder for cryptographic sampling is a security vulnerability. +. The ABI/FFI files (Idris, Zig) are RSR template boilerplate – they +still have `+ProvenCrypto+` placeholders. Either customize them for +ProvenCrypto or remove them. + +''''' + +=== TASK 1: Fix Module Load Crash – Dual `+__init__()+` and Missing Include + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/ProvenCrypto.jl+` (lines +118-121) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/primitives/ffi_wrappers.jl+` (lines +237-239) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/backends/advanced_hardware.jl+` +(entire file – never included) + +*Problem:* Two `+function __init__()+` definitions exist. The one in +`+ffi_wrappers.jl+` (line 237) calls `+__init_libsodium__()+`, and the +one in `+ProvenCrypto.jl+` (line 118) calls `+detect_hardware()+`. Julia +modules can only have one `+__init__()+`. The second definition silently +overwrites the first. Whichever file is `+include()+`d last wins, +meaning either libsodium never loads or hardware detection never runs. + +Additionally, `+src/backends/advanced_hardware.jl+` defines +`+HardwareFeatures+`, `+detect_hardware_features()+`, and +`+print_hardware_report()+` but is never `+include()+`d in the main +module. The test file (`+test/runtests.jl+` lines 17-18) calls these +functions, so the test suite will crash with `+UndefVarError+`. + +*What to do:* 1. Remove the `+__init__()+` from `+ffi_wrappers.jl+`. +Rename it to `+init_libsodium()+` or similar. 2. In the main +`+ProvenCrypto.jl+` `+__init__()+`, call both `+init_libsodium()+` and +`+detect_hardware()+`. 3. Add +`+include("backends/advanced_hardware.jl")+` to `+ProvenCrypto.jl+` +after line 102 (after `+include("backends/hardware.jl")+`). 4. Export +`+HardwareFeatures+`, `+detect_hardware_features+`, and +`+print_hardware_report+` from the module. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto +# Module loaded without crash +println("Module loaded OK") +# Hardware detection ran +println("Backend: ", ProvenCrypto.HARDWARE_BACKEND[]) +# Advanced hardware features available +features = detect_hardware_features() +println("Features type: ", typeof(features)) +@assert features isa HardwareFeatures +println("TASK 1 PASS") +' +---- + +''''' + +=== TASK 2: Fix Missing Extensions (3 Declared but No Source Files) + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/Project.toml+` (lines 24, +27, 28) - Missing: `+ext/ProvenCryptoAMDGPUExt.jl+` - Missing: +`+ext/ProvenCryptoOneAPIExt.jl+` - Missing: +`+ext/ProvenCryptoSMTExt.jl+` + +*Problem:* `+Project.toml+` declares five extensions: + +[source,toml] +---- +ProvenCryptoAMDGPUExt = ["AMDGPU"] +ProvenCryptoCUDAExt = ["CUDA"] +ProvenCryptoMetalExt = ["Metal"] +ProvenCryptoOneAPIExt = ["oneAPI"] +ProvenCryptoSMTExt = ["SMTLib"] +---- + +Only three files exist (`+ext/ProvenCryptoCUDAExt.jl+`, +`+ext/ProvenCryptoMetalExt.jl+`, `+ext/ProvenCryptoROCmExt.jl+`). Note +that the ROCm extension file exists but is named +`+ProvenCryptoROCmExt.jl+` while the Project.toml declares +`+ProvenCryptoAMDGPUExt+`. This is a mismatch – Julia looks for a module +named `+ProvenCryptoAMDGPUExt+` but the file defines +`+module ProvenCryptoROCmExt+`. + +The `+ProvenCryptoOneAPIExt.jl+` and `+ProvenCryptoSMTExt.jl+` files do +not exist at all. + +*What to do:* 1. Rename `+ext/ProvenCryptoROCmExt.jl+` to +`+ext/ProvenCryptoAMDGPUExt.jl+` and change the internal +`+module ProvenCryptoROCmExt+` to `+module ProvenCryptoAMDGPUExt+`. 2. +Create `+ext/ProvenCryptoOneAPIExt.jl+` with at minimum the +`+oneapi_available()+` override and stub backend methods (matching the +pattern in MetalExt). 3. Create `+ext/ProvenCryptoSMTExt.jl+` with +`+@prove+` macro integration for SMT-LIB solvers. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +# Check all declared extensions have matching files +for ext in ProvenCryptoAMDGPUExt ProvenCryptoCUDAExt ProvenCryptoMetalExt ProvenCryptoOneAPIExt ProvenCryptoSMTExt; do + if [ -f "ext/${ext}.jl" ]; then + echo "OK: ext/${ext}.jl exists" + grep -q "module ${ext}" "ext/${ext}.jl" && echo " module name matches" || echo " ERROR: module name mismatch" + else + echo "MISSING: ext/${ext}.jl" + fi +done +---- + +''''' + +=== TASK 3: Implement CPU NTT Backend (Blocks All Post-Quantum Algorithms) + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/backends/hardware.jl+` +(lines 247-257) + +*Problem:* Four critical CPU backend functions are placeholders that +return identity or garbage: + +* `+backend_ntt_transform(::CPUBackend, poly, modulus)+` at line 248: +returns `+poly+` unchanged. NTT (Number Theoretic Transform) is the core +operation for all lattice-based crypto. Without it, Kyber and Dilithium +produce mathematically wrong results. +* `+backend_polynomial_multiply(::CPUBackend, a, b, modulus)+` at line +252: returns `+a+` unchanged, ignoring `+b+` entirely. +* `+backend_sampling(::CPUBackend, distribution, params...)+` at line +256: calls `+randn()+` which returns a Float64 instead of a properly +sampled integer from the specified distribution. +* `+backend_ntt_inverse_transform+` at kyber.jl line 213: global stub +returns `+poly+` unchanged. + +*What to do:* 1. Implement Cooley-Tukey NTT for +`+backend_ntt_transform+` over `+Z_q+` where `+q=3329+` (Kyber) or +`+q=8380417+` (Dilithium). Use primitive roots of unity for each +modulus. 2. Implement inverse NTT for `+backend_ntt_inverse_transform+`. +Move it from the kyber.jl stub to `+hardware.jl+` as a proper +`+CPUBackend+` method. 3. Implement polynomial multiplication via NTT: +`+a*b = INTT(NTT(a) .* NTT(b))+` mod q. 4. Implement constant-time +centered binomial distribution sampling for `+:cbd+` and uniform +sampling for `+:uniform+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto +backend = CPUBackend(:avx2, 1) + +# NTT round-trip test: INTT(NTT(x)) == x +q = 3329 +x = rand(0:q-1, 256) +x_ntt = ProvenCrypto.backend_ntt_transform(backend, x, q) +x_recovered = ProvenCrypto.backend_ntt_inverse_transform(backend, x_ntt, q) +@assert x_recovered == x "NTT round-trip failed" + +# Polynomial multiplication test: (1+x) * (1+x) mod q +a = zeros(Int, 256); a[1] = 1; a[2] = 1 +b = zeros(Int, 256); b[1] = 1; b[2] = 1 +c = ProvenCrypto.backend_polynomial_multiply(backend, a, b, q) +@assert c[1] == 1 # constant term +@assert c[2] == 2 # x coefficient +@assert c[3] == 1 # x^2 coefficient + +println("TASK 3 PASS") +' +---- + +''''' + +=== TASK 4: Implement Kyber KEM Helper Functions + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/postquantum/kyber.jl+` +(lines 169-213) + +*Problem:* Seven helper functions are stubs returning garbage: + +[arabic] +. `+kyber_gen_matrix+` (line 170): Returns `+rand(Int, k, n) .% q+` +instead of deterministically generating matrix A from seed via SHAKE-128 +(XOF). +. `+kyber_sample_cbd+` (line 176): Returns +`+rand(Int, k, n) .- (eta / 2)+` instead of constant-time centered +binomial distribution sampling. +. `+kyber_encode+` (line 182): Returns `+zeros(Int, length(msg)*8)+` – +wrong dimensions, wrong values. +. `+kyber_decode+` (line 188): Returns `+UInt8[]+` – empty array, loses +all data. +. `+kyber_compress+` (line 194): Returns `+UInt8[]+` – empty, makes +ciphertext vanish. +. `+kyber_decompress+` (line 200): Returns zeros – makes decapsulation +impossible. +. `+encode_pk+` (line 206): Returns `+UInt8[]+` – empty serialization +breaks hashing. + +The top-level functions (`+kyber_keygen+`, `+kyber_encapsulate+`, +`+kyber_decapsulate+`) have correct structure but produce wrong results +because every helper returns garbage. + +*What to do:* Implement each function per FIPS 203 (ML-KEM) / the Kyber +specification: 1. `+kyber_gen_matrix+`: Use SHAKE-128 (or SHA3) to +expand seed into matrix A. Julia’s SHA package has SHA3 support. 2. +`+kyber_sample_cbd+`: Implement CBD_eta sampling per Algorithm 2 of the +Kyber spec. 3. `+kyber_encode+`/`+kyber_decode+`: Implement Compress_d +and Decompress_d per Kyber spec Section 4.2.1. 4. +`+kyber_compress+`/`+kyber_decompress+`: Implement byte-level +compression per spec. 5. `+encode_pk+`: Serialize `+(t, rho)+` as per +spec byte encoding. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# Full Kyber round-trip +(pk, sk) = kyber_keygen(512) +(ciphertext, ss_sender) = kyber_encapsulate(pk) +ss_receiver = kyber_decapsulate(sk, ciphertext) + +@assert length(ss_sender) == 32 "Shared secret must be 32 bytes" +@assert length(ss_receiver) == 32 "Recovered secret must be 32 bytes" +@assert length(ciphertext) > 0 "Ciphertext must not be empty" + +# Key sizes per spec +@assert pk.level == 512 + +println("Kyber round-trip: shared secrets match = ", ss_sender == ss_receiver) +println("TASK 4 PASS") +' +---- + +''''' + +=== TASK 5: Implement Dilithium Signature Helper Functions + +*Files:* - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/postquantum/dilithium.jl+` (lines +211-254) + +*Problem:* Nine helper functions are stubs: + +[arabic] +. `+dilithium_expand_matrix+` (line 212): `+rand(Int, k*n, l*n) .% q+` – +non-deterministic, wrong dimensions (should be k-by-l of n-polynomials, +not a single flat matrix). +. `+dilithium_sample_eta+` (line 216): `+rand(Int, rows, n) .- eta+` – +not CBD, not constant-time, wrong distribution. +. `+dilithium_sample_y+` (line 220): `+rand(Int, l, n) .% gamma1+` – +should use rejection sampling from `+[-gamma1+1, gamma1]+`. +. `+dilithium_sample_in_ball+` (line 224): Returns `+zeros(Int, n)+` – +must sample a polynomial with exactly `+tau+` nonzero coefficients in +\{-1, +1}. +. `+dilithium_high_bits+` (line 235): Returns `+w+` unchanged – must +extract HighBits per spec. +. `+dilithium_low_bits+` (line 239): Returns `+w+` unchanged – must +extract LowBits per spec. +. `+dilithium_make_hint+` (line 243): Returns `+Bool[]+` – must compute +MakeHint per spec. +. `+dilithium_use_hint+` (line 248): Returns `+w+` unchanged – must +apply UseHint per spec. +. `+encode_vector+` (line 252): Returns `+UInt8[]+` – must serialize +polynomial vector. + +Additionally, `+encode_pk+` is called for `+DilithiumPublicKey+` (lines +108, 180) but only has a method for `+KyberPublicKey+` (kyber.jl line +206). This is a `+MethodError+` crash. + +*What to do:* 1. Add an `+encode_pk(pk::DilithiumPublicKey)+` method in +dilithium.jl. 2. Implement all nine helpers per FIPS 204 (ML-DSA) / +Dilithium specification. 3. The HighBits/LowBits/MakeHint/UseHint +functions are defined in Dilithium spec Section 3.1 – follow those +definitions exactly. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# Full Dilithium sign/verify round-trip +(pk, sk) = dilithium_keygen(2) +message = Vector{UInt8}("Test message for Dilithium") +signature = dilithium_sign(sk, message) + +@assert signature isa DilithiumSignature +@assert length(signature.c_tilde) == 32 +@assert length(signature.z) > 0 + +is_valid = dilithium_verify(pk, message, signature) +@assert is_valid "Valid signature must verify" + +# Tampered message must fail +tampered = Vector{UInt8}("Tampered message") +@assert !dilithium_verify(pk, tampered, signature) "Tampered message must not verify" + +println("TASK 5 PASS") +' +---- + +''''' + +=== TASK 6: Implement SPHINCS+ Helper Functions + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/postquantum/sphincs.jl+` +(lines 150-185) + +*Problem:* Six helper functions are stubs returning empty arrays or +zeros: + +[arabic] +. `+sphincs_compute_root+` (line 151): Returns `+rand(UInt8, params.n)+` +– must compute Merkle hypertree root using WOTS+ and tree hashing. +. `+sphincs_parse_digest+` (line 156): Returns `+(0, 0)+` – must split +digest into tree index and leaf index per spec. +. `+sphincs_fors_sign+` (line 161): Returns `+UInt8[]+` – must implement +FORS (Forest of Random Subsets) signing. +. `+sphincs_fors_verify+` (line 167): Returns `+UInt8[]+` – must verify +FORS and return the FORS public key. +. `+sphincs_ht_sign+` (line 173): Returns `+UInt8[]+` – must implement +HyperTree signing with WOTS+ chains. +. `+sphincs_ht_verify+` (line 180): Returns `+UInt8[]+` – must verify +HyperTree path and return reconstructed root. + +*What to do:* Implement each function per the SPHINCS+ specification +(NIST SP 800-208): 1. Implement WOTS+ one-time signature scheme as the +base. 2. Implement Merkle tree construction and authentication path +generation. 3. Implement FORS few-time signature scheme. 4. Implement +the full HyperTree structure. 5. Use hash_blake3 or SHA-256 as the +tweakable hash function. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# Full SPHINCS+ sign/verify round-trip +(pk, sk) = sphincs_keygen(128, :f) # Fast variant for testing +message = Vector{UInt8}("Test message for SPHINCS+") + +signature = sphincs_sign(sk, message) +@assert length(signature.sig_bytes) > 0 "Signature must not be empty" + +is_valid = sphincs_verify(pk, message, signature) +@assert is_valid "Valid signature must verify" + +# Tampered message must fail +tampered = Vector{UInt8}("Tampered") +@assert !sphincs_verify(pk, tampered, signature) "Tampered must not verify" + +println("TASK 6 PASS") +' +---- + +''''' + +=== TASK 7: Implement Protocol Stubs (Noise, Signal, TLS 1.3) + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/protocols/noise.jl+` +(entire file – 15 lines, empty struct) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/protocols/signal.jl+` (entire file +– 14 lines, empty struct) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/protocols/tls13.jl+` (entire file – +16 lines, empty struct) + +*Problem:* All three protocol implementations are empty structs with no +fields and no methods: + +[source,julia] +---- +struct NoiseHandshake end # noise.jl line 11 +struct SignalRatchet end # signal.jl line 10 +struct TLS13Session end # tls13.jl line 12 +---- + +These types are exported from the main module but have zero +functionality. The README and module docstring list them as features. + +*What to do:* For each protocol, implement at minimum: + +*Noise Protocol (noise.jl):* - `+NoiseHandshake+` struct with: pattern +(XX, IK, NK), static keypair, ephemeral keypair, handshake state, cipher +state. - `+noise_initiator()+` / `+noise_responder()+` constructors. - +`+noise_write_message()+` / `+noise_read_message()+` for handshake +messages. - `+noise_split()+` to derive transport keys after handshake. +- Use `+aead_encrypt+`/`+aead_decrypt+` from ffi_wrappers for the +symmetric crypto. + +*Signal Protocol (signal.jl):* - `+SignalRatchet+` struct with: root +key, chain key, message keys, DH ratchet state. - +`+signal_init_sender()+` / `+signal_init_receiver()+`. - +`+signal_ratchet_encrypt()+` / `+signal_ratchet_decrypt()+`. - Implement +the Double Ratchet algorithm per the Signal spec. + +*TLS 1.3 (tls13.jl):* - `+TLS13Session+` struct with: handshake state, +cipher suite, keys. - `+tls13_client_hello()+` / +`+tls13_server_hello()+`. - Key schedule derivation using HKDF. - This +is educational/reference only (per the file’s own docstring). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# Noise: basic handshake +hs_init = NoiseHandshake # Should have constructor with pattern +@assert fieldcount(NoiseHandshake) > 0 "NoiseHandshake must have fields" + +# Signal: basic ratchet +@assert fieldcount(SignalRatchet) > 0 "SignalRatchet must have fields" + +# TLS 1.3: basic session +@assert fieldcount(TLS13Session) > 0 "TLS13Session must have fields" + +println("TASK 7 PASS") +' +---- + +''''' + +=== TASK 8: Implement Zero-Knowledge Proof Systems + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/zkproofs/zksnark.jl+` +(entire file – 28 lines) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/zkproofs/zkstark.jl+` (entire file +– 14 lines) + +*Problem:* `+zk_prove+` (line 18) returns `+ZKProof(UInt8[], UInt8[])+` +– empty proof data. `+zk_verify+` (line 23) always returns `+false+`. +`+zkstark.jl+` has no code at all beyond a docstring comment. + +*What to do:* 1. In `+zksnark.jl+`: - Define a `+Circuit+` type (R1CS +constraint system: matrices A, B, C). - Define a `+Witness+` type +(assignment of values satisfying constraints). - Implement a simplified +Groth16 prover: generate proof elements (A, B, C points). - Implement +verifier: pairing check e(A,B) = e(alpha,beta) * e(C,delta). - At +minimum, support boolean circuit verification. + +[arabic, start=2] +. In `+zkstark.jl+`: +* Define `+STARKProof+` struct. +* Implement polynomial commitment via Merkle tree (FRI protocol). +* Implement `+stark_prove()+` and `+stark_verify()+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# zk-SNARK: prove knowledge of x such that x^2 = 9 +# (simplified circuit) +proof = zk_prove(nothing, nothing) # Replace with real circuit/witness +@assert length(proof.proof_data) > 0 "Proof must contain data" + +valid = zk_verify(proof, nothing) +@assert typeof(valid) == Bool + +println("TASK 8 PASS") +' +---- + +''''' + +=== TASK 9: Implement Shamir Secret Sharing + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/src/threshold/shamir.jl+` +(lines 14-23) + +*Problem:* `+shamir_split+` (line 14) returns +`+[UInt8[] for _ in 1:num_shares]+` – a list of empty byte arrays. No +polynomial evaluation, no GF(2^8) arithmetic, no secret encoding. + +`+shamir_reconstruct+` (line 19) returns `+UInt8[]+` – empty, ignoring +all shares. + +*What to do:* 1. Implement Shamir’s Secret Sharing over GF(256) (or a +large prime field): - `+shamir_split+`: Generate random polynomial of +degree `+threshold-1+` with constant term = secret byte. Evaluate at +`+num_shares+` distinct points. - `+shamir_reconstruct+`: Use Lagrange +interpolation to recover the constant term. 2. Handle multi-byte secrets +by splitting each byte independently. 3. Validate: +`+threshold <= num_shares+`, `+threshold >= 2+`, `+num_shares <= 255+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +secret = Vector{UInt8}("SuperSecretKey!!") +shares = shamir_split(secret, 3, 5) + +# Must produce 5 non-empty shares +@assert length(shares) == 5 +for s in shares + @assert length(s) > 0 "Share must not be empty" +end + +# Reconstruct from any 3 shares +recovered = shamir_reconstruct(shares[1:3]) +@assert recovered == secret "3-of-5 reconstruction must recover secret" + +# Reconstruct from different 3 shares +recovered2 = shamir_reconstruct(shares[3:5]) +@assert recovered2 == secret "Different 3-of-5 must also work" + +# 2 shares must NOT be enough (if implemented with threshold check) +# This depends on implementation -- at minimum verify 3-of-5 works + +println("TASK 9 PASS") +' +---- + +''''' + +=== TASK 10: Implement Real Proof-Export Spec Translators + +*Files:* - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/verification/proof_export.jl+` +(lines 228-251) + +*Problem:* All four translation functions return hardcoded example +strings regardless of input: + +[source,julia] +---- +translate_spec_to_idris_type(spec) = "(a : Nat) -> (b : Nat) -> a + b = b + a" # line 230 +translate_spec_to_lean(spec) = "forall (a b : N), a + b = b + a" # line 234 +translate_spec_to_coq(spec) = "forall (a b : nat), a + b = b + a" # line 238 +translate_spec_to_isabelle(spec) = "\\a b::nat. a + b = b + a" # line 242 +---- + +The `+spec+` argument is completely ignored. Any specification string +produces the same commutativity theorem in the output file. + +*What to do:* 1. Define a small specification language or parse a subset +of SMT-LIB2 syntax. 2. Translate quantifiers (`+forall+`, `+exists+`), +arithmetic, equality, and basic types. 3. At minimum, handle: - +Universal quantification: `+forall x : T. P(x)+` - Equality: `+a = b+` - +Implication: `+P => Q+` - Basic types: `+Nat+`, `+Int+`, `+Bool+`, +`+ByteVector+` 4. If full SMT-LIB parsing is too complex, at minimum +pass through the spec string with appropriate syntax adjustments for +each target language instead of ignoring it. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# Two different specs must produce different output +spec1 = "forall x : Nat. x + 0 = x" +spec2 = "forall a b : Nat. a * b = b * a" + +idris1 = ProvenCrypto.translate_spec_to_idris_type(spec1) +idris2 = ProvenCrypto.translate_spec_to_idris_type(spec2) +@assert idris1 != idris2 "Different specs must produce different translations" + +lean1 = ProvenCrypto.translate_spec_to_lean(spec1) +lean2 = ProvenCrypto.translate_spec_to_lean(spec2) +@assert lean1 != lean2 "Different specs must produce different Lean translations" + +println("TASK 10 PASS") +' +---- + +''''' + +=== TASK 11: Replace Template Placeholders in ABI/FFI Files + +*Files (13 files with `+{{PROJECT}}+` or `+{{project}}+` placeholders):* +- `+/var$REPOS_DIR/ProvenCrypto.jl/src/abi/Types.idr+` (3 occurrences: +`+{{PROJECT}}.ABI.Types+`, etc.) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/abi/Layout.idr+` (2 occurrences: +`+{{PROJECT}}.ABI.Layout+`, imports) - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/abi/Foreign.idr+` (14 occurrences: +module name, all `+%foreign+` declarations) - +`+/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/build.zig+` (6 occurrences: +library name, header, benchmark) - +`+/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/src/main.zig+` (19 occurrences: +all export functions) - +`+/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/test/integration_test.zig+` (44 +occurrences: all extern declarations and test calls) - Plus occurrences +in: `+SECURITY.md+`, `+CONTRIBUTING.md+`, `+CODE_OF_CONDUCT.md+`, +`+ABI-FFI-README.md+`, `+.github/workflows/quality.yml+`, `+ci.yml+`, +`+release.yml+` + +*Problem:* 184 total `+{{...}}+` placeholder occurrences across 13 +files. These are RSR template markers that should have been replaced +when the repo was created from the template. The Idris modules will not +compile, the Zig code will not build, and the workflows reference a +nonexistent project name. + +*What to do:* 1. Replace `+{{PROJECT}}+` with `+ProvenCrypto+` +(capitalized, for module names and titles). 2. Replace `+{{project}}+` +with `+provencrypto+` (lowercase, for library names and C symbols). 3. +Replace `+{{OWNER}}+` with `+hyperpolymath+`. 4. Replace `+{{FORGE}}+` +with `+github.com+`. 5. Replace `+{{REPO}}+` with `+ProvenCrypto.jl+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +count=$(grep -r '{{' --include='*.idr' --include='*.zig' --include='*.yml' --include='*.md' --include='*.adoc' --include='*.res' -l . 2>/dev/null | wc -l) +if [ "$count" -eq 0 ]; then + echo "TASK 11 PASS: No template placeholders remain" +else + echo "TASK 11 FAIL: $count files still contain {{ placeholders" + grep -r '{{' --include='*.idr' --include='*.zig' --include='*.yml' --include='*.md' --include='*.adoc' --include='*.res' -l . +fi +---- + +''''' + +=== TASK 12: Fix SPDX License Headers (AGPL-3.0 Must Be MPL-2.0) + +*Files with wrong license:* - +`+/var$REPOS_DIR/ProvenCrypto.jl/examples/SafeDOMExample.res+` line 1: +`+AGPL-3.0-or-later+` - +`+/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/build.zig+` line 2: +`+AGPL-3.0-or-later+` - +`+/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/src/main.zig+` line 6: +`+AGPL-3.0-or-later+` - +`+/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/test/integration_test.zig+` +line 2: `+AGPL-3.0-or-later+` - +`+/var$REPOS_DIR/ProvenCrypto.jl/docs/CITATIONS.adoc+` line 13: +`+license = {AGPL-3.0-or-later}+` + +*Problem:* Per the CLAUDE.md license policy, hyperpolymath original code +must use `+MPL-2.0+`. AGPL-3.0 is the old license and must never be +used. + +*What to do:* 1. Replace all `+AGPL-3.0-or-later+` SPDX identifiers with +`+MPL-2.0+`. 2. Update `+docs/CITATIONS.adoc+` BibTeX entry from +`+AGPL-3.0-or-later+` to `+MPL-2.0+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +agpl_count=$(grep -r 'AGPL' --include='*.jl' --include='*.zig' --include='*.idr' --include='*.res' --include='*.adoc' . 2>/dev/null | wc -l) +if [ "$agpl_count" -eq 0 ]; then + echo "TASK 12 PASS: No AGPL references remain" +else + echo "TASK 12 FAIL: $agpl_count lines still reference AGPL" + grep -rn 'AGPL' --include='*.jl' --include='*.zig' --include='*.idr' --include='*.res' --include='*.adoc' . +fi +---- + +''''' + +=== TASK 13: Fix GPU Extension Backends (All Are Fallback-Only Placeholders) + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/ext/ProvenCryptoCUDAExt.jl+` +(lines 12-14) - +`+/var$REPOS_DIR/ProvenCrypto.jl/ext/ProvenCryptoMetalExt.jl+` (lines +25-62) - `+/var$REPOS_DIR/ProvenCrypto.jl/ext/ProvenCryptoROCmExt.jl+` +(lines 25-62) + +*Problem:* All GPU backend methods are placeholders that immediately +fall back to CPU: + +[source,julia] +---- +# MetalExt.jl line 27 +@warn "Metal lattice multiplication not yet implemented; falling back to CPU" +return ProvenCrypto.backend_lattice_multiply(ProvenCrypto.CPUBackend(:neon, ...), A, x) +---- + +Same pattern for `+backend_ntt_transform+`, +`+backend_polynomial_multiply+`, and `+backend_sampling+` in both Metal +and ROCm extensions. The CUDA extension (line 13) has an empty function +body: + +[source,julia] +---- +function ProvenCrypto.backend_lattice_multiply(backend::ProvenCrypto.CUDABackend, args...) + # CUDA-specific implementation +end +---- + +This silently returns `+nothing+` instead of a matrix, which will crash +any caller. + +*What to do:* 1. For CUDA: Implement lattice multiplication using +`+CUDA.jl+` `+CuArray+` operations. Use `+CUDA.@cuda+` kernel for NTT if +performance matters, or use cuBLAS for matrix ops. 2. For Metal: +Implement using `+Metal.jl+` MtlArray operations. 3. For ROCm: Implement +using `+AMDGPU.jl+` ROCArray operations. 4. At minimum, each +backend_lattice_multiply must return a valid matrix/vector result, not +`+nothing+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +# Verify no empty function bodies in extensions +for ext in ext/ProvenCrypto*.jl; do + empty=$(grep -c '^\s*end\s*$' "$ext") + funcs=$(grep -c 'function ProvenCrypto\.' "$ext") + echo "$ext: $funcs functions, checking for empty bodies..." + # Check that no function has an immediately-following end with only a comment between + grep -Pzo 'function[^)]+\)\n\s*#[^\n]*\n\s*end' "$ext" && echo " WARNING: empty function body found" || echo " OK" +done +---- + +''''' + +=== TASK 14: Add Missing .machine_readable/ Directory and SCM Files + +*Files (all missing):* - +`+/var$REPOS_DIR/ProvenCrypto.jl/.machine_readable/STATE.scm+` - +`+/var$REPOS_DIR/ProvenCrypto.jl/.machine_readable/ECOSYSTEM.scm+` - +`+/var$REPOS_DIR/ProvenCrypto.jl/.machine_readable/META.scm+` + +*Problem:* Per CLAUDE.md checkpoint file protocol, every hyperpolymath +repo MUST have SCM files in `+.machine_readable/+`. This directory does +not exist at all. The ROADMAP.adoc is still the RSR template text +("`YOUR Template Repo Roadmap`") and the CITATIONS.adoc references +"`RSR-template-repo`" instead of "`ProvenCrypto.jl`". + +*What to do:* 1. Create `+.machine_readable/+` directory. 2. Create +`+STATE.scm+` with: metadata, project-context (ProvenCrypto.jl – +post-quantum crypto library for Julia), current-position (v0.1.1, mostly +stubs), route-to-mvp, blockers (all algorithms are placeholders), +critical-next-actions. 3. Create `+ECOSYSTEM.scm+` with: relationship to +`+proven+` (Idris library), `+hypatia+` (CI/CD), `+verisimdb+` +(vulnerability DB). 4. Create `+META.scm+` with: architecture decisions +(pure Julia + FFI), license (PMPL), design rationale. 5. Update +`+ROADMAP.adoc+` from template text to actual ProvenCrypto milestones. +6. Update `+docs/CITATIONS.adoc+` from "`RSR-template-repo`" to +"`ProvenCrypto.jl`". + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +for f in .machine_readable/STATE.scm .machine_readable/ECOSYSTEM.scm .machine_readable/META.scm; do + if [ -f "$f" ]; then + echo "OK: $f exists ($(wc -l < "$f") lines)" + else + echo "MISSING: $f" + fi +done +# Verify ROADMAP is customized +grep -q "ProvenCrypto" ROADMAP.adoc && echo "ROADMAP customized" || echo "ROADMAP still template" +# Verify CITATIONS is customized +grep -q "ProvenCrypto" docs/CITATIONS.adoc && echo "CITATIONS customized" || echo "CITATIONS still template" +---- + +''''' + +=== TASK 15: Fix Changelog Lies and Add Missing Preferences.jl Dependency + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/CHANGELOG.md+` (line 22) - +`+/var$REPOS_DIR/ProvenCrypto.jl/Project.toml+` + +*Problem:* The CHANGELOG v0.1.1 entry (line 22) states: > +"`Dependencies: Added Preferences.jl for user-configurable fallback +behavior`" + +But `+Preferences+` is not listed in `+Project.toml+` `+[deps]+` or +`+[weakdeps]+`. It is not used anywhere in the codebase. This is a false +claim. + +The README also references a `+benchmark/benchmarks.jl+` file and +`+docs/make.jl+` file that do not exist. + +*What to do:* Either: - (A) Add `+Preferences+` to `+[deps]+` in +Project.toml and implement the configurable fallback behavior the +changelog claims exists, OR - (B) Remove the false claim from the +changelog. + +Also: - Create `+benchmark/benchmarks.jl+` (at least a stub using +BenchmarkTools.jl) or remove the README reference. - Create +`+docs/make.jl+` (using Documenter.jl) or remove the README reference. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +# Check Preferences is either used or the claim is removed +if grep -q 'Preferences' CHANGELOG.md; then + grep -q 'Preferences' Project.toml && echo "OK: Preferences in Project.toml" || echo "FAIL: Changelog claims Preferences but not in Project.toml" +else + echo "OK: False Preferences claim removed from changelog" +fi +# Check referenced files exist +[ -f benchmark/benchmarks.jl ] && echo "OK: benchmark exists" || echo "MISSING: benchmark/benchmarks.jl (referenced in README)" +[ -f docs/make.jl ] && echo "OK: docs/make.jl exists" || echo "MISSING: docs/make.jl (referenced in README)" +---- + +''''' + +=== TASK 16: Fix Test Suite to Actually Test Crypto Operations + +*Files:* - `+/var$REPOS_DIR/ProvenCrypto.jl/test/runtests.jl+` (lines +74-111) + +*Problem:* The post-quantum test sections only test struct construction, +not actual crypto operations: + +[source,julia] +---- +# test/runtests.jl lines 76-85 +(pk, sk) = kyber_keygen(512) +@test pk isa KyberPublicKey # Only tests type, not correctness +@test sk isa KyberSecretKey +@test pk.level == 512 +# TODO: Test encapsulation/decapsulation when NTT is implemented +# (ciphertext, ss_sender) = kyber_encapsulate(pk) <-- COMMENTED OUT +---- + +The `+TODO+` comments at lines 82, 95, and 109 indicate the developers +knew these tests were incomplete. Once Tasks 3-6 are complete, the +commented-out tests must be enabled and expanded. + +*What to do:* 1. Uncomment all `+# TODO+` test blocks (lines 82-85, +95-98, 109). 2. Add edge case tests: wrong key sizes, empty messages, +corrupted ciphertexts. 3. Add round-trip tests for each algorithm at all +security levels. 4. Add test for `+shamir_split+`/`+shamir_reconstruct+` +(currently no test exists at all). 5. Add tests for +`+zk_prove+`/`+zk_verify+` (currently no test exists). 6. Add tests for +protocol structs once they have real fields (Task 7). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e 'using Pkg; Pkg.test("ProvenCrypto")' +# All tests must pass with zero TODO comments in test output +grep -c 'TODO' test/runtests.jl +# Should be 0 +---- + +''''' + +=== TASK 17: Fix `+kdf_argon2+` Fallback (SHA-256 Is Not PBKDF2) + +*Files:* - +`+/var$REPOS_DIR/ProvenCrypto.jl/src/primitives/ffi_wrappers.jl+` (line +218) + +*Problem:* When libsodium is unavailable, the fallback is: + +[source,julia] +---- +return SHA.sha256(vcat(password, salt)) # Placeholder; replace with PBKDF2 +---- + +This is not a KDF. It ignores the `+memory_kb+`, `+iterations+`, +`+parallelism+`, and `+key_length+` parameters entirely. +SHA-256(password || salt) is trivially brute-forceable and the comment +admits it is a placeholder. + +Additionally, the function name is `+hash_blake3+` (line 176) but it +actually calls libsodium’s `+crypto_generichash+` which is BLAKE2b, not +BLAKE3. The docstring and function name are misleading. + +*What to do:* 1. Rename `+hash_blake3+` to `+hash_blake2b+` or add a +real BLAKE3 implementation (the BLAKE3 reference implementation exists +in Julia via `+BLAKE3.jl+`). 2. Replace the `+kdf_argon2+` fallback with +actual PBKDF2 using Julia’s `+OpenSSL_jll+` or implement +PBKDF2-HMAC-SHA256 in pure Julia (it is a simple HMAC iteration). 3. +Respect all parameters (`+iterations+`, `+key_length+`) in the fallback +path. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl +julia --project -e ' +using ProvenCrypto + +# Test that KDF respects key_length parameter +password = Vector{UInt8}("password") +salt = rand(UInt8, 16) + +key32 = kdf_argon2(password, salt; memory_kb=1024, iterations=1, key_length=32) +@assert length(key32) == 32 + +key64 = kdf_argon2(password, salt; memory_kb=1024, iterations=1, key_length=64) +@assert length(key64) == 64 + +# Different iterations should produce different keys (if libsodium available) +# or at least different iteration counts in PBKDF2 fallback + +println("TASK 17 PASS") +' +---- + +''''' + +=== FINAL VERIFICATION + +Run this complete verification to confirm all tasks are done: + +[source,bash] +---- +cd /var$REPOS_DIR/ProvenCrypto.jl + +echo "=== FINAL VERIFICATION ===" + +# 1. Module loads without crash +julia --project -e ' +using ProvenCrypto +println("1. Module loads: OK") +println(" Backend: ", ProvenCrypto.HARDWARE_BACKEND[]) +' + +# 2. No template placeholders +count=$(grep -r "{{" --include="*.jl" --include="*.idr" --include="*.zig" --include="*.yml" . 2>/dev/null | wc -l) +echo "2. Template placeholders remaining: $count (want 0)" + +# 3. No AGPL references +agpl=$(grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.idr" --include="*.res" . 2>/dev/null | wc -l) +echo "3. AGPL references remaining: $agpl (want 0)" + +# 4. All declared extensions have files +for ext in ProvenCryptoAMDGPUExt ProvenCryptoCUDAExt ProvenCryptoMetalExt ProvenCryptoOneAPIExt ProvenCryptoSMTExt; do + [ -f "ext/${ext}.jl" ] && echo "4. Extension $ext: OK" || echo "4. Extension $ext: MISSING" +done + +# 5. SCM files exist +for f in .machine_readable/STATE.scm .machine_readable/ECOSYSTEM.scm .machine_readable/META.scm; do + [ -f "$f" ] && echo "5. $f: OK" || echo "5. $f: MISSING" +done + +# 6. Test suite passes +echo "6. Running test suite..." +julia --project -e 'using Pkg; Pkg.test("ProvenCrypto")' 2>&1 | tail -5 + +# 7. No TODO/Placeholder in helper functions (crypto implementations) +stub_count=$(grep -c "Placeholder\|# TODO:" src/postquantum/*.jl src/protocols/*.jl src/zkproofs/*.jl src/threshold/*.jl 2>/dev/null) +echo "7. Remaining stubs/TODOs in crypto code: $stub_count (want 0)" + +# 8. Kyber round-trip +julia --project -e ' +using ProvenCrypto +(pk, sk) = kyber_keygen(768) +(ct, ss1) = kyber_encapsulate(pk) +ss2 = kyber_decapsulate(sk, ct) +println("8. Kyber round-trip: ", ss1 == ss2 ? "PASS" : "FAIL") +' + +# 9. Dilithium sign/verify +julia --project -e ' +using ProvenCrypto +(pk, sk) = dilithium_keygen(2) +msg = Vector{UInt8}("test") +sig = dilithium_sign(sk, msg) +println("9. Dilithium sign/verify: ", dilithium_verify(pk, msg, sig) ? "PASS" : "FAIL") +' + +# 10. Shamir round-trip +julia --project -e ' +using ProvenCrypto +secret = Vector{UInt8}("secret") +shares = shamir_split(secret, 3, 5) +recovered = shamir_reconstruct(shares[1:3]) +println("10. Shamir round-trip: ", recovered == secret ? "PASS" : "FAIL") +' + +echo "=== FINAL VERIFICATION COMPLETE ===" +---- diff --git a/packages/ProvenCrypto.jl/SONNET-TASKS.md b/packages/ProvenCrypto.jl/SONNET-TASKS.md deleted file mode 100644 index baa94bb8d..000000000 --- a/packages/ProvenCrypto.jl/SONNET-TASKS.md +++ /dev/null @@ -1,943 +0,0 @@ -# SONNET-TASKS: ProvenCrypto.jl - -**Date:** 2026-02-12 -**Auditor:** Claude Opus 4.6 -**Honest Completion:** ~15% - -The README and CHANGELOG claim a functioning post-quantum cryptography library with -hardware acceleration, protocol implementations, zero-knowledge proofs, threshold -cryptography, and formal verification export. In reality, every single cryptographic -algorithm is a stub returning placeholder data. The only code that actually works is: -(1) hardware backend detection (CPU SIMD level), (2) libsodium FFI wrappers for -AEAD/hashing/KDF (if libsodium is installed), and (3) proof export to files (but the -spec-to-prover translation functions are hardcoded examples, not real translators). -Everything else -- Kyber, Dilithium, SPHINCS+, Noise, Signal, TLS 1.3, zk-SNARKs, -zk-STARKs, Shamir, GPU backends -- is empty structs and functions returning empty -arrays or identity values. - -There is also a module load crash: two `__init__()` functions compete, three declared -extensions have no source files, the advanced hardware module is never included but -tests reference it, and template placeholders `{{PROJECT}}` are never replaced in 13 files. - ---- - -## GROUND RULES FOR SONNET - -1. Do NOT just add more stubs. Every function body you write must do real computation. -2. Do NOT skip verification blocks. Every task must be testable with the commands given. -3. Do NOT claim completion without running the tests. Julia must load the module and - pass all tests without errors. -4. If a task says "implement X per the NIST spec," you must follow the actual spec, not - invent a simplified version. -5. Constant-time operations are required where noted. Using `rand()` as a placeholder - for cryptographic sampling is a security vulnerability. -6. The ABI/FFI files (Idris, Zig) are RSR template boilerplate -- they still have - `ProvenCrypto` placeholders. Either customize them for ProvenCrypto or remove them. - ---- - -## TASK 1: Fix Module Load Crash -- Dual `__init__()` and Missing Include - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/ProvenCrypto.jl` (lines 118-121) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/primitives/ffi_wrappers.jl` (lines 237-239) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/backends/advanced_hardware.jl` (entire file -- never included) - -**Problem:** -Two `function __init__()` definitions exist. The one in `ffi_wrappers.jl` (line 237) -calls `__init_libsodium__()`, and the one in `ProvenCrypto.jl` (line 118) calls -`detect_hardware()`. Julia modules can only have one `__init__()`. The second definition -silently overwrites the first. Whichever file is `include()`d last wins, meaning either -libsodium never loads or hardware detection never runs. - -Additionally, `src/backends/advanced_hardware.jl` defines `HardwareFeatures`, -`detect_hardware_features()`, and `print_hardware_report()` but is never `include()`d in -the main module. The test file (`test/runtests.jl` lines 17-18) calls these functions, -so the test suite will crash with `UndefVarError`. - -**What to do:** -1. Remove the `__init__()` from `ffi_wrappers.jl`. Rename it to `init_libsodium()` or - similar. -2. In the main `ProvenCrypto.jl` `__init__()`, call both `init_libsodium()` and - `detect_hardware()`. -3. Add `include("backends/advanced_hardware.jl")` to `ProvenCrypto.jl` after line 102 - (after `include("backends/hardware.jl")`). -4. Export `HardwareFeatures`, `detect_hardware_features`, and `print_hardware_report` - from the module. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto -# Module loaded without crash -println("Module loaded OK") -# Hardware detection ran -println("Backend: ", ProvenCrypto.HARDWARE_BACKEND[]) -# Advanced hardware features available -features = detect_hardware_features() -println("Features type: ", typeof(features)) -@assert features isa HardwareFeatures -println("TASK 1 PASS") -' -``` - ---- - -## TASK 2: Fix Missing Extensions (3 Declared but No Source Files) - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/Project.toml` (lines 24, 27, 28) -- Missing: `ext/ProvenCryptoAMDGPUExt.jl` -- Missing: `ext/ProvenCryptoOneAPIExt.jl` -- Missing: `ext/ProvenCryptoSMTExt.jl` - -**Problem:** -`Project.toml` declares five extensions: -```toml -ProvenCryptoAMDGPUExt = ["AMDGPU"] -ProvenCryptoCUDAExt = ["CUDA"] -ProvenCryptoMetalExt = ["Metal"] -ProvenCryptoOneAPIExt = ["oneAPI"] -ProvenCryptoSMTExt = ["SMTLib"] -``` -Only three files exist (`ext/ProvenCryptoCUDAExt.jl`, `ext/ProvenCryptoMetalExt.jl`, -`ext/ProvenCryptoROCmExt.jl`). Note that the ROCm extension file exists but is named -`ProvenCryptoROCmExt.jl` while the Project.toml declares `ProvenCryptoAMDGPUExt`. This -is a mismatch -- Julia looks for a module named `ProvenCryptoAMDGPUExt` but the file -defines `module ProvenCryptoROCmExt`. - -The `ProvenCryptoOneAPIExt.jl` and `ProvenCryptoSMTExt.jl` files do not exist at all. - -**What to do:** -1. Rename `ext/ProvenCryptoROCmExt.jl` to `ext/ProvenCryptoAMDGPUExt.jl` and change - the internal `module ProvenCryptoROCmExt` to `module ProvenCryptoAMDGPUExt`. -2. Create `ext/ProvenCryptoOneAPIExt.jl` with at minimum the `oneapi_available()` override - and stub backend methods (matching the pattern in MetalExt). -3. Create `ext/ProvenCryptoSMTExt.jl` with `@prove` macro integration for SMT-LIB solvers. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -# Check all declared extensions have matching files -for ext in ProvenCryptoAMDGPUExt ProvenCryptoCUDAExt ProvenCryptoMetalExt ProvenCryptoOneAPIExt ProvenCryptoSMTExt; do - if [ -f "ext/${ext}.jl" ]; then - echo "OK: ext/${ext}.jl exists" - grep -q "module ${ext}" "ext/${ext}.jl" && echo " module name matches" || echo " ERROR: module name mismatch" - else - echo "MISSING: ext/${ext}.jl" - fi -done -``` - ---- - -## TASK 3: Implement CPU NTT Backend (Blocks All Post-Quantum Algorithms) - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/backends/hardware.jl` (lines 247-257) - -**Problem:** -Four critical CPU backend functions are placeholders that return identity or garbage: - -- `backend_ntt_transform(::CPUBackend, poly, modulus)` at line 248: returns `poly` unchanged. - NTT (Number Theoretic Transform) is the core operation for all lattice-based crypto. - Without it, Kyber and Dilithium produce mathematically wrong results. - -- `backend_polynomial_multiply(::CPUBackend, a, b, modulus)` at line 252: returns `a` - unchanged, ignoring `b` entirely. - -- `backend_sampling(::CPUBackend, distribution, params...)` at line 256: calls `randn()` - which returns a Float64 instead of a properly sampled integer from the specified - distribution. - -- `backend_ntt_inverse_transform` at kyber.jl line 213: global stub returns `poly` - unchanged. - -**What to do:** -1. Implement Cooley-Tukey NTT for `backend_ntt_transform` over `Z_q` where `q=3329` - (Kyber) or `q=8380417` (Dilithium). Use primitive roots of unity for each modulus. -2. Implement inverse NTT for `backend_ntt_inverse_transform`. Move it from the kyber.jl - stub to `hardware.jl` as a proper `CPUBackend` method. -3. Implement polynomial multiplication via NTT: `a*b = INTT(NTT(a) .* NTT(b))` mod q. -4. Implement constant-time centered binomial distribution sampling for `:cbd` and - uniform sampling for `:uniform`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto -backend = CPUBackend(:avx2, 1) - -# NTT round-trip test: INTT(NTT(x)) == x -q = 3329 -x = rand(0:q-1, 256) -x_ntt = ProvenCrypto.backend_ntt_transform(backend, x, q) -x_recovered = ProvenCrypto.backend_ntt_inverse_transform(backend, x_ntt, q) -@assert x_recovered == x "NTT round-trip failed" - -# Polynomial multiplication test: (1+x) * (1+x) mod q -a = zeros(Int, 256); a[1] = 1; a[2] = 1 -b = zeros(Int, 256); b[1] = 1; b[2] = 1 -c = ProvenCrypto.backend_polynomial_multiply(backend, a, b, q) -@assert c[1] == 1 # constant term -@assert c[2] == 2 # x coefficient -@assert c[3] == 1 # x^2 coefficient - -println("TASK 3 PASS") -' -``` - ---- - -## TASK 4: Implement Kyber KEM Helper Functions - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/postquantum/kyber.jl` (lines 169-213) - -**Problem:** -Seven helper functions are stubs returning garbage: - -1. `kyber_gen_matrix` (line 170): Returns `rand(Int, k, n) .% q` instead of - deterministically generating matrix A from seed via SHAKE-128 (XOF). -2. `kyber_sample_cbd` (line 176): Returns `rand(Int, k, n) .- (eta / 2)` instead of - constant-time centered binomial distribution sampling. -3. `kyber_encode` (line 182): Returns `zeros(Int, length(msg)*8)` -- wrong dimensions, - wrong values. -4. `kyber_decode` (line 188): Returns `UInt8[]` -- empty array, loses all data. -5. `kyber_compress` (line 194): Returns `UInt8[]` -- empty, makes ciphertext vanish. -6. `kyber_decompress` (line 200): Returns zeros -- makes decapsulation impossible. -7. `encode_pk` (line 206): Returns `UInt8[]` -- empty serialization breaks hashing. - -The top-level functions (`kyber_keygen`, `kyber_encapsulate`, `kyber_decapsulate`) have -correct structure but produce wrong results because every helper returns garbage. - -**What to do:** -Implement each function per FIPS 203 (ML-KEM) / the Kyber specification: -1. `kyber_gen_matrix`: Use SHAKE-128 (or SHA3) to expand seed into matrix A. Julia's SHA - package has SHA3 support. -2. `kyber_sample_cbd`: Implement CBD_eta sampling per Algorithm 2 of the Kyber spec. -3. `kyber_encode`/`kyber_decode`: Implement Compress_d and Decompress_d per Kyber spec - Section 4.2.1. -4. `kyber_compress`/`kyber_decompress`: Implement byte-level compression per spec. -5. `encode_pk`: Serialize `(t, rho)` as per spec byte encoding. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# Full Kyber round-trip -(pk, sk) = kyber_keygen(512) -(ciphertext, ss_sender) = kyber_encapsulate(pk) -ss_receiver = kyber_decapsulate(sk, ciphertext) - -@assert length(ss_sender) == 32 "Shared secret must be 32 bytes" -@assert length(ss_receiver) == 32 "Recovered secret must be 32 bytes" -@assert length(ciphertext) > 0 "Ciphertext must not be empty" - -# Key sizes per spec -@assert pk.level == 512 - -println("Kyber round-trip: shared secrets match = ", ss_sender == ss_receiver) -println("TASK 4 PASS") -' -``` - ---- - -## TASK 5: Implement Dilithium Signature Helper Functions - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/postquantum/dilithium.jl` (lines 211-254) - -**Problem:** -Nine helper functions are stubs: - -1. `dilithium_expand_matrix` (line 212): `rand(Int, k*n, l*n) .% q` -- non-deterministic, - wrong dimensions (should be k-by-l of n-polynomials, not a single flat matrix). -2. `dilithium_sample_eta` (line 216): `rand(Int, rows, n) .- eta` -- not CBD, not - constant-time, wrong distribution. -3. `dilithium_sample_y` (line 220): `rand(Int, l, n) .% gamma1` -- should use - rejection sampling from `[-gamma1+1, gamma1]`. -4. `dilithium_sample_in_ball` (line 224): Returns `zeros(Int, n)` -- must sample a - polynomial with exactly `tau` nonzero coefficients in {-1, +1}. -5. `dilithium_high_bits` (line 235): Returns `w` unchanged -- must extract HighBits per spec. -6. `dilithium_low_bits` (line 239): Returns `w` unchanged -- must extract LowBits per spec. -7. `dilithium_make_hint` (line 243): Returns `Bool[]` -- must compute MakeHint per spec. -8. `dilithium_use_hint` (line 248): Returns `w` unchanged -- must apply UseHint per spec. -9. `encode_vector` (line 252): Returns `UInt8[]` -- must serialize polynomial vector. - -Additionally, `encode_pk` is called for `DilithiumPublicKey` (lines 108, 180) but only -has a method for `KyberPublicKey` (kyber.jl line 206). This is a `MethodError` crash. - -**What to do:** -1. Add an `encode_pk(pk::DilithiumPublicKey)` method in dilithium.jl. -2. Implement all nine helpers per FIPS 204 (ML-DSA) / Dilithium specification. -3. The HighBits/LowBits/MakeHint/UseHint functions are defined in Dilithium spec - Section 3.1 -- follow those definitions exactly. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# Full Dilithium sign/verify round-trip -(pk, sk) = dilithium_keygen(2) -message = Vector{UInt8}("Test message for Dilithium") -signature = dilithium_sign(sk, message) - -@assert signature isa DilithiumSignature -@assert length(signature.c_tilde) == 32 -@assert length(signature.z) > 0 - -is_valid = dilithium_verify(pk, message, signature) -@assert is_valid "Valid signature must verify" - -# Tampered message must fail -tampered = Vector{UInt8}("Tampered message") -@assert !dilithium_verify(pk, tampered, signature) "Tampered message must not verify" - -println("TASK 5 PASS") -' -``` - ---- - -## TASK 6: Implement SPHINCS+ Helper Functions - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/postquantum/sphincs.jl` (lines 150-185) - -**Problem:** -Six helper functions are stubs returning empty arrays or zeros: - -1. `sphincs_compute_root` (line 151): Returns `rand(UInt8, params.n)` -- must compute - Merkle hypertree root using WOTS+ and tree hashing. -2. `sphincs_parse_digest` (line 156): Returns `(0, 0)` -- must split digest into tree - index and leaf index per spec. -3. `sphincs_fors_sign` (line 161): Returns `UInt8[]` -- must implement FORS (Forest of - Random Subsets) signing. -4. `sphincs_fors_verify` (line 167): Returns `UInt8[]` -- must verify FORS and return - the FORS public key. -5. `sphincs_ht_sign` (line 173): Returns `UInt8[]` -- must implement HyperTree signing - with WOTS+ chains. -6. `sphincs_ht_verify` (line 180): Returns `UInt8[]` -- must verify HyperTree path - and return reconstructed root. - -**What to do:** -Implement each function per the SPHINCS+ specification (NIST SP 800-208): -1. Implement WOTS+ one-time signature scheme as the base. -2. Implement Merkle tree construction and authentication path generation. -3. Implement FORS few-time signature scheme. -4. Implement the full HyperTree structure. -5. Use hash_blake3 or SHA-256 as the tweakable hash function. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# Full SPHINCS+ sign/verify round-trip -(pk, sk) = sphincs_keygen(128, :f) # Fast variant for testing -message = Vector{UInt8}("Test message for SPHINCS+") - -signature = sphincs_sign(sk, message) -@assert length(signature.sig_bytes) > 0 "Signature must not be empty" - -is_valid = sphincs_verify(pk, message, signature) -@assert is_valid "Valid signature must verify" - -# Tampered message must fail -tampered = Vector{UInt8}("Tampered") -@assert !sphincs_verify(pk, tampered, signature) "Tampered must not verify" - -println("TASK 6 PASS") -' -``` - ---- - -## TASK 7: Implement Protocol Stubs (Noise, Signal, TLS 1.3) - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/protocols/noise.jl` (entire file -- 15 lines, empty struct) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/protocols/signal.jl` (entire file -- 14 lines, empty struct) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/protocols/tls13.jl` (entire file -- 16 lines, empty struct) - -**Problem:** -All three protocol implementations are empty structs with no fields and no methods: -```julia -struct NoiseHandshake end # noise.jl line 11 -struct SignalRatchet end # signal.jl line 10 -struct TLS13Session end # tls13.jl line 12 -``` -These types are exported from the main module but have zero functionality. The README -and module docstring list them as features. - -**What to do:** -For each protocol, implement at minimum: - -**Noise Protocol (noise.jl):** -- `NoiseHandshake` struct with: pattern (XX, IK, NK), static keypair, ephemeral keypair, - handshake state, cipher state. -- `noise_initiator()` / `noise_responder()` constructors. -- `noise_write_message()` / `noise_read_message()` for handshake messages. -- `noise_split()` to derive transport keys after handshake. -- Use `aead_encrypt`/`aead_decrypt` from ffi_wrappers for the symmetric crypto. - -**Signal Protocol (signal.jl):** -- `SignalRatchet` struct with: root key, chain key, message keys, DH ratchet state. -- `signal_init_sender()` / `signal_init_receiver()`. -- `signal_ratchet_encrypt()` / `signal_ratchet_decrypt()`. -- Implement the Double Ratchet algorithm per the Signal spec. - -**TLS 1.3 (tls13.jl):** -- `TLS13Session` struct with: handshake state, cipher suite, keys. -- `tls13_client_hello()` / `tls13_server_hello()`. -- Key schedule derivation using HKDF. -- This is educational/reference only (per the file's own docstring). - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# Noise: basic handshake -hs_init = NoiseHandshake # Should have constructor with pattern -@assert fieldcount(NoiseHandshake) > 0 "NoiseHandshake must have fields" - -# Signal: basic ratchet -@assert fieldcount(SignalRatchet) > 0 "SignalRatchet must have fields" - -# TLS 1.3: basic session -@assert fieldcount(TLS13Session) > 0 "TLS13Session must have fields" - -println("TASK 7 PASS") -' -``` - ---- - -## TASK 8: Implement Zero-Knowledge Proof Systems - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/zkproofs/zksnark.jl` (entire file -- 28 lines) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/zkproofs/zkstark.jl` (entire file -- 14 lines) - -**Problem:** -`zk_prove` (line 18) returns `ZKProof(UInt8[], UInt8[])` -- empty proof data. -`zk_verify` (line 23) always returns `false`. -`zkstark.jl` has no code at all beyond a docstring comment. - -**What to do:** -1. In `zksnark.jl`: - - Define a `Circuit` type (R1CS constraint system: matrices A, B, C). - - Define a `Witness` type (assignment of values satisfying constraints). - - Implement a simplified Groth16 prover: generate proof elements (A, B, C points). - - Implement verifier: pairing check e(A,B) = e(alpha,beta) * e(C,delta). - - At minimum, support boolean circuit verification. - -2. In `zkstark.jl`: - - Define `STARKProof` struct. - - Implement polynomial commitment via Merkle tree (FRI protocol). - - Implement `stark_prove()` and `stark_verify()`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# zk-SNARK: prove knowledge of x such that x^2 = 9 -# (simplified circuit) -proof = zk_prove(nothing, nothing) # Replace with real circuit/witness -@assert length(proof.proof_data) > 0 "Proof must contain data" - -valid = zk_verify(proof, nothing) -@assert typeof(valid) == Bool - -println("TASK 8 PASS") -' -``` - ---- - -## TASK 9: Implement Shamir Secret Sharing - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/threshold/shamir.jl` (lines 14-23) - -**Problem:** -`shamir_split` (line 14) returns `[UInt8[] for _ in 1:num_shares]` -- a list of empty -byte arrays. No polynomial evaluation, no GF(2^8) arithmetic, no secret encoding. - -`shamir_reconstruct` (line 19) returns `UInt8[]` -- empty, ignoring all shares. - -**What to do:** -1. Implement Shamir's Secret Sharing over GF(256) (or a large prime field): - - `shamir_split`: Generate random polynomial of degree `threshold-1` with constant - term = secret byte. Evaluate at `num_shares` distinct points. - - `shamir_reconstruct`: Use Lagrange interpolation to recover the constant term. -2. Handle multi-byte secrets by splitting each byte independently. -3. Validate: `threshold <= num_shares`, `threshold >= 2`, `num_shares <= 255`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -secret = Vector{UInt8}("SuperSecretKey!!") -shares = shamir_split(secret, 3, 5) - -# Must produce 5 non-empty shares -@assert length(shares) == 5 -for s in shares - @assert length(s) > 0 "Share must not be empty" -end - -# Reconstruct from any 3 shares -recovered = shamir_reconstruct(shares[1:3]) -@assert recovered == secret "3-of-5 reconstruction must recover secret" - -# Reconstruct from different 3 shares -recovered2 = shamir_reconstruct(shares[3:5]) -@assert recovered2 == secret "Different 3-of-5 must also work" - -# 2 shares must NOT be enough (if implemented with threshold check) -# This depends on implementation -- at minimum verify 3-of-5 works - -println("TASK 9 PASS") -' -``` - ---- - -## TASK 10: Implement Real Proof-Export Spec Translators - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/verification/proof_export.jl` (lines 228-251) - -**Problem:** -All four translation functions return hardcoded example strings regardless of input: - -```julia -translate_spec_to_idris_type(spec) = "(a : Nat) -> (b : Nat) -> a + b = b + a" # line 230 -translate_spec_to_lean(spec) = "forall (a b : N), a + b = b + a" # line 234 -translate_spec_to_coq(spec) = "forall (a b : nat), a + b = b + a" # line 238 -translate_spec_to_isabelle(spec) = "\\a b::nat. a + b = b + a" # line 242 -``` - -The `spec` argument is completely ignored. Any specification string produces the same -commutativity theorem in the output file. - -**What to do:** -1. Define a small specification language or parse a subset of SMT-LIB2 syntax. -2. Translate quantifiers (`forall`, `exists`), arithmetic, equality, and basic types. -3. At minimum, handle: - - Universal quantification: `forall x : T. P(x)` - - Equality: `a = b` - - Implication: `P => Q` - - Basic types: `Nat`, `Int`, `Bool`, `ByteVector` -4. If full SMT-LIB parsing is too complex, at minimum pass through the spec string - with appropriate syntax adjustments for each target language instead of ignoring it. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# Two different specs must produce different output -spec1 = "forall x : Nat. x + 0 = x" -spec2 = "forall a b : Nat. a * b = b * a" - -idris1 = ProvenCrypto.translate_spec_to_idris_type(spec1) -idris2 = ProvenCrypto.translate_spec_to_idris_type(spec2) -@assert idris1 != idris2 "Different specs must produce different translations" - -lean1 = ProvenCrypto.translate_spec_to_lean(spec1) -lean2 = ProvenCrypto.translate_spec_to_lean(spec2) -@assert lean1 != lean2 "Different specs must produce different Lean translations" - -println("TASK 10 PASS") -' -``` - ---- - -## TASK 11: Replace Template Placeholders in ABI/FFI Files - -**Files (13 files with `{{PROJECT}}` or `{{project}}` placeholders):** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/abi/Types.idr` (3 occurrences: `{{PROJECT}}.ABI.Types`, etc.) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/abi/Layout.idr` (2 occurrences: `{{PROJECT}}.ABI.Layout`, imports) -- `/var$REPOS_DIR/ProvenCrypto.jl/src/abi/Foreign.idr` (14 occurrences: module name, all `%foreign` declarations) -- `/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/build.zig` (6 occurrences: library name, header, benchmark) -- `/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/src/main.zig` (19 occurrences: all export functions) -- `/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/test/integration_test.zig` (44 occurrences: all extern declarations and test calls) -- Plus occurrences in: `SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, - `ABI-FFI-README.md`, `.github/workflows/quality.yml`, `ci.yml`, `release.yml` - -**Problem:** -184 total `{{...}}` placeholder occurrences across 13 files. These are RSR template -markers that should have been replaced when the repo was created from the template. The -Idris modules will not compile, the Zig code will not build, and the workflows reference -a nonexistent project name. - -**What to do:** -1. Replace `{{PROJECT}}` with `ProvenCrypto` (capitalized, for module names and titles). -2. Replace `{{project}}` with `provencrypto` (lowercase, for library names and C symbols). -3. Replace `{{OWNER}}` with `hyperpolymath`. -4. Replace `{{FORGE}}` with `github.com`. -5. Replace `{{REPO}}` with `ProvenCrypto.jl`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -count=$(grep -r '{{' --include='*.idr' --include='*.zig' --include='*.yml' --include='*.md' --include='*.adoc' --include='*.res' -l . 2>/dev/null | wc -l) -if [ "$count" -eq 0 ]; then - echo "TASK 11 PASS: No template placeholders remain" -else - echo "TASK 11 FAIL: $count files still contain {{ placeholders" - grep -r '{{' --include='*.idr' --include='*.zig' --include='*.yml' --include='*.md' --include='*.adoc' --include='*.res' -l . -fi -``` - ---- - -## TASK 12: Fix SPDX License Headers (AGPL-3.0 Must Be MPL-2.0) - -**Files with wrong license:** -- `/var$REPOS_DIR/ProvenCrypto.jl/examples/SafeDOMExample.res` line 1: `AGPL-3.0-or-later` -- `/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/build.zig` line 2: `AGPL-3.0-or-later` -- `/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/src/main.zig` line 6: `AGPL-3.0-or-later` -- `/var$REPOS_DIR/ProvenCrypto.jl/ffi/zig/test/integration_test.zig` line 2: `AGPL-3.0-or-later` -- `/var$REPOS_DIR/ProvenCrypto.jl/docs/CITATIONS.adoc` line 13: `license = {AGPL-3.0-or-later}` - -**Problem:** -Per the CLAUDE.md license policy, hyperpolymath original code must use -`MPL-2.0`. AGPL-3.0 is the old license and must never be used. - -**What to do:** -1. Replace all `AGPL-3.0-or-later` SPDX identifiers with `MPL-2.0`. -2. Update `docs/CITATIONS.adoc` BibTeX entry from `AGPL-3.0-or-later` to `MPL-2.0`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -agpl_count=$(grep -r 'AGPL' --include='*.jl' --include='*.zig' --include='*.idr' --include='*.res' --include='*.adoc' . 2>/dev/null | wc -l) -if [ "$agpl_count" -eq 0 ]; then - echo "TASK 12 PASS: No AGPL references remain" -else - echo "TASK 12 FAIL: $agpl_count lines still reference AGPL" - grep -rn 'AGPL' --include='*.jl' --include='*.zig' --include='*.idr' --include='*.res' --include='*.adoc' . -fi -``` - ---- - -## TASK 13: Fix GPU Extension Backends (All Are Fallback-Only Placeholders) - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/ext/ProvenCryptoCUDAExt.jl` (lines 12-14) -- `/var$REPOS_DIR/ProvenCrypto.jl/ext/ProvenCryptoMetalExt.jl` (lines 25-62) -- `/var$REPOS_DIR/ProvenCrypto.jl/ext/ProvenCryptoROCmExt.jl` (lines 25-62) - -**Problem:** -All GPU backend methods are placeholders that immediately fall back to CPU: - -```julia -# MetalExt.jl line 27 -@warn "Metal lattice multiplication not yet implemented; falling back to CPU" -return ProvenCrypto.backend_lattice_multiply(ProvenCrypto.CPUBackend(:neon, ...), A, x) -``` - -Same pattern for `backend_ntt_transform`, `backend_polynomial_multiply`, and -`backend_sampling` in both Metal and ROCm extensions. The CUDA extension (line 13) -has an empty function body: - -```julia -function ProvenCrypto.backend_lattice_multiply(backend::ProvenCrypto.CUDABackend, args...) - # CUDA-specific implementation -end -``` - -This silently returns `nothing` instead of a matrix, which will crash any caller. - -**What to do:** -1. For CUDA: Implement lattice multiplication using `CUDA.jl` `CuArray` operations. - Use `CUDA.@cuda` kernel for NTT if performance matters, or use cuBLAS for matrix ops. -2. For Metal: Implement using `Metal.jl` MtlArray operations. -3. For ROCm: Implement using `AMDGPU.jl` ROCArray operations. -4. At minimum, each backend_lattice_multiply must return a valid matrix/vector result, - not `nothing`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -# Verify no empty function bodies in extensions -for ext in ext/ProvenCrypto*.jl; do - empty=$(grep -c '^\s*end\s*$' "$ext") - funcs=$(grep -c 'function ProvenCrypto\.' "$ext") - echo "$ext: $funcs functions, checking for empty bodies..." - # Check that no function has an immediately-following end with only a comment between - grep -Pzo 'function[^)]+\)\n\s*#[^\n]*\n\s*end' "$ext" && echo " WARNING: empty function body found" || echo " OK" -done -``` - ---- - -## TASK 14: Add Missing .machine_readable/ Directory and SCM Files - -**Files (all missing):** -- `/var$REPOS_DIR/ProvenCrypto.jl/.machine_readable/STATE.scm` -- `/var$REPOS_DIR/ProvenCrypto.jl/.machine_readable/ECOSYSTEM.scm` -- `/var$REPOS_DIR/ProvenCrypto.jl/.machine_readable/META.scm` - -**Problem:** -Per CLAUDE.md checkpoint file protocol, every hyperpolymath repo MUST have SCM files in -`.machine_readable/`. This directory does not exist at all. The ROADMAP.adoc is still -the RSR template text ("YOUR Template Repo Roadmap") and the CITATIONS.adoc references -"RSR-template-repo" instead of "ProvenCrypto.jl". - -**What to do:** -1. Create `.machine_readable/` directory. -2. Create `STATE.scm` with: metadata, project-context (ProvenCrypto.jl -- post-quantum - crypto library for Julia), current-position (v0.1.1, mostly stubs), route-to-mvp, - blockers (all algorithms are placeholders), critical-next-actions. -3. Create `ECOSYSTEM.scm` with: relationship to `proven` (Idris library), `hypatia` - (CI/CD), `verisimdb` (vulnerability DB). -4. Create `META.scm` with: architecture decisions (pure Julia + FFI), license (PMPL), - design rationale. -5. Update `ROADMAP.adoc` from template text to actual ProvenCrypto milestones. -6. Update `docs/CITATIONS.adoc` from "RSR-template-repo" to "ProvenCrypto.jl". - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -for f in .machine_readable/STATE.scm .machine_readable/ECOSYSTEM.scm .machine_readable/META.scm; do - if [ -f "$f" ]; then - echo "OK: $f exists ($(wc -l < "$f") lines)" - else - echo "MISSING: $f" - fi -done -# Verify ROADMAP is customized -grep -q "ProvenCrypto" ROADMAP.adoc && echo "ROADMAP customized" || echo "ROADMAP still template" -# Verify CITATIONS is customized -grep -q "ProvenCrypto" docs/CITATIONS.adoc && echo "CITATIONS customized" || echo "CITATIONS still template" -``` - ---- - -## TASK 15: Fix Changelog Lies and Add Missing Preferences.jl Dependency - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/CHANGELOG.md` (line 22) -- `/var$REPOS_DIR/ProvenCrypto.jl/Project.toml` - -**Problem:** -The CHANGELOG v0.1.1 entry (line 22) states: -> "Dependencies: Added Preferences.jl for user-configurable fallback behavior" - -But `Preferences` is not listed in `Project.toml` `[deps]` or `[weakdeps]`. It is not -used anywhere in the codebase. This is a false claim. - -The README also references a `benchmark/benchmarks.jl` file and `docs/make.jl` file -that do not exist. - -**What to do:** -Either: -- (A) Add `Preferences` to `[deps]` in Project.toml and implement the configurable - fallback behavior the changelog claims exists, OR -- (B) Remove the false claim from the changelog. - -Also: -- Create `benchmark/benchmarks.jl` (at least a stub using BenchmarkTools.jl) or remove - the README reference. -- Create `docs/make.jl` (using Documenter.jl) or remove the README reference. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -# Check Preferences is either used or the claim is removed -if grep -q 'Preferences' CHANGELOG.md; then - grep -q 'Preferences' Project.toml && echo "OK: Preferences in Project.toml" || echo "FAIL: Changelog claims Preferences but not in Project.toml" -else - echo "OK: False Preferences claim removed from changelog" -fi -# Check referenced files exist -[ -f benchmark/benchmarks.jl ] && echo "OK: benchmark exists" || echo "MISSING: benchmark/benchmarks.jl (referenced in README)" -[ -f docs/make.jl ] && echo "OK: docs/make.jl exists" || echo "MISSING: docs/make.jl (referenced in README)" -``` - ---- - -## TASK 16: Fix Test Suite to Actually Test Crypto Operations - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/test/runtests.jl` (lines 74-111) - -**Problem:** -The post-quantum test sections only test struct construction, not actual crypto operations: - -```julia -# test/runtests.jl lines 76-85 -(pk, sk) = kyber_keygen(512) -@test pk isa KyberPublicKey # Only tests type, not correctness -@test sk isa KyberSecretKey -@test pk.level == 512 -# TODO: Test encapsulation/decapsulation when NTT is implemented -# (ciphertext, ss_sender) = kyber_encapsulate(pk) <-- COMMENTED OUT -``` - -The `TODO` comments at lines 82, 95, and 109 indicate the developers knew these tests -were incomplete. Once Tasks 3-6 are complete, the commented-out tests must be enabled -and expanded. - -**What to do:** -1. Uncomment all `# TODO` test blocks (lines 82-85, 95-98, 109). -2. Add edge case tests: wrong key sizes, empty messages, corrupted ciphertexts. -3. Add round-trip tests for each algorithm at all security levels. -4. Add test for `shamir_split`/`shamir_reconstruct` (currently no test exists at all). -5. Add tests for `zk_prove`/`zk_verify` (currently no test exists). -6. Add tests for protocol structs once they have real fields (Task 7). - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e 'using Pkg; Pkg.test("ProvenCrypto")' -# All tests must pass with zero TODO comments in test output -grep -c 'TODO' test/runtests.jl -# Should be 0 -``` - ---- - -## TASK 17: Fix `kdf_argon2` Fallback (SHA-256 Is Not PBKDF2) - -**Files:** -- `/var$REPOS_DIR/ProvenCrypto.jl/src/primitives/ffi_wrappers.jl` (line 218) - -**Problem:** -When libsodium is unavailable, the fallback is: -```julia -return SHA.sha256(vcat(password, salt)) # Placeholder; replace with PBKDF2 -``` -This is not a KDF. It ignores the `memory_kb`, `iterations`, `parallelism`, and -`key_length` parameters entirely. SHA-256(password || salt) is trivially brute-forceable -and the comment admits it is a placeholder. - -Additionally, the function name is `hash_blake3` (line 176) but it actually calls -libsodium's `crypto_generichash` which is BLAKE2b, not BLAKE3. The docstring and -function name are misleading. - -**What to do:** -1. Rename `hash_blake3` to `hash_blake2b` or add a real BLAKE3 implementation (the - BLAKE3 reference implementation exists in Julia via `BLAKE3.jl`). -2. Replace the `kdf_argon2` fallback with actual PBKDF2 using Julia's `OpenSSL_jll` or - implement PBKDF2-HMAC-SHA256 in pure Julia (it is a simple HMAC iteration). -3. Respect all parameters (`iterations`, `key_length`) in the fallback path. - -**Verification:** -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl -julia --project -e ' -using ProvenCrypto - -# Test that KDF respects key_length parameter -password = Vector{UInt8}("password") -salt = rand(UInt8, 16) - -key32 = kdf_argon2(password, salt; memory_kb=1024, iterations=1, key_length=32) -@assert length(key32) == 32 - -key64 = kdf_argon2(password, salt; memory_kb=1024, iterations=1, key_length=64) -@assert length(key64) == 64 - -# Different iterations should produce different keys (if libsodium available) -# or at least different iteration counts in PBKDF2 fallback - -println("TASK 17 PASS") -' -``` - ---- - -## FINAL VERIFICATION - -Run this complete verification to confirm all tasks are done: - -```bash -cd /var$REPOS_DIR/ProvenCrypto.jl - -echo "=== FINAL VERIFICATION ===" - -# 1. Module loads without crash -julia --project -e ' -using ProvenCrypto -println("1. Module loads: OK") -println(" Backend: ", ProvenCrypto.HARDWARE_BACKEND[]) -' - -# 2. No template placeholders -count=$(grep -r "{{" --include="*.jl" --include="*.idr" --include="*.zig" --include="*.yml" . 2>/dev/null | wc -l) -echo "2. Template placeholders remaining: $count (want 0)" - -# 3. No AGPL references -agpl=$(grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.idr" --include="*.res" . 2>/dev/null | wc -l) -echo "3. AGPL references remaining: $agpl (want 0)" - -# 4. All declared extensions have files -for ext in ProvenCryptoAMDGPUExt ProvenCryptoCUDAExt ProvenCryptoMetalExt ProvenCryptoOneAPIExt ProvenCryptoSMTExt; do - [ -f "ext/${ext}.jl" ] && echo "4. Extension $ext: OK" || echo "4. Extension $ext: MISSING" -done - -# 5. SCM files exist -for f in .machine_readable/STATE.scm .machine_readable/ECOSYSTEM.scm .machine_readable/META.scm; do - [ -f "$f" ] && echo "5. $f: OK" || echo "5. $f: MISSING" -done - -# 6. Test suite passes -echo "6. Running test suite..." -julia --project -e 'using Pkg; Pkg.test("ProvenCrypto")' 2>&1 | tail -5 - -# 7. No TODO/Placeholder in helper functions (crypto implementations) -stub_count=$(grep -c "Placeholder\|# TODO:" src/postquantum/*.jl src/protocols/*.jl src/zkproofs/*.jl src/threshold/*.jl 2>/dev/null) -echo "7. Remaining stubs/TODOs in crypto code: $stub_count (want 0)" - -# 8. Kyber round-trip -julia --project -e ' -using ProvenCrypto -(pk, sk) = kyber_keygen(768) -(ct, ss1) = kyber_encapsulate(pk) -ss2 = kyber_decapsulate(sk, ct) -println("8. Kyber round-trip: ", ss1 == ss2 ? "PASS" : "FAIL") -' - -# 9. Dilithium sign/verify -julia --project -e ' -using ProvenCrypto -(pk, sk) = dilithium_keygen(2) -msg = Vector{UInt8}("test") -sig = dilithium_sign(sk, msg) -println("9. Dilithium sign/verify: ", dilithium_verify(pk, msg, sig) ? "PASS" : "FAIL") -' - -# 10. Shamir round-trip -julia --project -e ' -using ProvenCrypto -secret = Vector{UInt8}("secret") -shares = shamir_split(secret, 3, 5) -recovered = shamir_reconstruct(shares[1:3]) -println("10. Shamir round-trip: ", recovered == secret ? "PASS" : "FAIL") -' - -echo "=== FINAL VERIFICATION COMPLETE ===" -``` diff --git a/packages/ProvenCrypto.jl/TOPOLOGY.md b/packages/ProvenCrypto.jl/TOPOLOGY.adoc similarity index 90% rename from packages/ProvenCrypto.jl/TOPOLOGY.md rename to packages/ProvenCrypto.jl/TOPOLOGY.adoc index 7ca9d03dd..e0a0686c4 100644 --- a/packages/ProvenCrypto.jl/TOPOLOGY.md +++ b/packages/ProvenCrypto.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== ProvenCrypto.jl — Project Topology -# ProvenCrypto.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / HARDWARE │ ├─────────────────────────────────────────┤ @@ -48,11 +44,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── POST-QUANTUM @@ -76,24 +72,25 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~90% Feature Complete (Research) -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... libsodium FFI ──────► Protocols (Noise) ──────► Hardware Accel │ Post-Quantum ───────► Formal Proofs ──────────► COMPLETE -``` +.... -## 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/packages/SMTLib.jl/ABI-FFI-README.md b/packages/SMTLib.jl/ABI-FFI-README.adoc similarity index 75% rename from packages/SMTLib.jl/ABI-FFI-README.md rename to packages/SMTLib.jl/ABI-FFI-README.adoc index dd4d4e201..7d44c3e23 100644 --- a/packages/SMTLib.jl/ABI-FFI-README.md +++ b/packages/SMTLib.jl/ABI-FFI-README.adoc @@ -1,18 +1,20 @@ +== SMTLib ABI/FFI Documentation -# SMTLib ABI/FFI Documentation +=== Overview -## Overview +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI +=== Architecture -## Architecture - -``` +.... ┌─────────────────────────────────────────────┐ │ ABI Definitions (Idris2) │ │ src/abi/ │ @@ -44,11 +46,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: │ Any Language via C ABI │ │ - Rust, ReScript, Julia, Python, etc. │ └─────────────────────────────────────────────┘ -``` +.... -## Directory Structure +=== Directory Structure -``` +.... smtlib/ ├── src/ │ ├── abi/ # ABI definitions (Idris2) @@ -76,15 +78,17 @@ smtlib/ ├── rust/ ├── rescript/ └── julia/ -``` +.... -## Why Idris2 for ABI? +=== Why Idris2 for ABI? -### 1. **Formal Verification** +==== 1. *Formal Verification* -Idris2's dependent types allow proving properties about the ABI at compile-time: +Idris2’s dependent types allow proving properties about the ABI at +compile-time: -```idris +[source,idris] +---- -- Prove struct size is correct public export exampleStructSize : HasSize ExampleStruct 16 @@ -96,13 +100,14 @@ fieldAligned : Divides 8 (offsetOf ExampleStruct.field) -- Prove ABI is platform-compatible public export abiCompatible : Compatible (ABI 1) (ABI 2) -``` +---- -### 2. **Type Safety** +==== 2. *Type Safety* Encode invariants that C/Zig cannot express: -```idris +[source,idris] +---- -- Non-null pointer guaranteed at type level data Handle : Type where MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle @@ -110,13 +115,14 @@ data Handle : Type where -- Array with length proof data Buffer : (n : Nat) -> Type where MkBuffer : Vect n Byte -> Buffer n -``` +---- -### 3. **Platform Abstraction** +==== 3. *Platform Abstraction* Platform-specific types with compile-time selection: -```idris +[source,idris] +---- CInt : Platform -> Type CInt Linux = Bits32 CInt Windows = Bits32 @@ -124,13 +130,14 @@ CInt Windows = Bits32 CSize : Platform -> Type CSize Linux = Bits64 CSize Windows = Bits64 -``` +---- -### 4. **Safe Evolution** +==== 4. *Safe Evolution* Prove that new ABI versions are backward-compatible: -```idris +[source,idris] +---- -- Compiler enforces compatibility abiUpgrade : ABI 1 -> ABI 2 abiUpgrade old = MkABI2 { @@ -139,71 +146,78 @@ abiUpgrade old = MkABI2 { -- Can add new fields new_features = defaults } -``` +---- -## Why Zig for FFI? +=== Why Zig for FFI? -### 1. **C ABI Compatibility** +==== 1. *C ABI Compatibility* Zig exports C-compatible functions naturally: -```zig +[source,zig] +---- export fn library_function(param: i32) i32 { return param * 2; } -``` +---- -### 2. **Memory Safety** +==== 2. *Memory Safety* Compile-time safety without runtime overhead: -```zig +[source,zig] +---- // Null check enforced at compile time const handle = init() orelse return error.InitFailed; defer free(handle); -``` +---- -### 3. **Cross-Compilation** +==== 3. *Cross-Compilation* Built-in cross-compilation to any platform: -```bash +[source,bash] +---- zig build -Dtarget=x86_64-linux zig build -Dtarget=aarch64-macos zig build -Dtarget=x86_64-windows -``` +---- -### 4. **Zero Dependencies** +==== 4. *Zero Dependencies* No runtime, no libc required (unless explicitly needed): -```zig +[source,zig] +---- // Minimal binary size pub const lib = @import("std"); // Only includes what you use -``` +---- -## Building +=== Building -### Build FFI Library +==== Build FFI Library -```bash +[source,bash] +---- cd ffi/zig zig build # Build debug zig build -Doptimize=ReleaseFast # Build optimized zig build test # Run tests -``` +---- -### Generate C Header from Idris2 ABI +==== Generate C Header from Idris2 ABI -```bash +[source,bash] +---- cd src/abi idris2 --cg c-header Types.idr -o ../../generated/abi/smtlib.h -``` +---- -### Cross-Compile +==== Cross-Compile -```bash +[source,bash] +---- cd ffi/zig # Linux x86_64 @@ -214,13 +228,14 @@ zig build -Dtarget=aarch64-macos # Windows x86_64 zig build -Dtarget=x86_64-windows -``` +---- -## Usage +=== Usage -### From C +==== From C -```c +[source,c] +---- #include "smtlib.h" int main() { @@ -236,16 +251,19 @@ int main() { smtlib_free(handle); return 0; } -``` +---- Compile with: -```bash + +[source,bash] +---- gcc -o example example.c -lsmtlib -L./zig-out/lib -``` +---- -### From Idris2 +==== From Idris2 -```idris +[source,idris] +---- import SMTLib.ABI.Foreign main : IO () @@ -258,11 +276,12 @@ main = do free handle putStrLn "Success" -``` +---- -### From Rust +==== From Rust -```rust +[source,rust] +---- #[link(name = "smtlib")] extern "C" { fn smtlib_init() -> *mut std::ffi::c_void; @@ -281,11 +300,12 @@ fn main() { smtlib_free(handle); } } -``` +---- -### From Julia +==== From Julia -```julia +[source,julia] +---- const libsmtlib = "libsmtlib" function init() @@ -311,27 +331,30 @@ try finally cleanup(handle) end -``` +---- -## Testing +=== Testing -### Unit Tests (Zig) +==== Unit Tests (Zig) -```bash +[source,bash] +---- cd ffi/zig zig build test -``` +---- -### Integration Tests +==== Integration Tests -```bash +[source,bash] +---- cd ffi/zig zig build test-integration -``` +---- -### ABI Verification (Idris2) +==== ABI Verification (Idris2) -```idris +[source,idris] +---- -- Compile-time verification %runElab verifyABI @@ -341,44 +364,44 @@ main = do verifyLayoutsCorrect verifyAlignmentsCorrect putStrLn "ABI verification passed" -``` +---- -## Contributing +=== Contributing When modifying the ABI/FFI: -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/smtlib.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/smtlib.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License MPL-2.0 -## See Also +=== See Also -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/SMTLib.jl/AGENTS.adoc b/packages/SMTLib.jl/AGENTS.adoc new file mode 100644 index 000000000..12fe032f1 --- /dev/null +++ b/packages/SMTLib.jl/AGENTS.adoc @@ -0,0 +1,76 @@ +== Repository Guidelines + +=== Project Structure & Module Organization + +* `+src/SMTLib.jl+` contains the main `+SMTLib+` module and public API. +* `+test/runtests.jl+` holds the test suite driven by Julia’s `+Test+` +stdlib. +* `+Project.toml+` defines package metadata and dependencies. +* `+README.md+` documents features, usage, and solver prerequisites. + +=== Build, Test, and Development Commands + +* `+julia --project=. -e 'using Pkg; Pkg.instantiate()'+` installs +dependencies for this project environment. +* `+julia --project=. -e 'using Pkg; Pkg.precompile()'+` precompiles for +faster local runs. +* `+julia --project=. -e 'using Pkg; Pkg.test()'+` runs the test suite. + +This package is pure Julia, so there is no separate build step beyond +precompilation. + +=== User Options & Configuration + +* Prefer `+find_solver(:z3)+` or `+find_solver(:cvc5)+` when you need a +specific backend. +* `+SMTContext+` accepts `+solver+`, `+logic+`, and `+timeout_ms+` +(milliseconds). +* `+check_sat(ctx; get_model=false)+` skips model parsing when you only +need status. +* The `+@smt+` macro mirrors `+SMTContext+` options: +`+@smt solver=:z3 logic=:QF_LRA timeout=10000 begin ... end+`. + +=== Coding Style & Naming Conventions + +* Follow Julia conventions: 4-space indentation, CamelCase for types +(`+SMTContext+`), lowercase with underscores for functions +(`+available_solvers+`), and `+!+` suffix for mutating functions +(`+reset!+`, `+assert!+`). +* Keep public API exported from `+src/SMTLib.jl+` and add docstrings for +new public functions. +* Prefer explicit types for public structs and use `+Symbol+` for SMT +identifiers. + +=== Testing Guidelines + +* Tests live in `+test/runtests.jl+` and use `+Test.@testset+` blocks. +* Add new tests near related functionality and keep them deterministic. +* Solver-dependent tests should gracefully skip when no SMT solver is +installed. + +=== CI & Solver Detection + +* CI should install at least one solver and ensure it is on `+PATH+` +(e.g., `+apt-get install z3+` on Ubuntu runners). +* Expect solver-backed tests to skip or return `+:unknown+` if no solver +is detected; document this in CI logs or PR notes. +* For a solver matrix, run separate CI jobs with only one solver on +`+PATH+` to validate backend-specific behavior. +* If adding a new solver, extend `+available_solvers()+` and keep +`+README.md+` and this guide in sync. + +=== Commit & Pull Request Guidelines + +* Current history is minimal; use clear, imperative commit subjects +(e.g., "`Add model parsing for bitvectors`"). +* PRs should describe the change, list commands run (e.g., +`+Pkg.test()+`), and note solver prerequisites when relevant. +* If behavior changes are user-visible, update `+README.md+` examples or +API descriptions. + +=== Solver Prerequisites + +* At least one SMT solver (Z3, CVC5, Yices, or MathSAT) must be +installed to run solver-backed tests and examples. +* If adding solver-specific features, document them in `+README.md+` and +guard for missing executables. diff --git a/packages/SMTLib.jl/AGENTS.md b/packages/SMTLib.jl/AGENTS.md deleted file mode 100644 index 0397f7daa..000000000 --- a/packages/SMTLib.jl/AGENTS.md +++ /dev/null @@ -1,45 +0,0 @@ -# Repository Guidelines - -## Project Structure & Module Organization -- `src/SMTLib.jl` contains the main `SMTLib` module and public API. -- `test/runtests.jl` holds the test suite driven by Julia’s `Test` stdlib. -- `Project.toml` defines package metadata and dependencies. -- `README.md` documents features, usage, and solver prerequisites. - -## Build, Test, and Development Commands -- `julia --project=. -e 'using Pkg; Pkg.instantiate()'` installs dependencies for this project environment. -- `julia --project=. -e 'using Pkg; Pkg.precompile()'` precompiles for faster local runs. -- `julia --project=. -e 'using Pkg; Pkg.test()'` runs the test suite. - -This package is pure Julia, so there is no separate build step beyond precompilation. - -## User Options & Configuration -- Prefer `find_solver(:z3)` or `find_solver(:cvc5)` when you need a specific backend. -- `SMTContext` accepts `solver`, `logic`, and `timeout_ms` (milliseconds). -- `check_sat(ctx; get_model=false)` skips model parsing when you only need status. -- The `@smt` macro mirrors `SMTContext` options: `@smt solver=:z3 logic=:QF_LRA timeout=10000 begin ... end`. - -## Coding Style & Naming Conventions -- Follow Julia conventions: 4-space indentation, CamelCase for types (`SMTContext`), lowercase with underscores for functions (`available_solvers`), and `!` suffix for mutating functions (`reset!`, `assert!`). -- Keep public API exported from `src/SMTLib.jl` and add docstrings for new public functions. -- Prefer explicit types for public structs and use `Symbol` for SMT identifiers. - -## Testing Guidelines -- Tests live in `test/runtests.jl` and use `Test.@testset` blocks. -- Add new tests near related functionality and keep them deterministic. -- Solver-dependent tests should gracefully skip when no SMT solver is installed. - -## CI & Solver Detection -- CI should install at least one solver and ensure it is on `PATH` (e.g., `apt-get install z3` on Ubuntu runners). -- Expect solver-backed tests to skip or return `:unknown` if no solver is detected; document this in CI logs or PR notes. -- For a solver matrix, run separate CI jobs with only one solver on `PATH` to validate backend-specific behavior. -- If adding a new solver, extend `available_solvers()` and keep `README.md` and this guide in sync. - -## Commit & Pull Request Guidelines -- Current history is minimal; use clear, imperative commit subjects (e.g., "Add model parsing for bitvectors"). -- PRs should describe the change, list commands run (e.g., `Pkg.test()`), and note solver prerequisites when relevant. -- If behavior changes are user-visible, update `README.md` examples or API descriptions. - -## Solver Prerequisites -- At least one SMT solver (Z3, CVC5, Yices, or MathSAT) must be installed to run solver-backed tests and examples. -- If adding solver-specific features, document them in `README.md` and guard for missing executables. diff --git a/packages/SMTLib.jl/CODE_OF_CONDUCT.adoc b/packages/SMTLib.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..7b21b02d2 --- /dev/null +++ b/packages/SMTLib.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,340 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +SMTLib.jl a harassment-free experience for everyone, regardless of age, +body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |jonathan.jewell@open.ac.uk |Detailed reports, sensitive +matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *72 hours* +. The maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* jonathan.jewell@open.ac.uk with subject line "`Appeal: +[Original Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainers member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/SMTLib.jl/discussions[Discussion] (for +general questions) +* Email jonathan.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/SMTLib.jl/CODE_OF_CONDUCT.md b/packages/SMTLib.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 3d9a90d78..000000000 --- a/packages/SMTLib.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,308 +0,0 @@ -# Code of Conduct - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in SMTLib.jl a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | jonathan.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **72 hours** -2. The maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** jonathan.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/SMTLib.jl/discussions) (for general questions) -- Email jonathan.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/packages/SMTLib.jl/CONTRIBUTING.adoc b/packages/SMTLib.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..e1033dc22 --- /dev/null +++ b/packages/SMTLib.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/SMTLib.jl.git cd SMTLib.jl + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create SMTLib.jl-dev toolbox enter SMTLib.jl-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +SMTLib.jl/ ├── 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/SMTLib.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/SMTLib.jl/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/SMTLib.jl/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/SMTLib.jl/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/packages/SMTLib.jl/CONTRIBUTING.md b/packages/SMTLib.jl/CONTRIBUTING.md deleted file mode 100644 index 9a97fef3e..000000000 --- a/packages/SMTLib.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/SMTLib.jl.git -cd SMTLib.jl - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create SMTLib.jl-dev -toolbox enter SMTLib.jl-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -SMTLib.jl/ -├── 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/SMTLib.jl/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/SMTLib.jl/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/SMTLib.jl/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/SMTLib.jl/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/packages/SMTLib.jl/SECURITY.adoc b/packages/SMTLib.jl/SECURITY.adoc new file mode 100644 index 000000000..710ff85e6 --- /dev/null +++ b/packages/SMTLib.jl/SECURITY.adoc @@ -0,0 +1,430 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/SMTLib.jl/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |jonathan.jewell@open.ac.uk +|=== + +.... + +> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. + +--- + +## What to Include + +A good vulnerability report helps us understand and reproduce the issue quickly. + +### Required Information + +- **Description**: Clear explanation of the vulnerability +- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) +- **Affected versions**: Which versions/commits are affected +- **Reproduction steps**: Detailed steps to reproduce the issue + +### Helpful Additional Information + +- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability +- **Attack scenario**: Realistic attack scenario showing exploitability +- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) +- **CWE ID**: Common Weakness Enumeration identifier if known +- **Suggested fix**: If you have ideas for remediation +- **References**: Links to related vulnerabilities, research, or advisories + +### Example Report Structure + +```markdown +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +.... + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/SMTLib.jl+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/SMTLib.jl/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using SMTLib.jl, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://github.com/hyperpolymath/SMTLib.jl/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/SMTLib.jl/security/advisories/new[Report +via GitHub] or jonathan.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/SMTLib.jl/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep SMTLib.jl and its users safe._ 🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/packages/SMTLib.jl/SECURITY.md b/packages/SMTLib.jl/SECURITY.md deleted file mode 100644 index cca52af65..000000000 --- a/packages/SMTLib.jl/SECURITY.md +++ /dev/null @@ -1,376 +0,0 @@ -# Security Policy - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/SMTLib.jl/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | jonathan.jewell@open.ac.uk | -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/SMTLib.jl`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/SMTLib.jl/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using SMTLib.jl, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Security Advisories](https://github.com/hyperpolymath/SMTLib.jl/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/SMTLib.jl/security/advisories/new) or jonathan.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/SMTLib.jl/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep SMTLib.jl and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/packages/SMTLib.jl/SONNET-TASKS.adoc b/packages/SMTLib.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..131a7ff6e --- /dev/null +++ b/packages/SMTLib.jl/SONNET-TASKS.adoc @@ -0,0 +1,764 @@ +== SONNET-TASKS: SMTLib.jl + +*Date:* 2026-02-12 *Auditor:* Claude Opus 4.6 *Honest Completion:* ~55% + +The Julia source (`+src/SMTLib.jl+`) is a real, functional single-file +library with working solver discovery, SMT-LIB2 generation, model +parsing, and a convenience macro. The tests are meaningful and would +pass given an installed solver. + +However: 4 exported symbols have no implementation (`+push!+`, `+pop!+`, +`+get_model+`, `+from_smtlib+`), the docs reference features that do not +exist (`+solver_options+`, named assertions, `+unsat_core+`), the +ABI/FFI layer is unmodified RSR template boilerplate with +`+{{PROJECT}}+` placeholders everywhere, every RSR community file still +has `+{{PLACEHOLDER}}+` tokens, there is no `+.machine_readable/+` +directory, no `+.editorconfig+`, no `+.gitignore+`, no +`+.bot_directives/+`, the CodeQL workflow scans for Rust (not Julia), +the examples directory contains ReScript and Deno files that have +nothing to do with SMT solving, and the ROADMAP is the raw template with +"`YOUR Template Repo.`" + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Do NOT add features that are not already partially started. Fix what +exists. +. Every change MUST be verified by a runnable command or test. +. Do NOT refactor working code. Only fix broken, missing, or misleading +things. +. Read the full file before editing – many issues are interconnected. +. Run +`+julia --project=/var$REPOS_DIR/SMTLib.jl -e 'using Pkg; Pkg.test()'+` +after every task to confirm nothing is broken. + +''''' + +=== TASK 1: Implement the 4 Exported-But-Missing Functions + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl+` (lines 36, 37, 39) + +*Problem:* The module exports `+push!+`, `+pop!+`, `+get_model+`, and +`+from_smtlib+` on lines 36 and 39, but none of these functions are +defined anywhere in the source: + +* `+push!+` and `+pop!+` for `+SMTContext+` – documented in README (line +77-80), referenced in examples (docs/src/examples.md lines 31-37), in +AGENTS.md (line 19). The `+SMTContext+` struct has no stack field to +support push/pop. +* `+get_model+` – exported on line 36, referenced in API docs +(docs/src/api.md line 26), but never defined. `+check_sat+` already +returns models inline via `+SMTResult.model+`. +* `+from_smtlib+` – exported on line 39, referenced in API docs +(docs/src/api.md line 40), but never defined. Would be the inverse of +`+to_smtlib+`. + +*What to do:* 1. Add a `+stack_depth::Int+` field to `+SMTContext+` +(line 96-102) initialized to 0. 2. Add +`+declarations_stack::Vector{Int}+` and +`+assertions_stack::Vector{Int}+` to track push points. 3. Implement +`+Base.push!(ctx::SMTContext)+` that records current lengths and emits +`+(push 1)+` to the script. 4. Implement `+Base.pop!(ctx::SMTContext)+` +that truncates back to last push point and emits `+(pop 1)+`. 5. +Implement `+get_model(result::SMTResult)+` as a convenience alias +returning `+result.model+`. 6. Implement `+from_smtlib(s::String)+` to +parse an SMT-LIB2 expression string back into a Julia `+Expr+`. At +minimum, handle: - `+(+ x y)+` -> `+:(x + y)+` - `+(= x y)+` -> +`+:(x == y)+` - `+(and ...)+` / `+(or ...)+` / `+(not ...)+` - Integer +and boolean literals. 7. Update `+build_script+` (line 430) to emit +push/pop commands from the stack. + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using SMTLib + +# Test push!/pop! exist and work structurally +ctx = SMTContext(logic=:QF_LIA) +declare(ctx, :x, Int) +assert!(ctx, :(x > 5)) +push!(ctx) +assert!(ctx, :(x < 3)) +pop!(ctx) +@assert length(ctx.assertions) == 1 "pop! should restore assertion count" + +# Test get_model exists +r = SMTResult(:sat, Dict(:x => 42), Symbol[], Dict{String,Any}(), "") +@assert get_model(r) == Dict(:x => 42) "get_model should return model dict" + +# Test from_smtlib exists and round-trips basics +@assert from_smtlib("(+ x y)") == :(x + y) "from_smtlib basic arithmetic" +@assert from_smtlib("true") == true "from_smtlib boolean" + +println("TASK 1 PASSED") +' +---- + +''''' + +=== TASK 2: Remove Bogus Examples Directory + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/examples/SafeDOMExample.res+` - +`+/var$REPOS_DIR/SMTLib.jl/examples/web-project-deno.json+` + +*Problem:* The `+examples/+` directory contains a ReScript DOM-mounting +example and a Deno project config. Neither has anything to do with SMT +solving. They are leftover RSR template files. The SPDX header in +`+SafeDOMExample.res+` is `+AGPL-3.0-or-later+` which violates the +license policy (should be MPL-2.0 or at least not AGPL). + +*What to do:* 1. Delete `+examples/SafeDOMExample.res+`. 2. Delete +`+examples/web-project-deno.json+`. 3. Create `+examples/basic_sat.jl+` +with a self-contained example that checks satisfiability (can run +without a solver by showing the generated SMT-LIB2 script output). 4. +Create `+examples/incremental.jl+` showing push/pop usage (after TASK +1). 5. Add SPDX header `+# SPDX-License-Identifier: CC-BY-SA-4.0+` to +all new files. + +*Verification:* + +[source,bash] +---- +# Bogus files gone +test ! -f /var$REPOS_DIR/SMTLib.jl/examples/SafeDOMExample.res && echo "PASS: res removed" +test ! -f /var$REPOS_DIR/SMTLib.jl/examples/web-project-deno.json && echo "PASS: deno removed" + +# New examples exist and are valid Julia +julia --project=/var$REPOS_DIR/SMTLib.jl -e 'include("/var$REPOS_DIR/SMTLib.jl/examples/basic_sat.jl")' && echo "PASS: basic_sat runs" +---- + +''''' + +=== TASK 3: Fix Unsat Core and Named Assertions (Documented but Nonexistent) + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl+` (function +`+assert!+` at line 400, `+build_script+` at line 430, `+parse_result+` +at line 503) - `+/var$REPOS_DIR/SMTLib.jl/docs/src/examples.md+` (lines +86-97) + +*Problem:* `+docs/src/examples.md+` lines 86-97 show +`+assert!(ctx, expr, name=:c1)+` with named assertions and +`+check_sat(ctx, unsat_core=true)+` returning `+result.unsat_core+`. The +`+SMTResult+` struct has an `+unsat_core+` field (line 78), but: - +`+assert!+` does not accept a `+name+` keyword argument. - +`+build_script+` never emits `+(set-option :produce-unsat-cores true)+`. +- `+build_script+` never emits `+(get-unsat-core)+`. - `+parse_result+` +never parses unsat core output. - `+check_sat+` does not accept an +`+unsat_core+` keyword. + +*What to do:* 1. Extend `+assert!(ctx, expr; name=nothing)+` to accept +an optional name. When `+name+` is provided, emit +`+(assert (! expr :named name))+`. 2. Add `+unsat_core_requested::Bool+` +field to `+SMTContext+`, defaulting to `+false+`. 3. Extend +`+check_sat(ctx; get_model=true, unsat_core=false)+` to accept the +`+unsat_core+` keyword. 4. Update `+build_script+` to emit +`+(set-option :produce-unsat-cores true)+` and `+(get-unsat-core)+` when +`+unsat_core=true+`. 5. Update `+parse_result+` to parse unsat core from +solver output (lines matching parenthesized symbol lists after +"`unsat`"). + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using SMTLib + +ctx = SMTContext(logic=:QF_LIA) +declare(ctx, :x, Int) + +# Named assertions should work +assert!(ctx, :(x > 10), name=:c1) +assert!(ctx, :(x < 5), name=:c2) + +# Verify the SMT-LIB script contains named assertions +script = SMTLib.build_script(ctx, true) +@assert occursin(":named c1", script) "Named assertion c1 missing from script" +@assert occursin(":named c2", script) "Named assertion c2 missing from script" + +println("TASK 3 PASSED") +' +---- + +''''' + +=== TASK 4: Fix solver_options References in Documentation + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/docs/src/solvers.md+` (lines +137-146, 191) + +*Problem:* The solvers documentation references +`+ctx.solver_options[:timeout]+`, `+ctx.solver_options[:random_seed]+`, +`+ctx.solver_options[:finite_model_find]+`, and +`+ctx.solver_options[:max_memory]+`. The `+SMTContext+` struct has no +`+solver_options+` field. This code will throw `+ErrorException+` if +anyone runs it. + +*What to do:* Either: (a) Add a `+solver_options::Dict{Symbol, Any}+` +field to `+SMTContext+` and wire it into `+build_script+` to emit +`+(set-option ...)+` commands, OR (b) Remove the solver_options examples +from `+docs/src/solvers.md+` and replace with documentation of existing +features (timeout_ms constructor arg). + +Option (a) is preferred since the feature is useful. + +If implementing (a): 1. Add `+solver_options::Dict{Symbol, Any}+` to +`+SMTContext+` struct (line 96-102), initialized to +`+Dict{Symbol, Any}()+`. 2. Update the constructor (line 104-112). 3. In +`+build_script+`, emit solver options as `+(set-option :key value)+` +lines. + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using SMTLib + +ctx = SMTContext(logic=:QF_LIA) + +# solver_options should be accessible +ctx.solver_options[:random_seed] = 42 + +script = SMTLib.build_script(ctx, false) +@assert occursin("random_seed", script) || occursin("random-seed", script) "solver option not in script" + +println("TASK 4 PASSED") +' +---- + +''''' + +=== TASK 5: Replace All \{\{PLACEHOLDER}} Tokens in RSR Files + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/SECURITY.md+` (\{\{OWNER}}, +\{\{REPO}}, \{\{PROJECT_NAME}}, etc.) - +`+/var$REPOS_DIR/SMTLib.jl/CONTRIBUTING.md+` (\{\{FORGE}}, \{\{OWNER}}, +\{\{REPO}}) - `+/var$REPOS_DIR/SMTLib.jl/CODE_OF_CONDUCT.md+` +(\{\{OWNER}}, \{\{REPO}}, etc.) - +`+/var$REPOS_DIR/SMTLib.jl/docs/CITATIONS.adoc+` (wrong project name, +AGPL license ref) - `+/var$REPOS_DIR/SMTLib.jl/ROADMAP.adoc+` (says +"`YOUR Template Repo Roadmap`") - +`+/var$REPOS_DIR/SMTLib.jl/ABI-FFI-README.md+` (line 1: "`delete this +line`") + +*Problem:* Dozens of `+{{OWNER}}+`, `+{{REPO}}+`, `+{{FORGE}}+`, +`+{{PROJECT_NAME}}+`, `+{{SECURITY_EMAIL}}+`, `+{{PGP_FINGERPRINT}}+`, +etc. remain unreplaced. `+ROADMAP.adoc+` line 2 says "`YOUR Template +Repo Roadmap.`" `+CITATIONS.adoc+` cites "`rsr-template-repo`" with AGPL +license. The ABI-FFI-README.md line 1 still says "`delete this line.`" + +*What to do:* 1. In SECURITY.md: - `+{{PROJECT_NAME}}+` -> `+SMTLib.jl+` +- `+{{OWNER}}+` -> `+hyperpolymath+` - `+{{REPO}}+` -> `+SMTLib.jl+` - +`+{{SECURITY_EMAIL}}+` -> `+jonathan.jewell@open.ac.uk+` - Remove the +template instruction comment block (lines 3-19). - Remove PGP sections +if not applicable. 2. In CONTRIBUTING.md: - `+{{FORGE}}+` -> +`+github.com+` - `+{{OWNER}}+` -> `+hyperpolymath+` - `+{{REPO}}+` -> +`+SMTLib.jl+` 3. In CODE_OF_CONDUCT.md: - Same replacements as above. - +Remove template instruction block. 4. In CITATIONS.adoc: - Replace +`+rsr-template-repo+` with `+SMTLib.jl+`. - Replace +`+AGPL-3.0-or-later+` with `+MPL-2.0+`. - Replace author +`+Polymath, Hyper+` with `+Jewell, Jonathan D.A.+` 5. In ROADMAP.adoc: - +Replace "`YOUR Template Repo`" with "`SMTLib.jl`". - Add real milestones +reflecting the actual state of the project. 6. In ABI-FFI-README.md: - +Delete line 1 (`+{{~ Aditionally delete this line...}}+`). - Replace +`+{{PROJECT}}+` with `+SMTLib+` and `+{{project}}+` with `+smtlib+`. - +Replace `+{{LICENSE}}+` with `+MPL-2.0+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl +grep -rn '{{' --include='*.md' --include='*.adoc' . | grep -v '.git/' | grep -v 'contractiles/' | grep -v 'ABI-FFI' | head -5 +# Should return NO matches (excluding contractile templates which are allowed) +echo "---" +grep -c '{{PROJECT}}' ABI-FFI-README.md +# Should return 0 +echo "---" +head -1 ROADMAP.adoc | grep -v 'YOUR' +# Should not contain "YOUR" +echo "TASK 5 PASSED (if all above are empty/0)" +---- + +''''' + +=== TASK 6: Replace All \{\{PROJECT}} Placeholders in ABI/FFI Files + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/src/abi/Types.idr+` (lines 6, 11) +- `+/var$REPOS_DIR/SMTLib.jl/src/abi/Layout.idr+` (lines 8, 10) - +`+/var$REPOS_DIR/SMTLib.jl/src/abi/Foreign.idr+` (lines 9, 11, 12, 23, +35, 49, etc.) - `+/var$REPOS_DIR/SMTLib.jl/ffi/zig/build.zig+` (lines 1, +12, 23, 35, 36, 82) - `+/var$REPOS_DIR/SMTLib.jl/ffi/zig/src/main.zig+` +(lines 1, 12, 54, 73, 89, etc.) - +`+/var$REPOS_DIR/SMTLib.jl/ffi/zig/test/integration_test.zig+` (lines 1, +10-17, etc.) + +*Problem:* Every ABI and FFI file is the raw RSR template with +`+{{PROJECT}}+` and `+{{project}}+` placeholders. None of these files +will compile. Additionally, the SPDX headers in the Zig files say +`+AGPL-3.0-or-later+` instead of `+MPL-2.0+`. + +*What to do:* 1. In all `+.idr+` files: replace `+{{PROJECT}}+` with +`+SMTLib+`. 2. In all `+.zig+` files: replace `+{{PROJECT}}+` with +`+SMTLib+` and `+{{project}}+` with `+smtlib+`. 3. In all `+.zig+` +files: change SPDX from `+AGPL-3.0-or-later+` to `+MPL-2.0+`. 4. +Consider whether the ABI/FFI layer makes sense for a pure-Julia SMT +interface. If it does not, add a note to `+ABI-FFI-README.md+` +explaining that the ABI/FFI layer is reserved for future native solver +bindings, or remove it entirely and document why in the commit message. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl +grep -rn '{{PROJECT}}\|{{project}}' src/abi/ ffi/ | head -5 +# Should return 0 matches +grep -rn 'AGPL' src/abi/ ffi/ | head -5 +# Should return 0 matches +echo "TASK 6 PASSED (if both empty)" +---- + +''''' + +=== TASK 7: Fix CodeQL Workflow (Scanning for Wrong Language) + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/.github/workflows/codeql.yml+` + +*Problem:* The CodeQL workflow (line 24-25) scans for `+language: rust+` +with `+build-mode: none+`. This is a Julia repository. CodeQL does not +have a Julia language scanner, so this workflow will either fail +silently or produce no useful results. The correct approach is to scan +for `+actions+` (workflow security) or remove the workflow if no +supported language is present. + +*What to do:* 1. Change the matrix to `+language: actions+` (CodeQL can +scan GitHub Actions workflows for injection vulnerabilities, which IS +useful). 2. Remove `+build-mode: none+` (not applicable to actions +scanning). 3. Update the checkout action SHA to match the standard +pinned version from CLAUDE.md: +`+actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5+` (v4). 4. +Update CodeQL action SHA to: +`+github/codeql-action@6624720a57d4c312633c7b953db2f2da5bcb4c3a+` (v3). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl +grep 'language:' .github/workflows/codeql.yml +# Should show "actions", not "rust" +grep 'build-mode' .github/workflows/codeql.yml +# Should return nothing +echo "TASK 7 PASSED (if actions and no build-mode)" +---- + +''''' + +=== TASK 8: Fix Scorecard Workflow (Unpinned Actions) + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/.github/workflows/scorecard.yml+` + +*Problem:* Lines 18, 22, 29 use unpinned action tags (`+@v4+`, +`+@v2.3.1+`, `+@v3+`) instead of SHA-pinned versions. This fails OpenSSF +Scorecard "`Pinned-Dependencies`" check and is a supply-chain security +risk. + +*What to do:* 1. Pin `+actions/checkout@v4+` to SHA +`+34e114876b0b11c390a56381ad16ebd13914f8d5+`. 2. Pin +`+ossf/scorecard-action@v2.4.0+` to SHA +`+62b2cac7ed8198b15735ed49ab1e5cf35480ba46+`. 3. Pin +`+github/codeql-action/upload-sarif@v3+` to SHA +`+6624720a57d4c312633c7b953db2f2da5bcb4c3a+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl +grep -E '@v[0-9]' .github/workflows/scorecard.yml +# Should return nothing (all SHA-pinned) +echo "TASK 8 PASSED (if empty)" +---- + +''''' + +=== TASK 9: Add Missing RSR Infrastructure Files + +*Files to create:* - `+/var$REPOS_DIR/SMTLib.jl/.editorconfig+` - +`+/var$REPOS_DIR/SMTLib.jl/.gitignore+` - +`+/var$REPOS_DIR/SMTLib.jl/.machine_readable/STATE.scm+` - +`+/var$REPOS_DIR/SMTLib.jl/.machine_readable/ECOSYSTEM.scm+` - +`+/var$REPOS_DIR/SMTLib.jl/.machine_readable/META.scm+` + +*Problem:* The repo is missing `+.editorconfig+`, `+.gitignore+`, and +the entire `+.machine_readable/+` directory with STATE.scm, +ECOSYSTEM.scm, and META.scm. The AI.a2ml file references +`+.machines_readable/6scm/STATE.scm+` (wrong path, wrong directory +name). There is no `+.bot_directives/+` directory either. + +*What to do:* 1. Create `+.editorconfig+` with Julia-appropriate +settings (4-space indent, UTF-8, LF line endings, trim trailing +whitespace). 2. Create `+.gitignore+` for Julia packages: - +`+/Manifest.toml+` (already tracked but should be in .gitignore for +libraries) - `+*.jl.cov+`, `+*.jl.*.cov+`, `+*.jl.mem+` - +`+/docs/build/+` - `+/generated/+` - `+*.smt2+` (temp solver files) 3. +Create `+.machine_readable/STATE.scm+` reflecting actual project state: +phase=implementation, maturity=alpha, ~55% completion. 4. Create +`+.machine_readable/ECOSYSTEM.scm+` with relationship to Axiom.jl (as +noted in README.adoc line 85). 5. Create `+.machine_readable/META.scm+` +with architecture decisions and license info. 6. Fix `+AI.a2ml+` to +reference `+.machine_readable/+` (not `+.machines_readable/6scm/+`). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl +test -f .editorconfig && echo "PASS: .editorconfig exists" +test -f .gitignore && echo "PASS: .gitignore exists" +test -f .machine_readable/STATE.scm && echo "PASS: STATE.scm exists" +test -f .machine_readable/ECOSYSTEM.scm && echo "PASS: ECOSYSTEM.scm exists" +test -f .machine_readable/META.scm && echo "PASS: META.scm exists" +grep -c 'machines_readable' AI.a2ml +# Should return 0 (fixed to machine_readable) +echo "TASK 9 PASSED" +---- + +''''' + +=== TASK 10: Fix Test Coverage Gaps + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/test/runtests.jl+` + +*Problem:* The test file has decent coverage of `+to_smtlib+`, type +mapping, and value parsing. But several functions have zero test +coverage: - `+prove()+` (line 689) – never tested. - +`+extract_variables()+` (line 711) – never tested. - `+is_operator()+` +(line 728) – never tested. - `+handle_let()+` (line 267) – never tested. +- `+handle_chained_comparison()+` (line 250) – never tested. - +`+build_script()+` (line 430) – never directly tested. - +`+build_solver_command()+` (line 484) – never tested. - `+@smt+` macro +(line 630) – never tested without a solver. - `+reset!()+` (line 411) – +never tested. - `+SMTContext+` constructor error path (line 108-109) – +never tested. + +Also, `+to_smtlib+` for `+&&+` and `+||+` (lines 227-232) uses +`+expr.head == :&&+` syntax which changed across Julia versions. The +tests for `+to_smtlib(:(x && y))+` may fail on Julia < 1.7 because the +AST representation changed. + +*What to do:* 1. Add a `+@testset "Script Generation"+` that calls +`+build_script+` directly and checks the output string contains +`+(set-logic ...)+`, `+(declare-const ...)+`, `+(assert ...)+`, and +`+(check-sat)+`. 2. Add a `+@testset "Solver Commands"+` that tests +`+build_solver_command+` for z3, cvc5, yices, and unknown solvers. 3. +Add a `+@testset "Variable Extraction"+` testing `+extract_variables+`. +4. Add a `+@testset "Operator Detection"+` testing `+is_operator+`. 5. +Add a `+@testset "Context Reset"+` testing `+reset!+`. 6. Add a +`+@testset "Chained Comparison"+` testing `+handle_chained_comparison+` +with expressions like `+:(1 < x < 10)+`. 7. Add a +`+@testset "Let Bindings"+` testing `+handle_let+`. 8. Add a +`+@testset "Macro Generation"+` that tests `+@smt+` structurally without +needing a solver (mock or check generated script). + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using Pkg; Pkg.test() +' 2>&1 | tail -5 +# Should show all tests passing with expanded coverage +---- + +''''' + +=== TASK 11: Fix the `+prove()+` Function Type Inference + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl+` (function +`+prove+` at line 689, `+extract_variables+` at line 711) + +*Problem:* The `+prove()+` function calls `+extract_variables()+` which +defaults every variable to `+Int+` (line 720: `+vars[expr] = Int+`). +This means: - `+prove(:(x > 0 && x < 10))+` declares `+x+` as Int but +also declares `+&&+` and `+>+` and `+<+` as Int variables (they pass +`+is_operator+` but the check is flawed). - Actually, `+is_operator+` +checks for `+Symbol("+")+` etc., but operators in Julia ASTs are stored +as `+:++`, `+:>+`, `+:&&+` – the `+Symbol("...")+` constructor creates +them. However, `+expr.args[1]+` in a `+:call+` Expr is the operator +symbol, so `+_extract_vars!+` recurses into `+expr.args+` including the +operator. It would declare `+:++` as a variable unless `+is_operator+` +catches it. - The `+is_operator+` list is incomplete: missing +`+:implies+`, `+:iff+`, `+:xor+`, `+:forall+`, `+:exists+`, `+:select+`, +`+:store+`, all `+:bv*+` operators, math functions (`+:sqrt+`, `+:exp+`, +`+:log+`, `+:sin+`, `+:cos+`, `+:tan+`, `+:^+`). - The comment on line +713 says "`Simple heuristic - would need type inference in practice`" +which is honest, but the function is exported and documented. + +*What to do:* 1. Expand `+is_operator+` to include all operators from +`+julia_op_to_smt+`’s keys (lines 287-351). Extract the keys from the +Dict and check membership. Better yet, define the operator set once and +share it. 2. Add a `+type+` parameter to `+prove()+` so users can +specify variable types: +`+prove(expr; vars=Dict(:x => Int, :y => Float64))+`. 3. When `+vars+` +is provided, skip `+extract_variables+` and use the provided dict. 4. +Document the limitations of `+extract_variables+` in its docstring. + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using SMTLib + +# Test that operators are not extracted as variables +vars = SMTLib.extract_variables(:(x + y > 0)) +@assert !haskey(vars, :+) "Operator + should not be a variable" +@assert !haskey(vars, :>) "Operator > should not be a variable" +@assert haskey(vars, :x) "x should be extracted" +@assert haskey(vars, :y) "y should be extracted" +@assert !haskey(vars, 0) || true # literals should not be variables + +println("TASK 11 PASSED") +' +---- + +''''' + +=== TASK 12: Fix parse_model Regex (Misses Multi-line Models) + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl+` (function +`+parse_model+` at line 539, line 544) + +*Problem:* The model parser on line 544 uses a single-line regex: + +.... +r"\(define-fun\s+(\w+)\s+\(\)\s+\w+\s+(.+?)\)" +.... + +This fails for multi-line model output, which is the default format from +Z3 and CVC5. A typical Z3 model looks like: + +.... +(model + (define-fun x () Int + 5) + (define-fun y () Int + (- 3)) +) +.... + +The regex requires the entire `+define-fun+` to be on one line. It also +fails to match type names with spaces like `+(_ BitVec 32)+`. + +*What to do:* 1. Replace the single-line regex with a proper +S-expression parser that handles nested parentheses and multi-line +output. 2. At minimum, use `+s+` flag for dotall matching and handle the +multi-line case: +`+r"\(define-fun\s+(\w+)\s+\(\)\s+[\w\s\(\)_]+\s+(.+?)\)"s+`. 3. Better +approach: write a minimal S-expression tokenizer that finds balanced +`+(define-fun ...)+` blocks, then extracts name, type, and value. 4. +Handle type names like `+(_ BitVec 32)+` and `+(Array Int Int)+`. + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using SMTLib + +# Multi-line model output from Z3 +output = """sat +(model + (define-fun x () Int + 5) + (define-fun y () Int + (- 3)) +)""" + +model = SMTLib.parse_model(output) +@assert haskey(model, :x) "Should parse x from multi-line model" +@assert haskey(model, :y) "Should parse y from multi-line model" +@assert model[:x] == 5 "x should be 5" +@assert model[:y] == -3 "y should be -3" + +println("TASK 12 PASSED") +' +---- + +''''' + +=== TASK 13: Fix Timeout Detection in parse_result + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl+` (function +`+parse_result+` at line 503, line 519) + +*Problem:* Line 519 checks `+startswith(line, "timeout")+` but: - Z3 +does not output "`timeout`" – it outputs "`unknown`" with +`+(:reason-unknown timeout)+` in a separate get-info response, or just +outputs nothing/errors. - CVC5 outputs "`unknown`" on timeout, not +"`timeout`". - Yices outputs "`unknown`" on timeout. - No major solver +outputs a bare "`timeout`" string. + +The timeout detection is effectively dead code. Real timeout detection +requires checking the process exit code or using Julia’s +`+timedwait+`/`+Timer+`. + +*What to do:* 1. Use Julia’s `+Base.process_running+` and timeout +mechanism. Wrap the solver process in a `+Timer+` that kills it after +`+timeout_ms+`. 2. In `+run_solver+`, use `+open(cmd)+` with a timer +instead of `+read(ignorestatus(cmd))+`. 3. If the process is killed due +to timeout, set status to `+:timeout+`. 4. Remove the bogus +`+startswith(line, "timeout")+` check. 5. Also handle solver stderr +output (currently ignored) which may contain error messages. + +*Verification:* + +[source,julia] +---- +julia --project=/var$REPOS_DIR/SMTLib.jl -e ' +using SMTLib + +# Test that a very short timeout results in :timeout (if solver available) +solvers = available_solvers() +if !isempty(solvers) + ctx = SMTContext(solver=first(solvers), logic=:QF_NRA, timeout_ms=1) + declare(ctx, :x, Float64) + # Intentionally hard problem + for i in 1:100 + assert!(ctx, :(x * x * x + x > $i)) + end + result = check_sat(ctx) + @assert result.status in (:timeout, :unknown, :sat, :unsat) "Should handle timeout gracefully" + println("Solver timeout test: status = $(result.status)") +else + println("No solver available, skipping timeout test") +end + +# Test that parse_result handles empty output gracefully +r = SMTLib.parse_result("") +@assert r.status == :unknown "Empty output should be :unknown" + +println("TASK 13 PASSED") +' +---- + +''''' + +=== TASK 14: Add .gitignore and Remove Tracked Manifest.toml + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/Manifest.toml+` (currently +tracked) - `+/var$REPOS_DIR/SMTLib.jl/.gitignore+` (does not exist) + +*Problem:* `+Manifest.toml+` is tracked in git. For Julia libraries (not +applications), `+Manifest.toml+` should NOT be committed because it pins +exact dependency versions and Julia versions +(`+julia_version = "1.12.2"+` on line 3) that will break for users on +different Julia versions. The Julia community convention is clear: +libraries should `+.gitignore+` their `+Manifest.toml+`. + +*What to do:* 1. Create `+.gitignore+` with standard Julia entries: +`+/Manifest.toml *.jl.cov *.jl.*.cov *.jl.mem /docs/build/ /generated/ *.smt2+` +2. Remove `+Manifest.toml+` from git tracking: +`+git rm --cached Manifest.toml+`. 3. Ensure `+Manifest.toml+` remains +on disk (not deleted, just untracked). + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl +test -f .gitignore && echo "PASS: .gitignore exists" +grep 'Manifest.toml' .gitignore && echo "PASS: Manifest.toml in .gitignore" +git ls-files --error-unmatch Manifest.toml 2>/dev/null && echo "FAIL: still tracked" || echo "PASS: Manifest.toml untracked" +---- + +''''' + +=== TASK 15: Fix quality.yml TODO Scanner (Wrong File Extensions) + +*Files:* - `+/var$REPOS_DIR/SMTLib.jl/.github/workflows/quality.yml+` +(line 31) + +*Problem:* The quality workflow scans for TODOs in `+*.rs+`, `+*.res+`, +`+*.py+`, `+*.ex+` files. This is a Julia repository. It should scan +`+*.jl+` files. None of the scanned extensions exist in the repo. + +*What to do:* 1. Change line 31 to include `+*.jl+` instead of/in +addition to the current extensions: +`+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.jl" --include="*.idr" --include="*.zig" . | head -20 || echo "None found"+` + +*Verification:* + +[source,bash] +---- +grep 'include.*\.jl' /var$REPOS_DIR/SMTLib.jl/.github/workflows/quality.yml && echo "TASK 15 PASSED" +---- + +''''' + +=== FINAL VERIFICATION + +After completing all tasks, run this sequence: + +[source,bash] +---- +cd /var$REPOS_DIR/SMTLib.jl + +echo "=== 1. Julia tests pass ===" +julia --project=. -e 'using Pkg; Pkg.test()' 2>&1 | tail -10 + +echo "" +echo "=== 2. No remaining template placeholders (excluding contractiles) ===" +grep -rn '{{' --include='*.md' --include='*.adoc' --include='*.idr' --include='*.zig' . | grep -v '.git/' | grep -v 'contractiles/' | wc -l +# Expected: 0 + +echo "" +echo "=== 3. All exports have implementations ===" +julia --project=. -e ' +using SMTLib +for name in names(SMTLib) + sym = getfield(SMTLib, name) + println(" $name => $(typeof(sym))") +end +' + +echo "" +echo "=== 4. No AGPL references in source ===" +grep -rn 'AGPL' --include='*.jl' --include='*.idr' --include='*.zig' . | grep -v '.git/' | wc -l +# Expected: 0 + +echo "" +echo "=== 5. RSR infrastructure files exist ===" +for f in .editorconfig .gitignore .machine_readable/STATE.scm .machine_readable/ECOSYSTEM.scm .machine_readable/META.scm; do + test -f "$f" && echo " OK: $f" || echo " MISSING: $f" +done + +echo "" +echo "=== 6. CodeQL scans correct language ===" +grep 'language:' .github/workflows/codeql.yml + +echo "" +echo "=== 7. All workflow actions SHA-pinned ===" +grep -E 'uses:.*@v[0-9]' .github/workflows/*.yml | wc -l +# Expected: 0 + +echo "" +echo "=== 8. Examples are Julia files ===" +ls examples/*.jl 2>/dev/null && echo "OK" || echo "MISSING Julia examples" +ls examples/*.res 2>/dev/null && echo "FAIL: ReScript still present" || echo "OK: no ReScript" + +echo "" +echo "=== 9. Manifest.toml not tracked ===" +git ls-files --error-unmatch Manifest.toml 2>/dev/null && echo "FAIL" || echo "OK" + +echo "" +echo "=== FINAL VERDICT ===" +echo "If all above show OK/0/expected values, all tasks are complete." +---- diff --git a/packages/SMTLib.jl/SONNET-TASKS.md b/packages/SMTLib.jl/SONNET-TASKS.md deleted file mode 100644 index 9d509d455..000000000 --- a/packages/SMTLib.jl/SONNET-TASKS.md +++ /dev/null @@ -1,758 +0,0 @@ -# SONNET-TASKS: SMTLib.jl - -**Date:** 2026-02-12 -**Auditor:** Claude Opus 4.6 -**Honest Completion:** ~55% - -The Julia source (`src/SMTLib.jl`) is a real, functional single-file library with -working solver discovery, SMT-LIB2 generation, model parsing, and a convenience -macro. The tests are meaningful and would pass given an installed solver. - -However: 4 exported symbols have no implementation (`push!`, `pop!`, `get_model`, -`from_smtlib`), the docs reference features that do not exist (`solver_options`, -named assertions, `unsat_core`), the ABI/FFI layer is unmodified RSR template -boilerplate with `{{PROJECT}}` placeholders everywhere, every RSR community file -still has `{{PLACEHOLDER}}` tokens, there is no `.machine_readable/` directory, -no `.editorconfig`, no `.gitignore`, no `.bot_directives/`, the CodeQL workflow -scans for Rust (not Julia), the examples directory contains ReScript and Deno -files that have nothing to do with SMT solving, and the ROADMAP is the raw -template with "YOUR Template Repo." - ---- - -## GROUND RULES FOR SONNET - -1. Do NOT add features that are not already partially started. Fix what exists. -2. Every change MUST be verified by a runnable command or test. -3. Do NOT refactor working code. Only fix broken, missing, or misleading things. -4. Read the full file before editing -- many issues are interconnected. -5. Run `julia --project=/var$REPOS_DIR/SMTLib.jl -e 'using Pkg; Pkg.test()'` after every task to confirm nothing is broken. - ---- - -## TASK 1: Implement the 4 Exported-But-Missing Functions - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl` (lines 36, 37, 39) - -**Problem:** -The module exports `push!`, `pop!`, `get_model`, and `from_smtlib` on lines -36 and 39, but none of these functions are defined anywhere in the source: - -- `push!` and `pop!` for `SMTContext` -- documented in README (line 77-80), - referenced in examples (docs/src/examples.md lines 31-37), in AGENTS.md - (line 19). The `SMTContext` struct has no stack field to support push/pop. -- `get_model` -- exported on line 36, referenced in API docs - (docs/src/api.md line 26), but never defined. `check_sat` already returns - models inline via `SMTResult.model`. -- `from_smtlib` -- exported on line 39, referenced in API docs - (docs/src/api.md line 40), but never defined. Would be the inverse of - `to_smtlib`. - -**What to do:** -1. Add a `stack_depth::Int` field to `SMTContext` (line 96-102) initialized to 0. -2. Add `declarations_stack::Vector{Int}` and `assertions_stack::Vector{Int}` to - track push points. -3. Implement `Base.push!(ctx::SMTContext)` that records current lengths and - emits `(push 1)` to the script. -4. Implement `Base.pop!(ctx::SMTContext)` that truncates back to last push point - and emits `(pop 1)`. -5. Implement `get_model(result::SMTResult)` as a convenience alias returning - `result.model`. -6. Implement `from_smtlib(s::String)` to parse an SMT-LIB2 expression string - back into a Julia `Expr`. At minimum, handle: - - `(+ x y)` -> `:(x + y)` - - `(= x y)` -> `:(x == y)` - - `(and ...)` / `(or ...)` / `(not ...)` - - Integer and boolean literals. -7. Update `build_script` (line 430) to emit push/pop commands from the stack. - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using SMTLib - -# Test push!/pop! exist and work structurally -ctx = SMTContext(logic=:QF_LIA) -declare(ctx, :x, Int) -assert!(ctx, :(x > 5)) -push!(ctx) -assert!(ctx, :(x < 3)) -pop!(ctx) -@assert length(ctx.assertions) == 1 "pop! should restore assertion count" - -# Test get_model exists -r = SMTResult(:sat, Dict(:x => 42), Symbol[], Dict{String,Any}(), "") -@assert get_model(r) == Dict(:x => 42) "get_model should return model dict" - -# Test from_smtlib exists and round-trips basics -@assert from_smtlib("(+ x y)") == :(x + y) "from_smtlib basic arithmetic" -@assert from_smtlib("true") == true "from_smtlib boolean" - -println("TASK 1 PASSED") -' -``` - ---- - -## TASK 2: Remove Bogus Examples Directory - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/examples/SafeDOMExample.res` -- `/var$REPOS_DIR/SMTLib.jl/examples/web-project-deno.json` - -**Problem:** -The `examples/` directory contains a ReScript DOM-mounting example and a Deno -project config. Neither has anything to do with SMT solving. They are leftover -RSR template files. The SPDX header in `SafeDOMExample.res` is `AGPL-3.0-or-later` -which violates the license policy (should be MPL-2.0 or at least not AGPL). - -**What to do:** -1. Delete `examples/SafeDOMExample.res`. -2. Delete `examples/web-project-deno.json`. -3. Create `examples/basic_sat.jl` with a self-contained example that checks - satisfiability (can run without a solver by showing the generated SMT-LIB2 - script output). -4. Create `examples/incremental.jl` showing push/pop usage (after TASK 1). -5. Add SPDX header `# SPDX-License-Identifier: CC-BY-SA-4.0` to all new files. - -**Verification:** -```bash -# Bogus files gone -test ! -f /var$REPOS_DIR/SMTLib.jl/examples/SafeDOMExample.res && echo "PASS: res removed" -test ! -f /var$REPOS_DIR/SMTLib.jl/examples/web-project-deno.json && echo "PASS: deno removed" - -# New examples exist and are valid Julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e 'include("/var$REPOS_DIR/SMTLib.jl/examples/basic_sat.jl")' && echo "PASS: basic_sat runs" -``` - ---- - -## TASK 3: Fix Unsat Core and Named Assertions (Documented but Nonexistent) - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl` (function `assert!` at line 400, `build_script` at line 430, `parse_result` at line 503) -- `/var$REPOS_DIR/SMTLib.jl/docs/src/examples.md` (lines 86-97) - -**Problem:** -`docs/src/examples.md` lines 86-97 show `assert!(ctx, expr, name=:c1)` with -named assertions and `check_sat(ctx, unsat_core=true)` returning -`result.unsat_core`. The `SMTResult` struct has an `unsat_core` field (line 78), -but: -- `assert!` does not accept a `name` keyword argument. -- `build_script` never emits `(set-option :produce-unsat-cores true)`. -- `build_script` never emits `(get-unsat-core)`. -- `parse_result` never parses unsat core output. -- `check_sat` does not accept an `unsat_core` keyword. - -**What to do:** -1. Extend `assert!(ctx, expr; name=nothing)` to accept an optional name. When - `name` is provided, emit `(assert (! expr :named name))`. -2. Add `unsat_core_requested::Bool` field to `SMTContext`, defaulting to `false`. -3. Extend `check_sat(ctx; get_model=true, unsat_core=false)` to accept the - `unsat_core` keyword. -4. Update `build_script` to emit `(set-option :produce-unsat-cores true)` and - `(get-unsat-core)` when `unsat_core=true`. -5. Update `parse_result` to parse unsat core from solver output (lines matching - parenthesized symbol lists after "unsat"). - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using SMTLib - -ctx = SMTContext(logic=:QF_LIA) -declare(ctx, :x, Int) - -# Named assertions should work -assert!(ctx, :(x > 10), name=:c1) -assert!(ctx, :(x < 5), name=:c2) - -# Verify the SMT-LIB script contains named assertions -script = SMTLib.build_script(ctx, true) -@assert occursin(":named c1", script) "Named assertion c1 missing from script" -@assert occursin(":named c2", script) "Named assertion c2 missing from script" - -println("TASK 3 PASSED") -' -``` - ---- - -## TASK 4: Fix solver_options References in Documentation - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/docs/src/solvers.md` (lines 137-146, 191) - -**Problem:** -The solvers documentation references `ctx.solver_options[:timeout]`, -`ctx.solver_options[:random_seed]`, `ctx.solver_options[:finite_model_find]`, -and `ctx.solver_options[:max_memory]`. The `SMTContext` struct has no -`solver_options` field. This code will throw `ErrorException` if anyone runs it. - -**What to do:** -Either: -(a) Add a `solver_options::Dict{Symbol, Any}` field to `SMTContext` and wire - it into `build_script` to emit `(set-option ...)` commands, OR -(b) Remove the solver_options examples from `docs/src/solvers.md` and replace - with documentation of existing features (timeout_ms constructor arg). - -Option (a) is preferred since the feature is useful. - -If implementing (a): -1. Add `solver_options::Dict{Symbol, Any}` to `SMTContext` struct (line 96-102), - initialized to `Dict{Symbol, Any}()`. -2. Update the constructor (line 104-112). -3. In `build_script`, emit solver options as `(set-option :key value)` lines. - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using SMTLib - -ctx = SMTContext(logic=:QF_LIA) - -# solver_options should be accessible -ctx.solver_options[:random_seed] = 42 - -script = SMTLib.build_script(ctx, false) -@assert occursin("random_seed", script) || occursin("random-seed", script) "solver option not in script" - -println("TASK 4 PASSED") -' -``` - ---- - -## TASK 5: Replace All {{PLACEHOLDER}} Tokens in RSR Files - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/SECURITY.md` ({{OWNER}}, {{REPO}}, {{PROJECT_NAME}}, etc.) -- `/var$REPOS_DIR/SMTLib.jl/CONTRIBUTING.md` ({{FORGE}}, {{OWNER}}, {{REPO}}) -- `/var$REPOS_DIR/SMTLib.jl/CODE_OF_CONDUCT.md` ({{OWNER}}, {{REPO}}, etc.) -- `/var$REPOS_DIR/SMTLib.jl/docs/CITATIONS.adoc` (wrong project name, AGPL license ref) -- `/var$REPOS_DIR/SMTLib.jl/ROADMAP.adoc` (says "YOUR Template Repo Roadmap") -- `/var$REPOS_DIR/SMTLib.jl/ABI-FFI-README.md` (line 1: "delete this line") - -**Problem:** -Dozens of `{{OWNER}}`, `{{REPO}}`, `{{FORGE}}`, `{{PROJECT_NAME}}`, -`{{SECURITY_EMAIL}}`, `{{PGP_FINGERPRINT}}`, etc. remain unreplaced. -`ROADMAP.adoc` line 2 says "YOUR Template Repo Roadmap." `CITATIONS.adoc` cites -"rsr-template-repo" with AGPL license. The ABI-FFI-README.md line 1 still says -"delete this line." - -**What to do:** -1. In SECURITY.md: - - `{{PROJECT_NAME}}` -> `SMTLib.jl` - - `{{OWNER}}` -> `hyperpolymath` - - `{{REPO}}` -> `SMTLib.jl` - - `{{SECURITY_EMAIL}}` -> `jonathan.jewell@open.ac.uk` - - Remove the template instruction comment block (lines 3-19). - - Remove PGP sections if not applicable. -2. In CONTRIBUTING.md: - - `{{FORGE}}` -> `github.com` - - `{{OWNER}}` -> `hyperpolymath` - - `{{REPO}}` -> `SMTLib.jl` -3. In CODE_OF_CONDUCT.md: - - Same replacements as above. - - Remove template instruction block. -4. In CITATIONS.adoc: - - Replace `rsr-template-repo` with `SMTLib.jl`. - - Replace `AGPL-3.0-or-later` with `MPL-2.0`. - - Replace author `Polymath, Hyper` with `Jewell, Jonathan D.A.` -5. In ROADMAP.adoc: - - Replace "YOUR Template Repo" with "SMTLib.jl". - - Add real milestones reflecting the actual state of the project. -6. In ABI-FFI-README.md: - - Delete line 1 (`{{~ Aditionally delete this line...}}`). - - Replace `{{PROJECT}}` with `SMTLib` and `{{project}}` with `smtlib`. - - Replace `{{LICENSE}}` with `MPL-2.0`. - -**Verification:** -```bash -cd /var$REPOS_DIR/SMTLib.jl -grep -rn '{{' --include='*.md' --include='*.adoc' . | grep -v '.git/' | grep -v 'contractiles/' | grep -v 'ABI-FFI' | head -5 -# Should return NO matches (excluding contractile templates which are allowed) -echo "---" -grep -c '{{PROJECT}}' ABI-FFI-README.md -# Should return 0 -echo "---" -head -1 ROADMAP.adoc | grep -v 'YOUR' -# Should not contain "YOUR" -echo "TASK 5 PASSED (if all above are empty/0)" -``` - ---- - -## TASK 6: Replace All {{PROJECT}} Placeholders in ABI/FFI Files - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/src/abi/Types.idr` (lines 6, 11) -- `/var$REPOS_DIR/SMTLib.jl/src/abi/Layout.idr` (lines 8, 10) -- `/var$REPOS_DIR/SMTLib.jl/src/abi/Foreign.idr` (lines 9, 11, 12, 23, 35, 49, etc.) -- `/var$REPOS_DIR/SMTLib.jl/ffi/zig/build.zig` (lines 1, 12, 23, 35, 36, 82) -- `/var$REPOS_DIR/SMTLib.jl/ffi/zig/src/main.zig` (lines 1, 12, 54, 73, 89, etc.) -- `/var$REPOS_DIR/SMTLib.jl/ffi/zig/test/integration_test.zig` (lines 1, 10-17, etc.) - -**Problem:** -Every ABI and FFI file is the raw RSR template with `{{PROJECT}}` and -`{{project}}` placeholders. None of these files will compile. Additionally, -the SPDX headers in the Zig files say `AGPL-3.0-or-later` instead of -`MPL-2.0`. - -**What to do:** -1. In all `.idr` files: replace `{{PROJECT}}` with `SMTLib`. -2. In all `.zig` files: replace `{{PROJECT}}` with `SMTLib` and `{{project}}` - with `smtlib`. -3. In all `.zig` files: change SPDX from `AGPL-3.0-or-later` to - `MPL-2.0`. -4. Consider whether the ABI/FFI layer makes sense for a pure-Julia SMT interface. - If it does not, add a note to `ABI-FFI-README.md` explaining that the ABI/FFI - layer is reserved for future native solver bindings, or remove it entirely - and document why in the commit message. - -**Verification:** -```bash -cd /var$REPOS_DIR/SMTLib.jl -grep -rn '{{PROJECT}}\|{{project}}' src/abi/ ffi/ | head -5 -# Should return 0 matches -grep -rn 'AGPL' src/abi/ ffi/ | head -5 -# Should return 0 matches -echo "TASK 6 PASSED (if both empty)" -``` - ---- - -## TASK 7: Fix CodeQL Workflow (Scanning for Wrong Language) - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/.github/workflows/codeql.yml` - -**Problem:** -The CodeQL workflow (line 24-25) scans for `language: rust` with -`build-mode: none`. This is a Julia repository. CodeQL does not have a Julia -language scanner, so this workflow will either fail silently or produce no -useful results. The correct approach is to scan for `actions` (workflow -security) or remove the workflow if no supported language is present. - -**What to do:** -1. Change the matrix to `language: actions` (CodeQL can scan GitHub Actions - workflows for injection vulnerabilities, which IS useful). -2. Remove `build-mode: none` (not applicable to actions scanning). -3. Update the checkout action SHA to match the standard pinned version from - CLAUDE.md: `actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5` (v4). -4. Update CodeQL action SHA to: `github/codeql-action@6624720a57d4c312633c7b953db2f2da5bcb4c3a` (v3). - -**Verification:** -```bash -cd /var$REPOS_DIR/SMTLib.jl -grep 'language:' .github/workflows/codeql.yml -# Should show "actions", not "rust" -grep 'build-mode' .github/workflows/codeql.yml -# Should return nothing -echo "TASK 7 PASSED (if actions and no build-mode)" -``` - ---- - -## TASK 8: Fix Scorecard Workflow (Unpinned Actions) - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/.github/workflows/scorecard.yml` - -**Problem:** -Lines 18, 22, 29 use unpinned action tags (`@v4`, `@v2.3.1`, `@v3`) instead -of SHA-pinned versions. This fails OpenSSF Scorecard "Pinned-Dependencies" -check and is a supply-chain security risk. - -**What to do:** -1. Pin `actions/checkout@v4` to SHA `34e114876b0b11c390a56381ad16ebd13914f8d5`. -2. Pin `ossf/scorecard-action@v2.4.0` to SHA `62b2cac7ed8198b15735ed49ab1e5cf35480ba46`. -3. Pin `github/codeql-action/upload-sarif@v3` to SHA `6624720a57d4c312633c7b953db2f2da5bcb4c3a`. - -**Verification:** -```bash -cd /var$REPOS_DIR/SMTLib.jl -grep -E '@v[0-9]' .github/workflows/scorecard.yml -# Should return nothing (all SHA-pinned) -echo "TASK 8 PASSED (if empty)" -``` - ---- - -## TASK 9: Add Missing RSR Infrastructure Files - -**Files to create:** -- `/var$REPOS_DIR/SMTLib.jl/.editorconfig` -- `/var$REPOS_DIR/SMTLib.jl/.gitignore` -- `/var$REPOS_DIR/SMTLib.jl/.machine_readable/STATE.scm` -- `/var$REPOS_DIR/SMTLib.jl/.machine_readable/ECOSYSTEM.scm` -- `/var$REPOS_DIR/SMTLib.jl/.machine_readable/META.scm` - -**Problem:** -The repo is missing `.editorconfig`, `.gitignore`, and the entire -`.machine_readable/` directory with STATE.scm, ECOSYSTEM.scm, and META.scm. -The AI.a2ml file references `.machines_readable/6scm/STATE.scm` (wrong path, -wrong directory name). There is no `.bot_directives/` directory either. - -**What to do:** -1. Create `.editorconfig` with Julia-appropriate settings (4-space indent, - UTF-8, LF line endings, trim trailing whitespace). -2. Create `.gitignore` for Julia packages: - - `/Manifest.toml` (already tracked but should be in .gitignore for libraries) - - `*.jl.cov`, `*.jl.*.cov`, `*.jl.mem` - - `/docs/build/` - - `/generated/` - - `*.smt2` (temp solver files) -3. Create `.machine_readable/STATE.scm` reflecting actual project state: - phase=implementation, maturity=alpha, ~55% completion. -4. Create `.machine_readable/ECOSYSTEM.scm` with relationship to Axiom.jl - (as noted in README.adoc line 85). -5. Create `.machine_readable/META.scm` with architecture decisions and license - info. -6. Fix `AI.a2ml` to reference `.machine_readable/` (not `.machines_readable/6scm/`). - -**Verification:** -```bash -cd /var$REPOS_DIR/SMTLib.jl -test -f .editorconfig && echo "PASS: .editorconfig exists" -test -f .gitignore && echo "PASS: .gitignore exists" -test -f .machine_readable/STATE.scm && echo "PASS: STATE.scm exists" -test -f .machine_readable/ECOSYSTEM.scm && echo "PASS: ECOSYSTEM.scm exists" -test -f .machine_readable/META.scm && echo "PASS: META.scm exists" -grep -c 'machines_readable' AI.a2ml -# Should return 0 (fixed to machine_readable) -echo "TASK 9 PASSED" -``` - ---- - -## TASK 10: Fix Test Coverage Gaps - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/test/runtests.jl` - -**Problem:** -The test file has decent coverage of `to_smtlib`, type mapping, and value -parsing. But several functions have zero test coverage: -- `prove()` (line 689) -- never tested. -- `extract_variables()` (line 711) -- never tested. -- `is_operator()` (line 728) -- never tested. -- `handle_let()` (line 267) -- never tested. -- `handle_chained_comparison()` (line 250) -- never tested. -- `build_script()` (line 430) -- never directly tested. -- `build_solver_command()` (line 484) -- never tested. -- `@smt` macro (line 630) -- never tested without a solver. -- `reset!()` (line 411) -- never tested. -- `SMTContext` constructor error path (line 108-109) -- never tested. - -Also, `to_smtlib` for `&&` and `||` (lines 227-232) uses `expr.head == :&&` -syntax which changed across Julia versions. The tests for `to_smtlib(:(x && y))` -may fail on Julia < 1.7 because the AST representation changed. - -**What to do:** -1. Add a `@testset "Script Generation"` that calls `build_script` directly and - checks the output string contains `(set-logic ...)`, `(declare-const ...)`, - `(assert ...)`, and `(check-sat)`. -2. Add a `@testset "Solver Commands"` that tests `build_solver_command` for - z3, cvc5, yices, and unknown solvers. -3. Add a `@testset "Variable Extraction"` testing `extract_variables`. -4. Add a `@testset "Operator Detection"` testing `is_operator`. -5. Add a `@testset "Context Reset"` testing `reset!`. -6. Add a `@testset "Chained Comparison"` testing `handle_chained_comparison` - with expressions like `:(1 < x < 10)`. -7. Add a `@testset "Let Bindings"` testing `handle_let`. -8. Add a `@testset "Macro Generation"` that tests `@smt` structurally without - needing a solver (mock or check generated script). - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using Pkg; Pkg.test() -' 2>&1 | tail -5 -# Should show all tests passing with expanded coverage -``` - ---- - -## TASK 11: Fix the `prove()` Function Type Inference - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl` (function `prove` at line 689, `extract_variables` at line 711) - -**Problem:** -The `prove()` function calls `extract_variables()` which defaults every -variable to `Int` (line 720: `vars[expr] = Int`). This means: -- `prove(:(x > 0 && x < 10))` declares `x` as Int but also declares `&&` and - `>` and `<` as Int variables (they pass `is_operator` but the check is flawed). -- Actually, `is_operator` checks for `Symbol("+")` etc., but operators in Julia - ASTs are stored as `:+`, `:>`, `:&&` -- the `Symbol("...")` constructor creates - them. However, `expr.args[1]` in a `:call` Expr is the operator symbol, so - `_extract_vars!` recurses into `expr.args` including the operator. It would - declare `:+` as a variable unless `is_operator` catches it. -- The `is_operator` list is incomplete: missing `:implies`, `:iff`, `:xor`, - `:forall`, `:exists`, `:select`, `:store`, all `:bv*` operators, math - functions (`:sqrt`, `:exp`, `:log`, `:sin`, `:cos`, `:tan`, `:^`). -- The comment on line 713 says "Simple heuristic - would need type inference - in practice" which is honest, but the function is exported and documented. - -**What to do:** -1. Expand `is_operator` to include all operators from `julia_op_to_smt`'s - keys (lines 287-351). Extract the keys from the Dict and check membership. - Better yet, define the operator set once and share it. -2. Add a `type` parameter to `prove()` so users can specify variable types: - `prove(expr; vars=Dict(:x => Int, :y => Float64))`. -3. When `vars` is provided, skip `extract_variables` and use the provided dict. -4. Document the limitations of `extract_variables` in its docstring. - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using SMTLib - -# Test that operators are not extracted as variables -vars = SMTLib.extract_variables(:(x + y > 0)) -@assert !haskey(vars, :+) "Operator + should not be a variable" -@assert !haskey(vars, :>) "Operator > should not be a variable" -@assert haskey(vars, :x) "x should be extracted" -@assert haskey(vars, :y) "y should be extracted" -@assert !haskey(vars, 0) || true # literals should not be variables - -println("TASK 11 PASSED") -' -``` - ---- - -## TASK 12: Fix parse_model Regex (Misses Multi-line Models) - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl` (function `parse_model` at line 539, line 544) - -**Problem:** -The model parser on line 544 uses a single-line regex: -``` -r"\(define-fun\s+(\w+)\s+\(\)\s+\w+\s+(.+?)\)" -``` -This fails for multi-line model output, which is the default format from Z3 -and CVC5. A typical Z3 model looks like: -``` -(model - (define-fun x () Int - 5) - (define-fun y () Int - (- 3)) -) -``` -The regex requires the entire `define-fun` to be on one line. It also fails to -match type names with spaces like `(_ BitVec 32)`. - -**What to do:** -1. Replace the single-line regex with a proper S-expression parser that handles - nested parentheses and multi-line output. -2. At minimum, use `s` flag for dotall matching and handle the multi-line case: - `r"\(define-fun\s+(\w+)\s+\(\)\s+[\w\s\(\)_]+\s+(.+?)\)"s`. -3. Better approach: write a minimal S-expression tokenizer that finds balanced - `(define-fun ...)` blocks, then extracts name, type, and value. -4. Handle type names like `(_ BitVec 32)` and `(Array Int Int)`. - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using SMTLib - -# Multi-line model output from Z3 -output = """sat -(model - (define-fun x () Int - 5) - (define-fun y () Int - (- 3)) -)""" - -model = SMTLib.parse_model(output) -@assert haskey(model, :x) "Should parse x from multi-line model" -@assert haskey(model, :y) "Should parse y from multi-line model" -@assert model[:x] == 5 "x should be 5" -@assert model[:y] == -3 "y should be -3" - -println("TASK 12 PASSED") -' -``` - ---- - -## TASK 13: Fix Timeout Detection in parse_result - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/src/SMTLib.jl` (function `parse_result` at line 503, line 519) - -**Problem:** -Line 519 checks `startswith(line, "timeout")` but: -- Z3 does not output "timeout" -- it outputs "unknown" with `(:reason-unknown timeout)` in a separate get-info response, or just outputs nothing/errors. -- CVC5 outputs "unknown" on timeout, not "timeout". -- Yices outputs "unknown" on timeout. -- No major solver outputs a bare "timeout" string. - -The timeout detection is effectively dead code. Real timeout detection requires -checking the process exit code or using Julia's `timedwait`/`Timer`. - -**What to do:** -1. Use Julia's `Base.process_running` and timeout mechanism. Wrap the solver - process in a `Timer` that kills it after `timeout_ms`. -2. In `run_solver`, use `open(cmd)` with a timer instead of `read(ignorestatus(cmd))`. -3. If the process is killed due to timeout, set status to `:timeout`. -4. Remove the bogus `startswith(line, "timeout")` check. -5. Also handle solver stderr output (currently ignored) which may contain error - messages. - -**Verification:** -```julia -julia --project=/var$REPOS_DIR/SMTLib.jl -e ' -using SMTLib - -# Test that a very short timeout results in :timeout (if solver available) -solvers = available_solvers() -if !isempty(solvers) - ctx = SMTContext(solver=first(solvers), logic=:QF_NRA, timeout_ms=1) - declare(ctx, :x, Float64) - # Intentionally hard problem - for i in 1:100 - assert!(ctx, :(x * x * x + x > $i)) - end - result = check_sat(ctx) - @assert result.status in (:timeout, :unknown, :sat, :unsat) "Should handle timeout gracefully" - println("Solver timeout test: status = $(result.status)") -else - println("No solver available, skipping timeout test") -end - -# Test that parse_result handles empty output gracefully -r = SMTLib.parse_result("") -@assert r.status == :unknown "Empty output should be :unknown" - -println("TASK 13 PASSED") -' -``` - ---- - -## TASK 14: Add .gitignore and Remove Tracked Manifest.toml - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/Manifest.toml` (currently tracked) -- `/var$REPOS_DIR/SMTLib.jl/.gitignore` (does not exist) - -**Problem:** -`Manifest.toml` is tracked in git. For Julia libraries (not applications), -`Manifest.toml` should NOT be committed because it pins exact dependency -versions and Julia versions (`julia_version = "1.12.2"` on line 3) that will -break for users on different Julia versions. The Julia community convention -is clear: libraries should `.gitignore` their `Manifest.toml`. - -**What to do:** -1. Create `.gitignore` with standard Julia entries: - ``` - /Manifest.toml - *.jl.cov - *.jl.*.cov - *.jl.mem - /docs/build/ - /generated/ - *.smt2 - ``` -2. Remove `Manifest.toml` from git tracking: `git rm --cached Manifest.toml`. -3. Ensure `Manifest.toml` remains on disk (not deleted, just untracked). - -**Verification:** -```bash -cd /var$REPOS_DIR/SMTLib.jl -test -f .gitignore && echo "PASS: .gitignore exists" -grep 'Manifest.toml' .gitignore && echo "PASS: Manifest.toml in .gitignore" -git ls-files --error-unmatch Manifest.toml 2>/dev/null && echo "FAIL: still tracked" || echo "PASS: Manifest.toml untracked" -``` - ---- - -## TASK 15: Fix quality.yml TODO Scanner (Wrong File Extensions) - -**Files:** -- `/var$REPOS_DIR/SMTLib.jl/.github/workflows/quality.yml` (line 31) - -**Problem:** -The quality workflow scans for TODOs in `*.rs`, `*.res`, `*.py`, `*.ex` files. -This is a Julia repository. It should scan `*.jl` files. None of the scanned -extensions exist in the repo. - -**What to do:** -1. Change line 31 to include `*.jl` instead of/in addition to the current - extensions: - ``` - grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.jl" --include="*.idr" --include="*.zig" . | head -20 || echo "None found" - ``` - -**Verification:** -```bash -grep 'include.*\.jl' /var$REPOS_DIR/SMTLib.jl/.github/workflows/quality.yml && echo "TASK 15 PASSED" -``` - ---- - -## FINAL VERIFICATION - -After completing all tasks, run this sequence: - -```bash -cd /var$REPOS_DIR/SMTLib.jl - -echo "=== 1. Julia tests pass ===" -julia --project=. -e 'using Pkg; Pkg.test()' 2>&1 | tail -10 - -echo "" -echo "=== 2. No remaining template placeholders (excluding contractiles) ===" -grep -rn '{{' --include='*.md' --include='*.adoc' --include='*.idr' --include='*.zig' . | grep -v '.git/' | grep -v 'contractiles/' | wc -l -# Expected: 0 - -echo "" -echo "=== 3. All exports have implementations ===" -julia --project=. -e ' -using SMTLib -for name in names(SMTLib) - sym = getfield(SMTLib, name) - println(" $name => $(typeof(sym))") -end -' - -echo "" -echo "=== 4. No AGPL references in source ===" -grep -rn 'AGPL' --include='*.jl' --include='*.idr' --include='*.zig' . | grep -v '.git/' | wc -l -# Expected: 0 - -echo "" -echo "=== 5. RSR infrastructure files exist ===" -for f in .editorconfig .gitignore .machine_readable/STATE.scm .machine_readable/ECOSYSTEM.scm .machine_readable/META.scm; do - test -f "$f" && echo " OK: $f" || echo " MISSING: $f" -done - -echo "" -echo "=== 6. CodeQL scans correct language ===" -grep 'language:' .github/workflows/codeql.yml - -echo "" -echo "=== 7. All workflow actions SHA-pinned ===" -grep -E 'uses:.*@v[0-9]' .github/workflows/*.yml | wc -l -# Expected: 0 - -echo "" -echo "=== 8. Examples are Julia files ===" -ls examples/*.jl 2>/dev/null && echo "OK" || echo "MISSING Julia examples" -ls examples/*.res 2>/dev/null && echo "FAIL: ReScript still present" || echo "OK: no ReScript" - -echo "" -echo "=== 9. Manifest.toml not tracked ===" -git ls-files --error-unmatch Manifest.toml 2>/dev/null && echo "FAIL" || echo "OK" - -echo "" -echo "=== FINAL VERDICT ===" -echo "If all above show OK/0/expected values, all tasks are complete." -``` diff --git a/packages/SMTLib.jl/TOPOLOGY.md b/packages/SMTLib.jl/TOPOLOGY.adoc similarity index 90% rename from packages/SMTLib.jl/TOPOLOGY.md rename to packages/SMTLib.jl/TOPOLOGY.adoc index 5df0c3931..60c9a6e5a 100644 --- a/packages/SMTLib.jl/TOPOLOGY.md +++ b/packages/SMTLib.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== SMTLib.jl — Project Topology -# SMTLib.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -53,11 +49,11 @@ │ .github/workflows/ (RSR Gate) │ │ scripts/ (readiness) │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE LOGIC @@ -79,24 +75,25 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~93% Stable, near production -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Solver Discovery ──────► Context Management ──────► Expr Generation │ Parser (from_smtlib) ◀───── Result Handling ◀──────────┘ -``` +.... -## 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/packages/SMTLib.jl/docs/src/api.md b/packages/SMTLib.jl/docs/src/api.adoc similarity index 51% rename from packages/SMTLib.jl/docs/src/api.md rename to packages/SMTLib.jl/docs/src/api.adoc index fcbbf976f..76c88aeb6 100644 --- a/packages/SMTLib.jl/docs/src/api.md +++ b/packages/SMTLib.jl/docs/src/api.adoc @@ -1,53 +1,60 @@ -# API Reference +== API Reference -## Types +=== Types -```@docs +[source,@docs] +---- SMTLib.SMTSolver SMTLib.SMTResult SMTLib.SMTContext -``` +---- -## Solver Discovery +=== Solver Discovery -```@docs +[source,@docs] +---- SMTLib.available_solvers SMTLib.find_solver -``` +---- -## Context Management +=== Context Management -```@docs +[source,@docs] +---- SMTLib.SMTContext SMTLib.declare SMTLib.assert! SMTLib.check_sat SMTLib.get_model SMTLib.reset! -``` +---- -## Incremental Solving +=== Incremental Solving -```@docs +[source,@docs] +---- Base.push!(::SMTLib.SMTContext) Base.pop!(::SMTLib.SMTContext) -``` +---- -## Conversion +=== Conversion -```@docs +[source,@docs] +---- SMTLib.to_smtlib SMTLib.from_smtlib -``` +---- -## Macros +=== Macros -```@docs +[source,@docs] +---- SMTLib.@smt -``` +---- -## Constants +=== Constants -```@docs +[source,@docs] +---- SMTLib.LOGICS -``` +---- diff --git a/packages/SMTLib.jl/docs/src/examples.md b/packages/SMTLib.jl/docs/src/examples.adoc similarity index 83% rename from packages/SMTLib.jl/docs/src/examples.md rename to packages/SMTLib.jl/docs/src/examples.adoc index 2859b0578..545ff7eb8 100644 --- a/packages/SMTLib.jl/docs/src/examples.md +++ b/packages/SMTLib.jl/docs/src/examples.adoc @@ -1,8 +1,9 @@ -# Examples +== Examples -## Basic Constraint Solving +=== Basic Constraint Solving -```julia +[source,julia] +---- using SMTLib # Linear integer arithmetic @@ -15,11 +16,12 @@ assert!(ctx, :(y >= 0)) result = check_sat(ctx) @show result.model # Dict(:x => 4, :y => 3) or similar -``` +---- -## Incremental Solving +=== Incremental Solving -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_LIA) declare(ctx, :x, Int) assert!(ctx, :(x > 5)) @@ -35,11 +37,12 @@ result2 = check_sat(ctx) # unsat # Backtrack pop!(ctx) result3 = check_sat(ctx) # sat again -``` +---- -## Bitvector Constraints +=== Bitvector Constraints -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_BV) declare(ctx, :a, BitVec{8}) declare(ctx, :b, BitVec{8}) @@ -49,11 +52,12 @@ assert!(ctx, :(bvadd(a, b) == 0xFF)) assert!(ctx, :(bvand(a, b) == 0x00)) result = check_sat(ctx) -``` +---- -## Real Arithmetic +=== Real Arithmetic -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_LRA) declare(ctx, :x, Real) declare(ctx, :y, Real) @@ -63,11 +67,12 @@ assert!(ctx, :(x - y < 2.0)) assert!(ctx, :(x > 0)) result = check_sat(ctx) -``` +---- -## Array Theory +=== Array Theory -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_AUFLIA) declare(ctx, :arr, Array{Int,Int}) declare(ctx, :i, Int) @@ -79,11 +84,12 @@ assert!(ctx, :(select(store(arr, j, 100), j) == 100)) assert!(ctx, :(i != j)) result = check_sat(ctx) -``` +---- -## Unsat Core +=== Unsat Core -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_LIA) declare(ctx, :x, Int) @@ -94,11 +100,12 @@ assert!(ctx, :(x >= 0), name=:c3) result = check_sat(ctx, unsat_core=true) @show result.unsat_core # [:c1, :c2] - conflicting constraints -``` +---- -## Timeout Handling +=== Timeout Handling -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_NRA, timeout=5000) # 5 second timeout declare(ctx, :x, Real) assert!(ctx, :(x^5 + x^3 + x == 42)) # Hard nonlinear constraint @@ -107,11 +114,12 @@ result = check_sat(ctx) if result.status == :timeout println("Solver timed out") end -``` +---- -## Using the @smt Macro +=== Using the @smt Macro -```julia +[source,julia] +---- # Convenient syntax for simple queries result = @smt begin x::Int @@ -125,11 +133,12 @@ if result.status == :sat println("x = ", result.model[:x]) println("y = ", result.model[:y]) end -``` +---- -## Multiple Solvers +=== Multiple Solvers -```julia +[source,julia] +---- # Find all available solvers solvers = available_solvers() for solver in solvers @@ -139,11 +148,12 @@ end # Use a specific solver z3 = find_solver(:z3) ctx = SMTContext(solver=z3, logic=:QF_LIA) -``` +---- -## Complex Constraints +=== Complex Constraints -```julia +[source,julia] +---- ctx = SMTContext(logic=:QF_NIA) declare(ctx, :x, Int) declare(ctx, :y, Int) @@ -158,4 +168,4 @@ result = check_sat(ctx) if result.status == :sat @show result.model end -``` +---- diff --git a/packages/SMTLib.jl/docs/src/index.adoc b/packages/SMTLib.jl/docs/src/index.adoc new file mode 100644 index 000000000..a353cace2 --- /dev/null +++ b/packages/SMTLib.jl/docs/src/index.adoc @@ -0,0 +1,106 @@ +== SMTLib.jl + +A lightweight Julia interface to SMT solvers via SMT-LIB2 format. + +=== Features + +* *Auto-detection* of installed SMT solvers (Z3, CVC5, Yices, MathSAT) +* *Julia expression to SMT-LIB2* conversion +* *Multiple logics*: QF_LIA, QF_LRA, QF_NRA, QF_BV, arrays, and more +* *Model parsing* and counterexample extraction +* *Timeout support* +* *Incremental solving* with push/pop semantics +* *Zero dependencies* - pure Julia + +=== Quick Start + +[source,julia] +---- +using SMTLib + +# Create an SMT context +ctx = SMTContext(logic=:QF_LIA) + +# Declare variables +declare(ctx, :x, Int) +declare(ctx, :y, Int) + +# Add constraints +assert!(ctx, :(x + y == 10)) +assert!(ctx, :(x > 0)) +assert!(ctx, :(y > 0)) + +# Check satisfiability +result = check_sat(ctx) + +if result.status == :sat + println("Solution found:") + println("x = ", result.model[:x]) + println("y = ", result.model[:y]) +end +---- + +=== Installation + +[source,julia] +---- +using Pkg +Pkg.add(url="https://github.com/hyperpolymath/SMTLib.jl") +---- + +==== Prerequisites + +Install at least one SMT solver: + +[source,bash] +---- +# Z3 (recommended) +brew install z3 # macOS +apt install z3 # Ubuntu/Debian +pacman -S z3 # Arch + +# CVC5 +brew install cvc5 # macOS +apt install cvc5 # Ubuntu/Debian +---- + +=== What is SMT? + +*Satisfiability Modulo Theories (SMT)* extends boolean satisfiability +(SAT) with theories like arithmetic, arrays, and bitvectors. SMT solvers +are used for: + +* *Formal verification* - proving program correctness +* *Symbolic execution* - exploring execution paths +* *Constraint solving* - finding solutions to complex constraints +* *Test generation* - generating inputs that trigger bugs +* *Program synthesis* - generating programs from specifications + +=== Supported Solvers + +* *Z3* (Microsoft Research) - Most feature-complete +* *CVC5* - Strong theory support +* *Yices* - Fast for linear arithmetic +* *MathSAT* - Good for optimization + +=== Supported Logics + +[width="100%",cols="35%,65%",options="header",] +|=== +|Logic |Description +|QF_LIA |Quantifier-free linear integer arithmetic +|QF_LRA |Quantifier-free linear real arithmetic +|QF_NIA |Quantifier-free nonlinear integer arithmetic +|QF_NRA |Quantifier-free nonlinear real arithmetic +|QF_BV |Quantifier-free bitvectors +|QF_AUFLIA |Arrays, uninterpreted functions, linear integer arithmetic +|LIA |Linear integer arithmetic with quantifiers +|LRA |Linear real arithmetic with quantifiers +|AUFLIRA |Arrays, uninterpreted functions, linear arithmetic +|ALL |All supported theories +|=== + +=== License + +SMTLib.jl is licensed under the +https://github.com/hyperpolymath/palimpsest-license[MPL-2.0] license. diff --git a/packages/SMTLib.jl/docs/src/index.md b/packages/SMTLib.jl/docs/src/index.md deleted file mode 100644 index 91987f2fc..000000000 --- a/packages/SMTLib.jl/docs/src/index.md +++ /dev/null @@ -1,98 +0,0 @@ -# SMTLib.jl - -A lightweight Julia interface to SMT solvers via SMT-LIB2 format. - -## Features - -- **Auto-detection** of installed SMT solvers (Z3, CVC5, Yices, MathSAT) -- **Julia expression to SMT-LIB2** conversion -- **Multiple logics**: QF_LIA, QF_LRA, QF_NRA, QF_BV, arrays, and more -- **Model parsing** and counterexample extraction -- **Timeout support** -- **Incremental solving** with push/pop semantics -- **Zero dependencies** - pure Julia - -## Quick Start - -```julia -using SMTLib - -# Create an SMT context -ctx = SMTContext(logic=:QF_LIA) - -# Declare variables -declare(ctx, :x, Int) -declare(ctx, :y, Int) - -# Add constraints -assert!(ctx, :(x + y == 10)) -assert!(ctx, :(x > 0)) -assert!(ctx, :(y > 0)) - -# Check satisfiability -result = check_sat(ctx) - -if result.status == :sat - println("Solution found:") - println("x = ", result.model[:x]) - println("y = ", result.model[:y]) -end -``` - -## Installation - -```julia -using Pkg -Pkg.add(url="https://github.com/hyperpolymath/SMTLib.jl") -``` - -### Prerequisites - -Install at least one SMT solver: - -```bash -# Z3 (recommended) -brew install z3 # macOS -apt install z3 # Ubuntu/Debian -pacman -S z3 # Arch - -# CVC5 -brew install cvc5 # macOS -apt install cvc5 # Ubuntu/Debian -``` - -## What is SMT? - -**Satisfiability Modulo Theories (SMT)** extends boolean satisfiability (SAT) with theories like arithmetic, arrays, and bitvectors. SMT solvers are used for: - -- **Formal verification** - proving program correctness -- **Symbolic execution** - exploring execution paths -- **Constraint solving** - finding solutions to complex constraints -- **Test generation** - generating inputs that trigger bugs -- **Program synthesis** - generating programs from specifications - -## Supported Solvers - -- **Z3** (Microsoft Research) - Most feature-complete -- **CVC5** - Strong theory support -- **Yices** - Fast for linear arithmetic -- **MathSAT** - Good for optimization - -## Supported Logics - -| Logic | Description | -|-------|-------------| -| QF_LIA | Quantifier-free linear integer arithmetic | -| QF_LRA | Quantifier-free linear real arithmetic | -| QF_NIA | Quantifier-free nonlinear integer arithmetic | -| QF_NRA | Quantifier-free nonlinear real arithmetic | -| QF_BV | Quantifier-free bitvectors | -| QF_AUFLIA | Arrays, uninterpreted functions, linear integer arithmetic | -| LIA | Linear integer arithmetic with quantifiers | -| LRA | Linear real arithmetic with quantifiers | -| AUFLIRA | Arrays, uninterpreted functions, linear arithmetic | -| ALL | All supported theories | - -## License - -SMTLib.jl is licensed under the [MPL-2.0](https://github.com/hyperpolymath/palimpsest-license) license. diff --git a/packages/SMTLib.jl/docs/src/solvers.md b/packages/SMTLib.jl/docs/src/solvers.adoc similarity index 50% rename from packages/SMTLib.jl/docs/src/solvers.md rename to packages/SMTLib.jl/docs/src/solvers.adoc index 9cc1d311a..88e1040fb 100644 --- a/packages/SMTLib.jl/docs/src/solvers.md +++ b/packages/SMTLib.jl/docs/src/solvers.adoc @@ -1,22 +1,22 @@ -# Solver Support +== Solver Support -SMTLib.jl auto-detects installed SMT solvers and provides a unified interface. +SMTLib.jl auto-detects installed SMT solvers and provides a unified +interface. -## Supported Solvers +=== Supported Solvers -### Z3 (Recommended) +==== Z3 (Recommended) -**Developer:** Microsoft Research -**Website:** https://github.com/Z3Prover/z3 +*Developer:* Microsoft Research *Website:* +https://github.com/Z3Prover/z3 -**Strengths:** -- Most comprehensive theory support -- Excellent documentation -- Active development -- Good performance across all logics +*Strengths:* - Most comprehensive theory support - Excellent +documentation - Active development - Good performance across all logics -**Installation:** -```bash +*Installation:* + +[source,bash] +---- # macOS brew install z3 @@ -29,20 +29,20 @@ pacman -S z3 # From source git clone https://github.com/Z3Prover/z3 cd z3 && python scripts/mk_make.py && cd build && make -``` +---- + +==== CVC5 -### CVC5 +*Developer:* Stanford, University of Iowa, others *Website:* +https://cvc5.github.io/ -**Developer:** Stanford, University of Iowa, others -**Website:** https://cvc5.github.io/ +*Strengths:* - Strong theory combinations - Good for arrays and +datatypes - Formal verification focus -**Strengths:** -- Strong theory combinations -- Good for arrays and datatypes -- Formal verification focus +*Installation:* -**Installation:** -```bash +[source,bash] +---- # macOS brew install cvc5 @@ -53,20 +53,19 @@ apt install cvc5 wget https://github.com/cvc5/cvc5/releases/latest/download/cvc5-Linux chmod +x cvc5-Linux sudo mv cvc5-Linux /usr/local/bin/cvc5 -``` +---- -### Yices 2 +==== Yices 2 -**Developer:** SRI International -**Website:** https://yices.csl.sri.com/ +*Developer:* SRI International *Website:* https://yices.csl.sri.com/ -**Strengths:** -- Very fast for linear arithmetic -- Low memory footprint -- Good for embedded/resource-constrained use +*Strengths:* - Very fast for linear arithmetic - Low memory footprint - +Good for embedded/resource-constrained use -**Installation:** -```bash +*Installation:* + +[source,bash] +---- # macOS brew install yices @@ -77,31 +76,32 @@ apt install yices2 wget https://yices.csl.sri.com/releases/2.6.4/yices-2.6.4-x86_64-pc-linux-gnu.tar.gz tar xzf yices-2.6.4-x86_64-pc-linux-gnu.tar.gz sudo cp yices-2.6.4/bin/yices-smt2 /usr/local/bin/ -``` +---- + +==== MathSAT -### MathSAT +*Developer:* FBK and University of Trento *Website:* +https://mathsat.fbk.eu/ -**Developer:** FBK and University of Trento -**Website:** https://mathsat.fbk.eu/ +*Strengths:* - Optimization (MaxSMT) - Interpolation - UNSAT core +generation -**Strengths:** -- Optimization (MaxSMT) -- Interpolation -- UNSAT core generation +*Installation:* -**Installation:** -```bash +[source,bash] +---- # Download from website (requires registration for academic use) wget https://mathsat.fbk.eu/download.php?file=mathsat-5.6.10-linux-x86_64.tar.gz tar xzf mathsat-5.6.10-linux-x86_64.tar.gz sudo cp mathsat-5.6.10-linux-x86_64/bin/mathsat /usr/local/bin/ -``` +---- -## Solver Detection +=== Solver Detection -SMTLib.jl searches for solvers in your `PATH`: +SMTLib.jl searches for solvers in your `+PATH+`: -```julia +[source,julia] +---- # List all available solvers solvers = available_solvers() for solver in solvers @@ -113,91 +113,100 @@ z3 = find_solver(:z3) if isnothing(z3) error("Z3 not found. Please install it.") end -``` +---- -## Choosing a Solver +=== Choosing a Solver -```julia +[source,julia] +---- # Use a specific solver ctx = SMTContext(solver=find_solver(:z3), logic=:QF_LIA) # Or let SMTLib.jl choose automatically (prefers Z3) ctx = SMTContext(logic=:QF_LIA) -``` +---- -## Solver-Specific Features +=== Solver-Specific Features -### Z3 Extensions +==== Z3 Extensions Z3 supports some extensions beyond SMT-LIB2: -```julia +[source,julia] +---- # Set Z3-specific options ctx = SMTContext(logic=:QF_LIA) ctx.solver_options[:timeout] = 5000 # milliseconds ctx.solver_options[:random_seed] = 42 -``` +---- -### CVC5 Options +==== CVC5 Options -```julia +[source,julia] +---- ctx = SMTContext(solver=find_solver(:cvc5), logic=:QF_LIA) ctx.solver_options[:finite_model_find] = true -``` +---- -## Solver Comparison +=== Solver Comparison -| Feature | Z3 | CVC5 | Yices | MathSAT | -|---------|----|----|-------|---------| -| Linear arithmetic | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | -| Nonlinear arithmetic | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ | -| Bitvectors | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | -| Arrays | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ | -| Datatypes | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | -| Quantifiers | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | -| Performance | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | -| Documentation | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | +[cols=",,,,",options="header",] +|=== +|Feature |Z3 |CVC5 |Yices |MathSAT +|Linear arithmetic |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ +|Nonlinear arithmetic |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐ |⭐⭐⭐⭐ +|Bitvectors |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐ |⭐⭐⭐⭐ +|Arrays |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐ |⭐⭐⭐⭐ +|Datatypes |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐ |⭐⭐⭐ +|Quantifiers |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐ |⭐⭐⭐ +|Performance |⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ +|Documentation |⭐⭐⭐⭐⭐ |⭐⭐⭐⭐ |⭐⭐⭐ |⭐⭐⭐ +|=== -## Troubleshooting +=== Troubleshooting -### Solver Not Found +==== Solver Not Found -```julia +[source,julia] +---- # Check your PATH println(ENV["PATH"]) # Manually specify solver path solver = SMTSolver(:z3, "/opt/homebrew/bin/z3", "4.12.2") ctx = SMTContext(solver=solver, logic=:QF_LIA) -``` +---- -### Timeout Issues +==== Timeout Issues -```julia +[source,julia] +---- # Increase timeout ctx = SMTContext(logic=:QF_NRA, timeout=30000) # 30 seconds # Or use a faster solver for your logic ctx = SMTContext(solver=find_solver(:yices), logic=:QF_LIA) -``` +---- -### Memory Issues +==== Memory Issues -```julia +[source,julia] +---- # Use Yices for lower memory footprint ctx = SMTContext(solver=find_solver(:yices), logic=:QF_LIA) # Or limit solver memory (Z3) ctx.solver_options[:max_memory] = 4096 # MB -``` +---- -## Contributing Solver Support +=== Contributing Solver Support To add support for a new solver, implement: -1. Detection logic in `find_solver()` -2. SMT-LIB2 generation (usually standard) -3. Result parsing -4. Add to CI tests +[arabic] +. Detection logic in `+find_solver()+` +. SMT-LIB2 generation (usually standard) +. Result parsing +. Add to CI tests -See `src/SMTLib.jl` for details. +See `+src/SMTLib.jl+` for details. diff --git a/packages/ShellIntegration.jl/TOPOLOGY.md b/packages/ShellIntegration.jl/TOPOLOGY.adoc similarity index 87% rename from packages/ShellIntegration.jl/TOPOLOGY.md rename to packages/ShellIntegration.jl/TOPOLOGY.adoc index 0ec3583cf..5f6557363 100644 --- a/packages/ShellIntegration.jl/TOPOLOGY.md +++ b/packages/ShellIntegration.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== ShellIntegration.jl — Project Topology -# ShellIntegration.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATING SYSTEM / SHELLS │ ├─────────────────────────────────────────┤ @@ -37,11 +33,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE INTEGRATION @@ -59,25 +55,26 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██░░░░░░░░ ~25% Initial Bridge Scaffold -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... OS Shells ───────────► Bridge Logic ───────────► Unified API ▲ │ Safety Wrappers ────────────┘ ▼ Secure Shell (Valence) -``` +.... -## 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/packages/SiliconCore.jl/TOPOLOGY.md b/packages/SiliconCore.jl/TOPOLOGY.adoc similarity index 84% rename from packages/SiliconCore.jl/TOPOLOGY.md rename to packages/SiliconCore.jl/TOPOLOGY.adoc index dc4e23f8a..db4056c65 100644 --- a/packages/SiliconCore.jl/TOPOLOGY.md +++ b/packages/SiliconCore.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== SiliconCore.jl — Project Topology -# SiliconCore.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ HARDWARE / BARE METAL │ ├─────────────────────────────────────────┤ @@ -31,11 +27,11 @@ │ REPO INFRASTRUCTURE │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE PRIMITIVES @@ -47,24 +43,25 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █░░░░░░░░░ ~10% Initial Foundation -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Hardware Features ───► Arch Detection ──────► LowLevel.jl │ ASM Intrinsics ──────► ASM Kernels ────────────┘ -``` +.... -## 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/packages/Skein.jl/ABI-FFI-README.adoc b/packages/Skein.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..136e03ac2 --- /dev/null +++ b/packages/Skein.jl/ABI-FFI-README.adoc @@ -0,0 +1,87 @@ +== Skein.jl ABI/FFI Layer + +=== Architecture + +[width="100%",cols="21%,27%,25%,27%",options="header",] +|=== +|Layer |Language |Purpose |Location +|*ABI* |Idris2 |Interface definitions with formal proofs +|`+src/abi/*.idr+` + +|*FFI* |Zig |C-compatible implementation |`+ffi/zig/src/*.zig+` + +|*Headers* |C (generated) |Bridge between ABI and FFI +|`+generated/abi/*.h+` +|=== + +=== Overview + +The canonical Skein implementation is in Julia (`+src/*.jl+`). The +ABI/FFI layer provides C-compatible bindings so other languages can read +and write Skein databases without requiring a Julia runtime. + +==== Idris2 ABI (`+src/abi/+`) + +Formal specifications of: - *Types.idr* — Data types with dependent-type +proofs (GaussCode validity, hash length) - *Layout.idr* — C struct +memory layouts with size guarantees - *Foreign.idr* — Function +signatures with ownership and precondition documentation + +==== Zig FFI (`+ffi/zig/+`) + +C-compatible implementation of the ABI specification: - *src/main.zig* — +Core FFI functions (open, close, count, haskey, crossing_number, writhe, +delete) - *src/schema.sql* — Database schema (must match Julia +`+src/storage.jl+`) - *test/integration_test.zig* — Integration tests + +==== Generated Headers (`+generated/abi/+`) + +* *skein.h* — C header for consuming the FFI from C/C++/Python/etc. + +=== Building + +[source,bash] +---- +cd ffi/zig +zig build # builds libskein_ffi.so / .dylib / .dll +zig build test # runs integration tests +---- + +Requires system SQLite3 (`+sqlite3.h+` and `+libsqlite3+`). + +=== Usage from C + +[source,c] +---- +#include "skein.h" + +int main() { + skein_db_t db = skein_open(":memory:", 0); + if (!db) return 1; + + int32_t trefoil[] = {1, -2, 3, -1, 2, -3}; + int cn = skein_crossing_number(trefoil, 6); + // cn == 3 + + int count = skein_count(db); + // count == 0 + + skein_close(db); + return 0; +} +---- + +=== Database Compatibility + +The FFI layer creates and reads the same SQLite schema as the Julia +implementation (schema version 2). Databases created by either +implementation are fully interoperable. + +=== Status + +The FFI layer implements a subset of the full Julia API: - Database +lifecycle (open, close) - Pure invariant computation (crossing_number, +writhe) - Basic queries (count, haskey, delete) - Store and fetch +operations are defined in the ABI but not yet implemented in the Zig FFI + +For the complete API, use the Julia implementation directly. diff --git a/packages/Skein.jl/ABI-FFI-README.md b/packages/Skein.jl/ABI-FFI-README.md deleted file mode 100644 index 81cf95752..000000000 --- a/packages/Skein.jl/ABI-FFI-README.md +++ /dev/null @@ -1,79 +0,0 @@ - - - -# Skein.jl ABI/FFI Layer - -## Architecture - -| Layer | Language | Purpose | Location | -|-------|----------|---------|----------| -| **ABI** | Idris2 | Interface definitions with formal proofs | `src/abi/*.idr` | -| **FFI** | Zig | C-compatible implementation | `ffi/zig/src/*.zig` | -| **Headers** | C (generated) | Bridge between ABI and FFI | `generated/abi/*.h` | - -## Overview - -The canonical Skein implementation is in Julia (`src/*.jl`). The ABI/FFI layer provides C-compatible bindings so other languages can read and write Skein databases without requiring a Julia runtime. - -### Idris2 ABI (`src/abi/`) - -Formal specifications of: -- **Types.idr** — Data types with dependent-type proofs (GaussCode validity, hash length) -- **Layout.idr** — C struct memory layouts with size guarantees -- **Foreign.idr** — Function signatures with ownership and precondition documentation - -### Zig FFI (`ffi/zig/`) - -C-compatible implementation of the ABI specification: -- **src/main.zig** — Core FFI functions (open, close, count, haskey, crossing_number, writhe, delete) -- **src/schema.sql** — Database schema (must match Julia `src/storage.jl`) -- **test/integration_test.zig** — Integration tests - -### Generated Headers (`generated/abi/`) - -- **skein.h** — C header for consuming the FFI from C/C++/Python/etc. - -## Building - -```bash -cd ffi/zig -zig build # builds libskein_ffi.so / .dylib / .dll -zig build test # runs integration tests -``` - -Requires system SQLite3 (`sqlite3.h` and `libsqlite3`). - -## Usage from C - -```c -#include "skein.h" - -int main() { - skein_db_t db = skein_open(":memory:", 0); - if (!db) return 1; - - int32_t trefoil[] = {1, -2, 3, -1, 2, -3}; - int cn = skein_crossing_number(trefoil, 6); - // cn == 3 - - int count = skein_count(db); - // count == 0 - - skein_close(db); - return 0; -} -``` - -## Database Compatibility - -The FFI layer creates and reads the same SQLite schema as the Julia implementation (schema version 2). Databases created by either implementation are fully interoperable. - -## Status - -The FFI layer implements a subset of the full Julia API: -- Database lifecycle (open, close) -- Pure invariant computation (crossing_number, writhe) -- Basic queries (count, haskey, delete) -- Store and fetch operations are defined in the ABI but not yet implemented in the Zig FFI - -For the complete API, use the Julia implementation directly. diff --git a/packages/Skein.jl/CODE_OF_CONDUCT.adoc b/packages/Skein.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..03ea6df0a --- /dev/null +++ b/packages/Skein.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,31 @@ +== Code of Conduct + +=== Our Pledge + +We are committed to providing a welcoming and inclusive environment for +everyone, regardless of background, identity, or experience level. + +=== Our Standards + +*Expected behaviour:* - Respectful and constructive communication - +Collaboration and mentorship - Graceful acceptance of constructive +criticism - Focus on what is best for the community and the project + +*Unacceptable behaviour:* - Harassment, discrimination, or personal +attacks - Publishing others’ private information without consent - +Trolling, insulting, or derogatory comments - Any conduct that could +reasonably be considered inappropriate in a professional setting + +=== Enforcement + +Instances of unacceptable behaviour may be reported to +jonathan.jewell@open.ac.uk. + +All complaints will be reviewed and investigated. The project team is +obligated to maintain confidentiality with regard to the reporter. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org/[Contributor Covenant], version +2.1. diff --git a/packages/Skein.jl/CODE_OF_CONDUCT.md b/packages/Skein.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index a86343ec2..000000000 --- a/packages/Skein.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,32 +0,0 @@ - - - -# Code of Conduct - -## Our Pledge - -We are committed to providing a welcoming and inclusive environment for everyone, regardless of background, identity, or experience level. - -## Our Standards - -**Expected behaviour:** -- Respectful and constructive communication -- Collaboration and mentorship -- Graceful acceptance of constructive criticism -- Focus on what is best for the community and the project - -**Unacceptable behaviour:** -- Harassment, discrimination, or personal attacks -- Publishing others' private information without consent -- Trolling, insulting, or derogatory comments -- Any conduct that could reasonably be considered inappropriate in a professional setting - -## Enforcement - -Instances of unacceptable behaviour may be reported to [jonathan.jewell@open.ac.uk](mailto:jonathan.jewell@open.ac.uk). - -All complaints will be reviewed and investigated. The project team is obligated to maintain confidentiality with regard to the reporter. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1. diff --git a/packages/Skein.jl/CONTRIBUTING.md b/packages/Skein.jl/CONTRIBUTING.adoc similarity index 50% rename from packages/Skein.jl/CONTRIBUTING.md rename to packages/Skein.jl/CONTRIBUTING.adoc index 2b99468a9..253de440c 100644 --- a/packages/Skein.jl/CONTRIBUTING.md +++ b/packages/Skein.jl/CONTRIBUTING.adoc @@ -1,38 +1,38 @@ - - - -# Contributing to Skein.jl +== Contributing to Skein.jl Thank you for your interest in contributing to Skein.jl! -## Prerequisites +=== Prerequisites -- Julia 1.10 or later -- Git +* Julia 1.10 or later +* Git -## Development Setup +=== Development Setup -```bash +[source,bash] +---- git clone https://github.com/hyperpolymath/Skein.jl cd Skein.jl julia --project=. -e 'using Pkg; Pkg.instantiate()' -``` +---- -## Running Tests +=== Running Tests -```bash +[source,bash] +---- julia --project=. -e 'using Pkg; Pkg.test()' -``` +---- -## Running Benchmarks +=== Running Benchmarks -```bash +[source,bash] +---- julia --project=. benchmark/benchmarks.jl -``` +---- -## Repository Structure +=== Repository Structure -``` +.... Skein.jl/ ├── src/ # Package source │ ├── Skein.jl # Module entry point @@ -50,45 +50,48 @@ Skein.jl/ ├── .machine_readable/ # SCM metadata files ├── .bot_directives/ # Bot-specific rules └── contractiles/ # Operational framework -``` +.... -## How to Contribute +=== How to Contribute -### Reporting Bugs +==== Reporting Bugs -Open an issue with: -- Julia version (`versioninfo()`) -- Minimal reproduction case -- Expected vs actual behaviour +Open an issue with: - Julia version (`+versioninfo()+`) - Minimal +reproduction case - Expected vs actual behaviour -### Code Contributions +==== Code Contributions -1. Fork the repository -2. Create a feature branch (`git checkout -b feat/my-feature`) -3. Write tests for new functionality -4. Ensure all tests pass -5. Submit a pull request +[arabic] +. Fork the repository +. Create a feature branch (`+git checkout -b feat/my-feature+`) +. Write tests for new functionality +. Ensure all tests pass +. Submit a pull request -### Code Style +==== Code Style -- Follow Julia conventions (4-space indent) -- Add docstrings to all public functions -- Include SPDX header on new files: - ```julia - # SPDX-License-Identifier: CC-BY-SA-4.0 - # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) - ``` +* Follow Julia conventions (4-space indent) +* Add docstrings to all public functions +* Include SPDX header on new files: ++ +[source,julia] +---- +# SPDX-License-Identifier: CC-BY-SA-4.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +---- -### Adding Knot Invariants +==== Adding Knot Invariants To add a new invariant: -1. Add the computation function to `src/invariants.jl` -2. Add a column to the schema in `src/storage.jl` (with migration) -3. Update `store!`, `fetch_knot`, and `row_to_record` -4. Add query support in `src/query.jl` -5. Add tests and update the benchmark suite +[arabic] +. Add the computation function to `+src/invariants.jl+` +. Add a column to the schema in `+src/storage.jl+` (with migration) +. Update `+store!+`, `+fetch_knot+`, and `+row_to_record+` +. Add query support in `+src/query.jl+` +. Add tests and update the benchmark suite -## Licence +=== Licence -By contributing, you agree that your contributions will be licensed under MPL-2.0. +By contributing, you agree that your contributions will be licensed +under MPL-2.0. diff --git a/packages/Skein.jl/SECURITY.adoc b/packages/Skein.jl/SECURITY.adoc new file mode 100644 index 000000000..5f3bfd052 --- /dev/null +++ b/packages/Skein.jl/SECURITY.adoc @@ -0,0 +1,52 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability in Skein.jl, please report it +responsibly. + +*Preferred:* Use +https://github.com/hyperpolymath/Skein.jl/security/advisories/new[GitHub +Security Advisories] + +*Alternative:* Email jonathan.jewell@open.ac.uk + +==== What to Include + +* Description of the vulnerability +* Steps to reproduce +* Affected versions +* Potential impact assessment +* Suggested fix (if any) + +==== Response Timeline + +* *Acknowledgement:* Within 48 hours +* *Initial assessment:* Within 7 days +* *Fix or mitigation:* Within 30 days for critical issues + +=== Scope + +This policy covers: + +* The Skein.jl Julia package (src/, ext/) +* SQLite database operations and schema +* Data import/export functionality +* The KnotTheory.jl extension + +=== Safe Harbour + +We will not pursue legal action against security researchers who: + +* Act in good faith +* Avoid privacy violations and data destruction +* Report findings promptly +* Allow reasonable time for remediation before disclosure + +=== Security Best Practices + +When using Skein.jl: + +* Use `+:memory:+` databases for untrusted data +* Validate Gauss code input before storage +* Keep dependencies updated (`+Pkg.update()+`) diff --git a/packages/Skein.jl/SECURITY.md b/packages/Skein.jl/SECURITY.md deleted file mode 100644 index 8ffb99e00..000000000 --- a/packages/Skein.jl/SECURITY.md +++ /dev/null @@ -1,52 +0,0 @@ - - - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability in Skein.jl, please report it responsibly. - -**Preferred:** Use [GitHub Security Advisories](https://github.com/hyperpolymath/Skein.jl/security/advisories/new) - -**Alternative:** Email [jonathan.jewell@open.ac.uk](mailto:jonathan.jewell@open.ac.uk) - -### What to Include - -- Description of the vulnerability -- Steps to reproduce -- Affected versions -- Potential impact assessment -- Suggested fix (if any) - -### Response Timeline - -- **Acknowledgement:** Within 48 hours -- **Initial assessment:** Within 7 days -- **Fix or mitigation:** Within 30 days for critical issues - -## Scope - -This policy covers: - -- The Skein.jl Julia package (src/, ext/) -- SQLite database operations and schema -- Data import/export functionality -- The KnotTheory.jl extension - -## Safe Harbour - -We will not pursue legal action against security researchers who: - -- Act in good faith -- Avoid privacy violations and data destruction -- Report findings promptly -- Allow reasonable time for remediation before disclosure - -## Security Best Practices - -When using Skein.jl: - -- Use `:memory:` databases for untrusted data -- Validate Gauss code input before storage -- Keep dependencies updated (`Pkg.update()`) diff --git a/packages/Skein.jl/TOPOLOGY.md b/packages/Skein.jl/TOPOLOGY.adoc similarity index 89% rename from packages/Skein.jl/TOPOLOGY.md rename to packages/Skein.jl/TOPOLOGY.adoc index 07e5284d8..4a38b4d81 100644 --- a/packages/Skein.jl/TOPOLOGY.md +++ b/packages/Skein.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Skein.jl — Project Topology -# Skein.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE STORAGE @@ -71,11 +67,11 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ████████░░ ~75% Stable Database Layer -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Gauss Code ──────────► Skein DB API ───────────► Query DSL ▲ │ SQLite Backend ─────────────┘ ▼ @@ -84,16 +80,17 @@ SQLite Backend ─────────────┘ KnotTheory.jl ───────► Package Extension ──────────┤ │ Equivalence Checking -``` +.... -## 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/packages/SoftwareSovereign.jl/ABI-FFI-README.adoc b/packages/SoftwareSovereign.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..8b1378917 --- /dev/null +++ b/packages/SoftwareSovereign.jl/ABI-FFI-README.adoc @@ -0,0 +1 @@ + diff --git a/packages/SoftwareSovereign.jl/ABI-FFI-README.md b/packages/SoftwareSovereign.jl/ABI-FFI-README.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/packages/SoftwareSovereign.jl/TOPOLOGY.md b/packages/SoftwareSovereign.jl/TOPOLOGY.adoc similarity index 90% rename from packages/SoftwareSovereign.jl/TOPOLOGY.md rename to packages/SoftwareSovereign.jl/TOPOLOGY.adoc index 7222b5737..579f7b4ec 100644 --- a/packages/SoftwareSovereign.jl/TOPOLOGY.md +++ b/packages/SoftwareSovereign.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== SoftwareSovereign.jl — Project Topology -# SoftwareSovereign.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ SYSTEM PACKAGE MANAGERS │ ├─────────────────────────────────────────┤ @@ -48,11 +44,11 @@ │ gnome-extension/ │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ENGINE @@ -76,26 +72,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████░░░░░ ~50% Functional Policy Framework -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... License DB ──────────► Policy Engine ──────────► System Audit │ Package Managers ────► Enforcement ──────────────┤ │ Sentinel Service ────► User Interfaces ────────► COMPLETE -``` +.... -## 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/packages/TradeUnionism.jl/ABI-FFI-README.adoc b/packages/TradeUnionism.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..46c07c05c --- /dev/null +++ b/packages/TradeUnionism.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/%7B%7BOWNER%7D%7D/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/TradeUnionism.jl/ABI-FFI-README.md b/packages/TradeUnionism.jl/ABI-FFI-README.md deleted file mode 100644 index 320b3f6fa..000000000 --- a/packages/TradeUnionism.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/{{OWNER}}/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/TradeUnionism.jl/CHANGELOG.adoc b/packages/TradeUnionism.jl/CHANGELOG.adoc new file mode 100644 index 000000000..ca1c65289 --- /dev/null +++ b/packages/TradeUnionism.jl/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/packages/TradeUnionism.jl/CHANGELOG.md b/packages/TradeUnionism.jl/CHANGELOG.md deleted file mode 100644 index 810947691..000000000 --- a/packages/TradeUnionism.jl/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/packages/TradeUnionism.jl/CODE_OF_CONDUCT.adoc b/packages/TradeUnionism.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/TradeUnionism.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/TradeUnionism.jl/CODE_OF_CONDUCT.md b/packages/TradeUnionism.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/TradeUnionism.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/TradeUnionism.jl/CONTRIBUTING.adoc b/packages/TradeUnionism.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..ad866b5ab --- /dev/null +++ b/packages/TradeUnionism.jl/CONTRIBUTING.adoc @@ -0,0 +1,112 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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) ├── .machine_readable/ # ALL machine-readable +content (Perimeter 1) │ ├── *.a2ml # State files (STATE, META, +ECOSYSTEM, etc.) │ ├── bot_directives/ # Bot configs │ └── contractiles/ +# Policy contracts (k9, dust, lust, must, trust) ├── .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 — fallback (Perimeter 1) ├── guix.scm # Guix package — +primary (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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/TradeUnionism.jl/CONTRIBUTING.md b/packages/TradeUnionism.jl/CONTRIBUTING.md deleted file mode 100644 index 02758c676..000000000 --- a/packages/TradeUnionism.jl/CONTRIBUTING.md +++ /dev/null @@ -1,121 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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) -├── .machine_readable/ # ALL machine-readable content (Perimeter 1) -│ ├── *.a2ml # State files (STATE, META, ECOSYSTEM, etc.) -│ ├── bot_directives/ # Bot configs -│ └── contractiles/ # Policy contracts (k9, dust, lust, must, trust) -├── .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 — fallback (Perimeter 1) -├── guix.scm # Guix package — primary (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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/TradeUnionism.jl/GOVERNANCE.adoc b/packages/TradeUnionism.jl/GOVERNANCE.adoc new file mode 100644 index 000000000..6dddd7a45 --- /dev/null +++ b/packages/TradeUnionism.jl/GOVERNANCE.adoc @@ -0,0 +1,176 @@ +== Project Governance + +This document describes the governance model for *\{\{PROJECT_NAME}}*. + +''''' + +=== Project Governance Model + +\{\{PROJECT_NAME}} follows a *Benevolent Dictator For Life (BDFL)* +governance model. This model is well-suited for solo maintainers and +small project teams where rapid, consistent decision-making is more +valuable than formal consensus processes. + +The BDFL has final authority on all project decisions, including +technical direction, release schedules, contributor access, and +community standards. + +____ +*Transition clause:* When the core team exceeds three active +maintainers, this project should transition to a *consensus-based +governance model* with documented voting procedures. That transition +should itself be recorded as an Architecture Decision Record (ADR) in +`+docs/decisions/+`. +____ + +''''' + +=== Decision Making + +==== Day-to-day decisions + +* The BDFL makes final decisions on all matters. +* Routine decisions (bug fixes, dependency updates, minor improvements) +may be made by any maintainer with commit access. +* Maintainers are expected to use good judgement and seek input on +non-trivial changes. + +==== Proposing changes + +* Contributors can propose changes by opening issues or pull requests. +* Significant changes (new features, breaking changes, architectural +shifts) should be discussed in an issue before implementation begins. +* The BDFL will provide a clear accept/reject decision with reasoning. + +==== Architecture Decision Records (ADRs) + +* Significant technical decisions are documented as ADRs in +`+docs/decisions/+`. +* ADR statuses: `+proposed+`, `+accepted+`, `+deprecated+`, +`+superseded+`, `+rejected+`. +* ADRs provide a historical record of why decisions were made and what +alternatives were considered. +* See `+.machine_readable/META.a2ml+` for the machine-readable ADR +index. + +''''' + +=== Roles + +==== BDFL (Benevolent Dictator For Life) + +* The project creator and ultimate decision-maker. +* Sets the project’s technical direction and long-term vision. +* Has final say on all matters, including maintainer appointments and +removals. +* Responsible for ensuring the project adheres to RSR standards. + +==== Maintainer + +* Has commit access to the repository. +* Reviews and merges pull requests. +* Triages issues and manages releases. +* Upholds code quality, security standards, and the Code of Conduct. +* Listed in MAINTAINERS.md. + +==== Contributor + +* Anyone who submits pull requests, opens issues, or participates in +discussions. +* Does not have direct commit access. +* Contributions are reviewed by maintainers before merging. +* All contributors must follow the link:CODE_OF_CONDUCT.md[Code of +Conduct]. + +==== Bot + +* Automated agents managed via your bot orchestration system. +* Perform automated code review, security scanning, dependency updates, +and standards enforcement. +* Bot actions are subject to the same quality and review standards as +human contributions. +* Configure your bots in `+.machine_readable/bot_directives/+`. + +''''' + +=== Becoming a Maintainer + +A contributor may be nominated to become a maintainer when they +demonstrate: + +[arabic] +. *Sustained quality contributions* – a track record of well-crafted +pull requests that follow project conventions and require minimal +revision. +. *Understanding of RSR standards* – familiarity with the Repository +Structure Requirements, security policies, and CI/CD workflows used +across the project. +. *Constructive participation* – helpful issue triage, thoughtful code +review comments, and mentoring of other contributors. +. *Reliability* – consistent engagement over a meaningful period +(typically 3+ months of active contribution). + +==== Process + +[arabic] +. An existing maintainer nominates the candidate by opening a private +discussion with the BDFL. +. The BDFL reviews the candidate’s contribution history and community +interactions. +. The BDFL approves or declines the nomination, with reasoning provided +to the nominator. +. If approved, the new maintainer is added to MAINTAINERS.md and granted +appropriate repository access. + +''''' + +=== Removing a Maintainer + +A maintainer may be removed under the following circumstances: + +* *Inactivity*: No meaningful contributions or reviews for 12 or more +consecutive months. The maintainer will be contacted before removal and +offered the option to move to emeritus status voluntarily. +* *Code of Conduct violation*: Behaviour that violates the +link:CODE_OF_CONDUCT.md[Code of Conduct], as determined through the +enforcement process described therein. +* *BDFL discretion*: The BDFL may remove a maintainer for other reasons +(e.g., repeated disregard for project standards, loss of trust). +Reasoning will be documented privately. + +Removed maintainers are moved to the Emeritus section of MAINTAINERS.md +unless removal was due to a serious Code of Conduct violation. + +''''' + +=== Code of Conduct + +All participants in this project are expected to follow the +link:CODE_OF_CONDUCT.md[Code of Conduct]. The Code of Conduct applies to +all project spaces, including issues, pull requests, discussions, and +any forum where the project is represented. + +Enforcement of the Code of Conduct is described in that document. The +BDFL serves as the final arbiter in conduct disputes. + +''''' + +=== Amendments + +This governance document may be amended by the BDFL at any time. All +amendments will be: + +[arabic] +. Documented as an ADR in `+docs/decisions/+` explaining the rationale +for the change. +. Committed to the repository with a clear commit message. +. Communicated to existing maintainers and contributors via the +project’s usual channels. + +Substantive changes (e.g., changing the governance model itself) should +be discussed with the community before adoption, even though the BDFL +retains final authority. + +''''' + +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/TradeUnionism.jl/GOVERNANCE.md b/packages/TradeUnionism.jl/GOVERNANCE.md deleted file mode 100644 index 5f082df92..000000000 --- a/packages/TradeUnionism.jl/GOVERNANCE.md +++ /dev/null @@ -1,158 +0,0 @@ - - -# Project Governance - -This document describes the governance model for **{{PROJECT_NAME}}**. - ---- - -## Project Governance Model - -{{PROJECT_NAME}} follows a **Benevolent Dictator For Life (BDFL)** governance model. -This model is well-suited for solo maintainers and small project teams where rapid, -consistent decision-making is more valuable than formal consensus processes. - -The BDFL has final authority on all project decisions, including technical direction, -release schedules, contributor access, and community standards. - -> **Transition clause:** When the core team exceeds three active maintainers, this -> project should transition to a **consensus-based governance model** with documented -> voting procedures. That transition should itself be recorded as an Architecture -> Decision Record (ADR) in `docs/decisions/`. - ---- - -## Decision Making - -### Day-to-day decisions - -- The BDFL makes final decisions on all matters. -- Routine decisions (bug fixes, dependency updates, minor improvements) may be made - by any maintainer with commit access. -- Maintainers are expected to use good judgement and seek input on non-trivial changes. - -### Proposing changes - -- Contributors can propose changes by opening issues or pull requests. -- Significant changes (new features, breaking changes, architectural shifts) should - be discussed in an issue before implementation begins. -- The BDFL will provide a clear accept/reject decision with reasoning. - -### Architecture Decision Records (ADRs) - -- Significant technical decisions are documented as ADRs in `docs/decisions/`. -- ADR statuses: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`. -- ADRs provide a historical record of why decisions were made and what alternatives - were considered. -- See `.machine_readable/META.a2ml` for the machine-readable ADR index. - ---- - -## Roles - -### BDFL (Benevolent Dictator For Life) - -- The project creator and ultimate decision-maker. -- Sets the project's technical direction and long-term vision. -- Has final say on all matters, including maintainer appointments and removals. -- Responsible for ensuring the project adheres to RSR standards. - -### Maintainer - -- Has commit access to the repository. -- Reviews and merges pull requests. -- Triages issues and manages releases. -- Upholds code quality, security standards, and the Code of Conduct. -- Listed in [MAINTAINERS.md](MAINTAINERS.md). - -### Contributor - -- Anyone who submits pull requests, opens issues, or participates in discussions. -- Does not have direct commit access. -- Contributions are reviewed by maintainers before merging. -- All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). - -### Bot - -- Automated agents managed via your bot orchestration system. -- Perform automated code review, security scanning, dependency updates, and - standards enforcement. -- Bot actions are subject to the same quality and review standards as human - contributions. -- Configure your bots in `.machine_readable/bot_directives/`. - ---- - -## Becoming a Maintainer - -A contributor may be nominated to become a maintainer when they demonstrate: - -1. **Sustained quality contributions** -- a track record of well-crafted pull requests - that follow project conventions and require minimal revision. -2. **Understanding of RSR standards** -- familiarity with the Repository Structure - Requirements, security policies, and CI/CD workflows used across the project. -3. **Constructive participation** -- helpful issue triage, thoughtful code review - comments, and mentoring of other contributors. -4. **Reliability** -- consistent engagement over a meaningful period (typically 3+ - months of active contribution). - -### Process - -1. An existing maintainer nominates the candidate by opening a private discussion - with the BDFL. -2. The BDFL reviews the candidate's contribution history and community interactions. -3. The BDFL approves or declines the nomination, with reasoning provided to the - nominator. -4. If approved, the new maintainer is added to [MAINTAINERS.md](MAINTAINERS.md) and - granted appropriate repository access. - ---- - -## Removing a Maintainer - -A maintainer may be removed under the following circumstances: - -- **Inactivity**: No meaningful contributions or reviews for 12 or more consecutive - months. The maintainer will be contacted before removal and offered the option to - move to emeritus status voluntarily. -- **Code of Conduct violation**: Behaviour that violates the - [Code of Conduct](CODE_OF_CONDUCT.md), as determined through the enforcement - process described therein. -- **BDFL discretion**: The BDFL may remove a maintainer for other reasons (e.g., - repeated disregard for project standards, loss of trust). Reasoning will be - documented privately. - -Removed maintainers are moved to the Emeritus section of -[MAINTAINERS.md](MAINTAINERS.md) unless removal was due to a serious Code of Conduct -violation. - ---- - -## Code of Conduct - -All participants in this project are expected to follow the -[Code of Conduct](CODE_OF_CONDUCT.md). The Code of Conduct applies to all project -spaces, including issues, pull requests, discussions, and any forum where the project -is represented. - -Enforcement of the Code of Conduct is described in that document. The BDFL serves as -the final arbiter in conduct disputes. - ---- - -## Amendments - -This governance document may be amended by the BDFL at any time. All amendments will -be: - -1. Documented as an ADR in `docs/decisions/` explaining the rationale for the change. -2. Committed to the repository with a clear commit message. -3. Communicated to existing maintainers and contributors via the project's usual - channels. - -Substantive changes (e.g., changing the governance model itself) should be discussed -with the community before adoption, even though the BDFL retains final authority. - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/TradeUnionism.jl/MAINTAINERS.adoc b/packages/TradeUnionism.jl/MAINTAINERS.adoc index d829dd959..f3a0e022b 100644 --- a/packages/TradeUnionism.jl/MAINTAINERS.adoc +++ b/packages/TradeUnionism.jl/MAINTAINERS.adoc @@ -1,47 +1,43 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Maintainers -:toc: preamble +== Maintainers -This document lists the maintainers of this project and their responsibilities. +This document lists the current and former maintainers of +*\{\{PROJECT_NAME}}*. -== Current Maintainers +''''' -[cols="2,3,2",options="header"] -|=== -| Name | Role | Contact +=== Current Maintainers -| {{AUTHOR}} -| Lead Maintainer -| https://github.com/{{OWNER}}[@{{OWNER}}] +[width="100%",cols="24%,29%,22%,25%",options="header",] +|=== +|Name |GitHub |Role |Since +|\{\{AUTHOR}} |https://github.com/%7B%7BOWNER%7D%7D[@\{OWNER}] |BDFL +|\{\{CURRENT_DATE}} |=== -== Responsibilities - -Maintainers are responsible for: - -* Reviewing and merging pull requests -* Triaging issues and feature requests -* Ensuring code quality and security standards -* Managing releases and versioning -* Upholding the project's code of conduct +''''' -== Becoming a Maintainer +=== How to Become a Maintainer -Contributors who demonstrate: +Contributors who demonstrate sustained, high-quality contributions and a +solid understanding of the project’s standards and goals may be +nominated to become maintainers. The full criteria and process are +described in GOVERNANCE.md. If you are interested, the best path is to +start contributing consistently and engage constructively in issues and +code reviews. -* Consistent, high-quality contributions -* Understanding of the project's goals and standards -* Constructive participation in discussions -* Commitment to the project's long-term health +''''' -May be invited to become maintainers at the discretion of existing maintainers. +=== Emeritus -== Decision Making +Former maintainers who have stepped back from active maintenance. We are +grateful for their contributions. -* Routine decisions (bug fixes, minor improvements) can be made by any maintainer -* Significant changes require discussion and consensus among maintainers -* Breaking changes or major features should be discussed in issues before implementation +[cols=",,,",options="header",] +|=== +|Name |GitHub |Role |Active +|_None yet_ | | | +|=== -== Contact +''''' -For questions about project governance, open an issue or contact the maintainers listed above. +Copyright (c) \{\{CURRENT_YEAR}} \{\{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/TradeUnionism.jl/MAINTAINERS.md b/packages/TradeUnionism.jl/MAINTAINERS.md deleted file mode 100644 index 32b92cc4a..000000000 --- a/packages/TradeUnionism.jl/MAINTAINERS.md +++ /dev/null @@ -1,38 +0,0 @@ - - -# Maintainers - -This document lists the current and former maintainers of **{{PROJECT_NAME}}**. - ---- - -## Current Maintainers - -| Name | GitHub | Role | Since | -|------|--------|------|-------| -| {{AUTHOR}} | [@{{OWNER}}](https://github.com/{{OWNER}}) | BDFL | {{CURRENT_DATE}} | - ---- - -## How to Become a Maintainer - -Contributors who demonstrate sustained, high-quality contributions and a solid -understanding of the project's standards and goals may be nominated to become -maintainers. The full criteria and process are described in -[GOVERNANCE.md](GOVERNANCE.md). If you are interested, the best path is to start -contributing consistently and engage constructively in issues and code reviews. - ---- - -## Emeritus - -Former maintainers who have stepped back from active maintenance. We are grateful -for their contributions. - -| Name | GitHub | Role | Active | -|------|--------|------|--------| -| *None yet* | | | | - ---- - -Copyright (c) {{CURRENT_YEAR}} {{OWNER}}. Licensed under MPL-2.0. diff --git a/packages/TradeUnionism.jl/PLACEHOLDERS.adoc b/packages/TradeUnionism.jl/PLACEHOLDERS.adoc new file mode 100644 index 000000000..1ec75339b --- /dev/null +++ b/packages/TradeUnionism.jl/PLACEHOLDERS.adoc @@ -0,0 +1,191 @@ +== Template Placeholders + +All placeholders in this template follow the `+{{PLACEHOLDER}}+` +pattern. After cloning, replace them with your project-specific values. + +=== Recommended: Interactive Bootstrap + +[source,bash] +---- +just init +---- + +This interactively prompts for all values, replaces every placeholder, +validates the result, and runs k9-svc checks if available. + +=== Manual Replace + +[source,bash] +---- +# If you prefer manual replacement (run from repo root) + +sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) +sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) +sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) +sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) +sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) +sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) +sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) +sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) +sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) +---- + +=== Placeholder Reference + +==== Author & Copyright + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{AUTHOR}}+` |Full legal name |`+Jane Doe+` |SPDX headers (all +files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md + +|`+{{AUTHOR_EMAIL}}+` |Primary contact email |`+jane@example.org+` |SPDX +headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt + +|`+{{AUTHOR_EMAIL_ALT}}+` |Previous/secondary email (for .mailmap) +|`+old@example.com+` |.mailmap + +|`+{{AUTHOR_ORG}}+` |Author’s organization/affiliation +|`+Acme University+` |project-metadata.k9.ncl + +|`+{{AUTHOR_LAST}}+` |Author surname (for citations) |`+Doe+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_FIRST}}+` |Author first name (for citations) |`+Jane+` +|docs/CITATIONS.adoc + +|`+{{AUTHOR_INITIALS}}+` |Author initials (for citations) |`+J.+` +|docs/CITATIONS.adoc +|=== + +==== Project Identity + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{PROJECT_NAME}}+` |Human-readable project name |`+My Project+` +|SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, +GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json + +|`+{{PROJECT_DESCRIPTION}}+` |One-line description |`+A tool for X+` +|flake.nix + +|`+{{PROJECT}}+` |Uppercase identifier (for Idris2 modules, C macros) +|`+MY_PROJECT+` |ABI-FFI-README.md, src/abi/_.idr, ffi/zig/_.zig + +|`+{{project}}+` |Lowercase identifier (for C symbols, filenames) +|`+my_project+` |ABI-FFI-README.md, ffi/zig/*.zig + +|`+{{REPO}}+` |Repository name (slug) |`+my-project+` |CONTRIBUTING.md, +SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml + +|`+{{OWNER}}+` |GitHub/GitLab org or username |`+my-org+` |SPDX headers, +CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, +mirror.yml, cliff.toml + +|`+{{FORGE}}+` |Git forge domain |`+github.com+` |CONTRIBUTING.md +|=== + +==== Dates + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{CURRENT_YEAR}}+` |Current year |`+2026+` |SPDX headers (all files), +GOVERNANCE.md, MAINTAINERS.md + +|`+{{CURRENT_DATE}}+` |Current date (ISO) |`+2026-02-14+` |STATE.a2ml, +MAINTAINERS.md + +|`+{{DATE}}+` |Last updated date |`+2026-02-14+` |TOPOLOGY.md, +THREAT-MODEL.md +|=== + +==== Contact & Security + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{SECURITY_EMAIL}}+` |Security contact email +|`+security@example.org+` |SECURITY.md + +|`+{{PGP_FINGERPRINT}}+` |40-char PGP fingerprint |`+ABCD 1234 ...+` +|SECURITY.md + +|`+{{PGP_KEY_URL}}+` |URL to public PGP key +|`+https://keys.openpgp.org/...+` |SECURITY.md + +|`+{{WEBSITE}}+` |Project website |`+https://example.org+` |SECURITY.md + +|`+{{CONDUCT_EMAIL}}+` |Conduct reports email |`+conduct@example.org+` +|CODE_OF_CONDUCT.md + +|`+{{CONDUCT_TEAM}}+` |Conduct committee name +|`+Code of Conduct Committee+` |CODE_OF_CONDUCT.md + +|`+{{RESPONSE_TIME}}+` |SLA for initial response |`+48 hours+` +|CODE_OF_CONDUCT.md +|=== + +==== Git + +[cols=",,,",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{MAIN_BRANCH}}+` |Main branch name |`+main+` |CONTRIBUTING.md +|=== + +==== Build + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+{{LICENSE}}+` |License name |`+MPL-2.0+` |ABI-FFI-README.md + +|`+{{PROJECT_PURPOSE}}+` |One-line project description +|`+FFI bridges between languages+` |STATE.a2ml +|=== + +==== AI Manifest + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Placeholder |Description |Example |Files +|`+[YOUR-REPO-NAME]+` |Repository name |`+my-project+` +|0-AI-MANIFEST.a2ml + +|`+[DATE]+` |Creation date |`+2026-02-14+` |0-AI-MANIFEST.a2ml + +|`+[YOUR-NAME/ORG]+` |Maintainer name |`+hyperpolymath+` +|0-AI-MANIFEST.a2ml +|=== + +=== Deletion Markers + +Some files contain deletion instructions: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Marker |Meaning |File +|`+{{~ ... ~}}+` |Delete this entire line after reading +|ABI-FFI-README.md (line 1) +|=== + +=== Verification + +After replacing all placeholders, verify none remain: + +[source,bash] +---- +grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ + --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ + --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ + --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ + --include='*.json' --include='Containerfile' --include='dep5' \ + | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' +---- + +If the above command produces no output, all placeholders have been +replaced. diff --git a/packages/TradeUnionism.jl/PLACEHOLDERS.md b/packages/TradeUnionism.jl/PLACEHOLDERS.md deleted file mode 100644 index b6c9d28cc..000000000 --- a/packages/TradeUnionism.jl/PLACEHOLDERS.md +++ /dev/null @@ -1,120 +0,0 @@ -# Template Placeholders - -All placeholders in this template follow the `{{PLACEHOLDER}}` pattern. -After cloning, replace them with your project-specific values. - -## Recommended: Interactive Bootstrap - -```bash -just init -``` - -This interactively prompts for all values, replaces every placeholder, -validates the result, and runs k9-svc checks if available. - -## Manual Replace - -```bash -# If you prefer manual replacement (run from repo root) - -sed -i 's/{{AUTHOR}}/Jane Doe/g' $(grep -rl '{{AUTHOR}}' .) -sed -i 's/{{AUTHOR_EMAIL}}/jane@example.org/g' $(grep -rl '{{AUTHOR_EMAIL}}' .) -sed -i 's/{{OWNER}}/my-org/g' $(grep -rl '{{OWNER}}' .) -sed -i 's/{{PROJECT_NAME}}/my-project/g' $(grep -rl '{{PROJECT_NAME}}' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) -sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) -sed -i 's/{{REPO}}/my-project/g' $(grep -rl '{{REPO}}' .) -sed -i 's/{{FORGE}}/github.com/g' $(grep -rl '{{FORGE}}' .) -sed -i "s/{{CURRENT_YEAR}}/$(date +%Y)/g" $(grep -rl '{{CURRENT_YEAR}}' .) -sed -i "s/{{CURRENT_DATE}}/$(date +%Y-%m-%d)/g" $(grep -rl '{{CURRENT_DATE}}' .) -``` - -## Placeholder Reference - -### Author & Copyright - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{AUTHOR}}` | Full legal name | `Jane Doe` | SPDX headers (all files), MAINTAINERS.md, .mailmap, .reuse/dep5, docs/AI-CONVENTIONS.md | -| `{{AUTHOR_EMAIL}}` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | -| `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | -| `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | - -### Project Identity - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{PROJECT_NAME}}` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | -| `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | -| `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | -| `{{REPO}}` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | -| `{{OWNER}}` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | -| `{{FORGE}}` | Git forge domain | `github.com` | CONTRIBUTING.md | - -### Dates - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{CURRENT_YEAR}}` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | -| `{{CURRENT_DATE}}` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | - -### Contact & Security - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{SECURITY_EMAIL}}` | Security contact email | `security@example.org` | SECURITY.md | -| `{{PGP_FINGERPRINT}}` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | -| `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | -| `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | -| `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | -| `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | - -### Git - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{MAIN_BRANCH}}` | Main branch name | `main` | CONTRIBUTING.md | - -### Build - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `{{LICENSE}}` | License name | `MPL-2.0` | ABI-FFI-README.md | -| `{{PROJECT_PURPOSE}}` | One-line project description | `FFI bridges between languages` | STATE.a2ml | - -### AI Manifest - -| Placeholder | Description | Example | Files | -|---|---|---|---| -| `[YOUR-REPO-NAME]` | Repository name | `my-project` | 0-AI-MANIFEST.a2ml | -| `[DATE]` | Creation date | `2026-02-14` | 0-AI-MANIFEST.a2ml | -| `[YOUR-NAME/ORG]` | Maintainer name | `hyperpolymath` | 0-AI-MANIFEST.a2ml | - -## Deletion Markers - -Some files contain deletion instructions: - -| Marker | Meaning | File | -|---|---|---| -| `{{~ ... ~}}` | Delete this entire line after reading | ABI-FFI-README.md (line 1) | - -## Verification - -After replacing all placeholders, verify none remain: - -```bash -grep -rn '{{' . --include='*.md' --include='*.adoc' --include='*.a2ml' \ - --include='*.scm' --include='*.idr' --include='*.zig' --include='*.res' \ - --include='Justfile' --include='*.nix' --include='*.toml' --include='*.yml' \ - --include='*.yaml' --include='*.hs' --include='*.ncl' --include='*.txt' \ - --include='*.json' --include='Containerfile' --include='dep5' \ - | grep -v 'PLACEHOLDERS.md' | grep -v 'node_modules' -``` - -If the above command produces no output, all placeholders have been replaced. diff --git a/packages/TradeUnionism.jl/SECURITY.adoc b/packages/TradeUnionism.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/TradeUnionism.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/TradeUnionism.jl/SECURITY.md b/packages/TradeUnionism.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/TradeUnionism.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/TradeUnionism.jl/TOPOLOGY.md b/packages/TradeUnionism.jl/TOPOLOGY.adoc similarity index 89% rename from packages/TradeUnionism.jl/TOPOLOGY.md rename to packages/TradeUnionism.jl/TOPOLOGY.adoc index 720855386..f17adce01 100644 --- a/packages/TradeUnionism.jl/TOPOLOGY.md +++ b/packages/TradeUnionism.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== TradeUnionist.jl — Project Topology -# TradeUnionist.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / STAKEHOLDERS │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE ORGANIZING @@ -71,26 +67,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ███████░░░ ~70% Functional Prototype -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Workplace Mapping ──────► Member Engagement ──────► Mobilization │ Grievance Pipeline ──────► Contract Knowledge ─────┤ │ Bargaining Support ──────► Strategy Planning ─────► COMPLETE -``` +.... -## 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/packages/TradeUnionism.jl/docs/AI-CONVENTIONS.adoc b/packages/TradeUnionism.jl/docs/AI-CONVENTIONS.adoc new file mode 100644 index 000000000..ba7e4ae74 --- /dev/null +++ b/packages/TradeUnionism.jl/docs/AI-CONVENTIONS.adoc @@ -0,0 +1,81 @@ +== AI Conventions (Authoritative Source) + +All AI coding agents working in this repository MUST follow these rules. +Per-tool config files (.cursorrules, .clinerules, etc.) reference this +document. + +=== Session Startup + +[arabic] +. Read `+0-AI-MANIFEST.a2ml+` FIRST (mandatory gatekeeper). +. Read `+.machine_readable/STATE.a2ml+` for current status and blockers. +. Read `+.machine_readable/AGENTIC.a2ml+` for agent constraints. + +=== License + +* All original code: *MPL-2.0* +* Fallback (platform-required only): MPL-2.0 with comment explaining +why. +* NEVER use AGPL-3.0. +* Preserve third-party licenses verbatim. +* Every source file needs `+# SPDX-License-Identifier: CC-BY-SA-4.0+`. + +=== Author Attribution + +* Name: *\{\{AUTHOR}}* +* Email: *\{\{AUTHOR_EMAIL}}* +* Copyright: +`+Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>+` + +=== State Files + +State/metadata files (.a2ml) belong in `+.machine_readable/+` ONLY. +NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, +NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. + +=== Banned Patterns + +[width="100%",cols="14%,50%,36%",options="header",] +|=== +|Language |Banned |Reason +|Idris2 |`+believe_me+`, `+assert_total+` |Unsound escape hatches +|Haskell |`+unsafeCoerce+`, `+unsafePerformIO+` |Breaks type safety +|OCaml |`+Obj.magic+`, `+Obj.repr+`, `+Obj.obj+` |Unsafe casting +|Coq |`+Admitted+` |Unproven assumption +|Lean |`+sorry+` |Unproven assumption +|Rust |`+transmute+` (unless FFI + SAFETY:) |Unsound reinterpret +|=== + +=== Banned Languages + +[cols=",",options="header",] +|=== +|Banned |Use Instead +|TypeScript |ReScript +|Node.js / npm / bun |Deno +|Go |Rust +|Python |Julia / Rust +|=== + +=== Container Standard + +* Runtime: *Podman* (never Docker). +* File: *Containerfile* (never Dockerfile). +* Base images: `+cgr.dev/chainguard/wolfi-base:latest+` or +`+cgr.dev/chainguard/static:latest+`. + +=== ABI/FFI Standard + +* ABI definitions: *Idris2* with dependent types (`+src/abi/+`). +* FFI implementation: *Zig* with C ABI compatibility (`+ffi/zig/+`). +* Generated C headers: `+generated/abi/+`. + +=== Build System + +Use `+just+` (Justfile) for all build, test, lint, and format tasks. + +=== References + +* `+0-AI-MANIFEST.a2ml+` – universal AI entry point +* `+.machine_readable/AGENTIC.a2ml+` – agent permissions and constraints +* `+.machine_readable/STATE.a2ml+` – current project state diff --git a/packages/TradeUnionism.jl/docs/AI-CONVENTIONS.md b/packages/TradeUnionism.jl/docs/AI-CONVENTIONS.md deleted file mode 100644 index 37f594d12..000000000 --- a/packages/TradeUnionism.jl/docs/AI-CONVENTIONS.md +++ /dev/null @@ -1,75 +0,0 @@ - - - -# AI Conventions (Authoritative Source) - -All AI coding agents working in this repository MUST follow these rules. -Per-tool config files (.cursorrules, .clinerules, etc.) reference this document. - -## Session Startup - -1. Read `0-AI-MANIFEST.a2ml` FIRST (mandatory gatekeeper). -2. Read `.machine_readable/STATE.a2ml` for current status and blockers. -3. Read `.machine_readable/AGENTIC.a2ml` for agent constraints. - -## License - -- All original code: **MPL-2.0** -- Fallback (platform-required only): MPL-2.0 with comment explaining why. -- NEVER use AGPL-3.0. -- Preserve third-party licenses verbatim. -- Every source file needs `# SPDX-License-Identifier: CC-BY-SA-4.0`. - -## Author Attribution - -- Name: **{{AUTHOR}}** -- Email: **{{AUTHOR_EMAIL}}** -- Copyright: `Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}>` - -## State Files - -State/metadata files (.a2ml) belong in `.machine_readable/` ONLY. -NEVER create STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml, AGENTIC.a2ml, -NEUROSYM.a2ml, or PLAYBOOK.a2ml in the repository root. - -## Banned Patterns - -| Language | Banned | Reason | -|----------|-------------------------------------|---------------------------| -| Idris2 | `believe_me`, `assert_total` | Unsound escape hatches | -| Haskell | `unsafeCoerce`, `unsafePerformIO` | Breaks type safety | -| OCaml | `Obj.magic`, `Obj.repr`, `Obj.obj` | Unsafe casting | -| Coq | `Admitted` | Unproven assumption | -| Lean | `sorry` | Unproven assumption | -| Rust | `transmute` (unless FFI + SAFETY:) | Unsound reinterpret | - -## Banned Languages - -| Banned | Use Instead | -|---------------------|--------------------| -| TypeScript | ReScript | -| Node.js / npm / bun | Deno | -| Go | Rust | -| Python | Julia / Rust | - -## Container Standard - -- Runtime: **Podman** (never Docker). -- File: **Containerfile** (never Dockerfile). -- Base images: `cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`. - -## ABI/FFI Standard - -- ABI definitions: **Idris2** with dependent types (`src/abi/`). -- FFI implementation: **Zig** with C ABI compatibility (`ffi/zig/`). -- Generated C headers: `generated/abi/`. - -## Build System - -Use `just` (Justfile) for all build, test, lint, and format tasks. - -## References - -- `0-AI-MANIFEST.a2ml` -- universal AI entry point -- `.machine_readable/AGENTIC.a2ml` -- agent permissions and constraints -- `.machine_readable/STATE.a2ml` -- current project state diff --git a/packages/TradeUnionism.jl/docs/QUICKSTART.adoc b/packages/TradeUnionism.jl/docs/QUICKSTART.adoc new file mode 100644 index 000000000..f000d4a13 --- /dev/null +++ b/packages/TradeUnionism.jl/docs/QUICKSTART.adoc @@ -0,0 +1,70 @@ +== Quickstart + +Get up and running in 60 seconds. + +=== Prerequisites + +* https://git-scm.com/[Git] 2.40+ +* https://github.com/casey/just[just] (command runner) +* Your language toolchain (see `+Justfile+` for details) + +=== From Template (New Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo my-project +cd my-project +rm -rf .git && git init -b main +just init # interactive placeholder replacement +---- + +=== Clone and Setup (Existing Project) + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/{{REPO}}.git +cd {{REPO}} +just deps +---- + +=== Build and Test + +[source,bash] +---- +just build +just test +---- + +=== Verify Everything Works + +[source,bash] +---- +just check +---- + +=== Project Structure + +.... +src/ # Source code +tests/ # Test suite +benches/ # Benchmarks +docs/ # Documentation +.github/ # CI/CD workflows +.... + +=== What Next? + +* Browse the link:.[docs/] for architecture and conventions +* Run `+just --list+` to see all available commands +* Read link:../CONTRIBUTING.md[CONTRIBUTING.md] when you are ready to +contribute + +=== Troubleshooting + +If `+just deps+` fails, ensure your toolchain version matches the +project requirements listed in the `+Justfile+` or +`+.machine_readable/ECOSYSTEM.a2ml+`. + +Open a +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +if you get stuck. diff --git a/packages/TradeUnionism.jl/docs/QUICKSTART.md b/packages/TradeUnionism.jl/docs/QUICKSTART.md deleted file mode 100644 index 724d8e111..000000000 --- a/packages/TradeUnionism.jl/docs/QUICKSTART.md +++ /dev/null @@ -1,64 +0,0 @@ - -# Quickstart - -Get up and running in 60 seconds. - -## Prerequisites - -- [Git](https://git-scm.com/) 2.40+ -- [just](https://github.com/casey/just) (command runner) -- Your language toolchain (see `Justfile` for details) - -## From Template (New Project) - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo my-project -cd my-project -rm -rf .git && git init -b main -just init # interactive placeholder replacement -``` - -## Clone and Setup (Existing Project) - -```bash -git clone https://github.com/{{OWNER}}/{{REPO}}.git -cd {{REPO}} -just deps -``` - -## Build and Test - -```bash -just build -just test -``` - -## Verify Everything Works - -```bash -just check -``` - -## Project Structure - -``` -src/ # Source code -tests/ # Test suite -benches/ # Benchmarks -docs/ # Documentation -.github/ # CI/CD workflows -``` - -## What Next? - -- Browse the [docs/](.) for architecture and conventions -- Run `just --list` to see all available commands -- Read [CONTRIBUTING.md](../CONTRIBUTING.md) when you are ready to contribute - -## Troubleshooting - -If `just deps` fails, ensure your toolchain version matches the -project requirements listed in the `Justfile` or `.machine_readable/ECOSYSTEM.a2ml`. - -Open a [Discussion](https://github.com/{{OWNER}}/{{REPO}}/discussions) -if you get stuck. diff --git a/packages/TradeUnionism.jl/docs/THREAT-MODEL.adoc b/packages/TradeUnionism.jl/docs/THREAT-MODEL.adoc new file mode 100644 index 000000000..35aa8cc8e --- /dev/null +++ b/packages/TradeUnionism.jl/docs/THREAT-MODEL.adoc @@ -0,0 +1,254 @@ +== Threat Model: \{\{PROJECT_NAME}} + +=== Document Info + +[cols=",",options="header",] +|=== +|Field |Value +|Project |\{\{PROJECT_NAME}} +|Version |1.0 +|Last Reviewed |\{\{DATE}} +|Author |\{\{AUTHOR}} +|Methodology |STRIDE +|=== + +=== Scope + +==== In Scope + +* Application source code and build pipeline +* CI/CD workflows (GitHub Actions) +* Container images and runtime environment +* Secrets and credential management +* Dependencies (direct and transitive) +* Deployment artifacts (binaries, containers, SBOM) + +==== Out of Scope + +* Physical security of hosting infrastructure +* GitHub/GitLab platform-level vulnerabilities +* End-user device security +* Social engineering attacks against maintainers (handled by org policy) + +=== System Overview + +Brief description of \{\{PROJECT_NAME}} and its architecture. + +____ +See link:../TOPOLOGY.md[TOPOLOGY.md] for the full architecture diagram +and completion dashboard. +____ + +=== Assets + +[width="100%",cols="25%,16%,13%,46%",options="header",] +|=== +|Asset |Classification |Owner |Notes +|Source code |Internal |Maintainers |Public repos are still +internal-integrity + +|Signing keys |Restricted |Release lead |Signing keys (e.g., Ed25519), +GPG keys + +|CI/CD secrets |Restricted |Maintainers |GITHUB_TOKEN, deploy tokens, +PATs + +|User/contributor data |Confidential |Org |Emails, contributor identity + +|Build artifacts |Internal |CI pipeline |Binaries, WASM bundles + +|Container images |Internal |CI pipeline |Chainguard-based, signed via +image signing tool + +|SBOM / provenance |Public |CI pipeline |SLSA attestations + +|Dependencies |Public |Lockfile |Cargo.lock, deno.lock, gleam.toml + +|Infrastructure config |Confidential |Maintainers |Containerfiles, +compose files, orchestration config +|=== + +=== Trust Boundaries + +[width="100%",cols="35%,32%,33%",options="header",] +|=== +|Boundary |From (Lower Trust) |To (Higher Trust) +|Pull request submission |External contributor |Repository codebase + +|CI/CD workflow execution |Workflow definition |Runner with secrets +access + +|Container build boundary |Build stage |Runtime stage + +|External API calls |Third-party service |Application internals + +|User input (CLI/Web) |End user |Application logic + +|Dependency resolution |Package registry |Build environment + +|Forge mirroring |GitHub |GitLab / Bitbucket +|=== + +=== Threat Actors + +[width="100%",cols="39%,44%,17%",options="header",] +|=== +|Actor |Motivation |Capability +|Script kiddie |Vandalism, clout |Low +|Disgruntled contributor |Sabotage, backdoor insertion |Medium +|Supply chain attacker |Wide-impact compromise |High +|Nation state |Espionage, disruption |Very High +|Automated bot |Credential stuffing, spam PRs |Low-Medium +|=== + +=== STRIDE Analysis + +==== Spoofing + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unsigned commits impersonate maintainer |Source code |Medium |High +|High |Require GPG-signed commits; vigilant code review + +|Forged bot actions (automated agents) |CI/CD pipeline |Low |High +|Medium |Bot tokens scoped minimally; audit bot activity + +|Spoofed package registry identity |Dependencies |Low |High |Medium |Pin +dependencies by hash; verify provenance +|=== + +==== Tampering + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Malicious pull request |Source code |Medium |High |High |Branch +protection; required reviews; CodeQL + +|Dependency poisoning (typosquat) |Dependencies |Medium |High |High +|Lockfiles; secret-scanner; security scans + +|Tampered container base image |Container images |Low |High |Medium +|Chainguard images; image signing verification + +|Workflow file modification |CI/CD pipeline |Low |High |Medium +|CODEOWNERS on .github/; workflow-linter +|=== + +==== Repudiation + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Unlogged deployment |Build artifacts |Medium |Medium |Medium |SLSA +provenance; deployment audit trail + +|Denied merge of vulnerable code |Source code |Low |Medium |Low |Git +history is immutable; signed commits + +|Secret rotation without record |CI/CD secrets |Low |Low |Low |Secret +rotation logged in STATE.a2ml +|=== + +==== Information Disclosure + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Secrets leaked in git history |CI/CD secrets |Medium |High |High +|TruffleHog in CI; secret-scanner workflow + +|Verbose error messages in prod |Application logic |Medium |Medium +|Medium |Sanitize outputs; structured logging + +|SBOM reveals internal structure |Infrastructure |Low |Low |Low +|Accepted risk; SBOM is intentionally public +|=== + +==== Denial of Service + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|CI resource exhaustion (fork bomb in PR) |CI/CD pipeline |Medium +|Medium |Medium |Concurrency limits; timeout on workflows + +|Spam issues/PRs flooding triage |Maintainer time |Medium |Low |Low +|GitHub rate limits; bot auto-close stale + +|Large binary commits bloating repo |Source code |Low |Medium |Low +|.gitattributes LFS policy; pre-commit hooks +|=== + +==== Elevation of Privilege + +[width="100%",cols="28%,14%,9%,6%,6%,37%",options="header",] +|=== +|Threat |Affected Asset |Likelihood |Impact |Risk |Mitigation +|Workflow injection via PR title/body |CI/CD pipeline |Medium |High +|High |Never interpolate PR fields in `+run:+`; use env vars + +|GITHUB_TOKEN over-scoped |CI/CD secrets |Medium |High |High +|`+permissions: read-all+` default; per-job scoping + +|Container escape |Runtime environment |Low |High |Medium |Hardened +container runtime; read-only rootfs; no-new-privileges + +|Compromised action dependency |CI/CD pipeline |Medium |High |High +|SHA-pin all actions; never use `+@latest+` tags +|=== + +=== Mitigations in Place + +* *SLSA Provenance*: Build attestations via slsa-github-generator +* *Secret Scanning*: TruffleHog + secret-scanner workflow on every push +* *Static Analysis*: CodeQL on supported languages +* *Supply Chain*: OpenSSF Scorecard (scorecard.yml + +scorecard-enforcer.yml) +* *Container Signing*: Ed25519 signatures on all published images +(optional: use your signing tool) +* *Container Runtime*: Hardened container runtime with formal +verification (optional) +* *Dependency Pinning*: All GitHub Actions SHA-pinned; lockfiles +committed +* *Workflow Validation*: workflow-linter.yml checks all workflow changes +* *Security Scanning*: Neurosymbolic scanning (hypatia-scan.yml, +optional) +* *Bot Governance*: Bot orchestration with confidence thresholds +(optional) +* *Edge Security*: Gateway with policy enforcement (optional, where +applicable) +* *SBOM*: Generated and published with releases + +=== Residual Risks + +[width="100%",cols="39%,41%,20%",options="header",] +|=== +|Risk |Accepted Because |Review Trigger +|Zero-day in GitHub Actions runner |Platform responsibility; no feasible +mitigation |GitHub advisory + +|Maintainer account compromise |Mitigated by 2FA requirement; residual +remains |Any suspicious activity + +|Transitive dependency vulnerability (0-day) |Lockfiles limit blast +radius; scanning catches known CVEs |CVE database update + +|SBOM exposes internal component names |Transparency is a design goal +|Policy change +|=== + +=== Review Schedule + +This threat model should be reviewed: + +* *Quarterly* as a standing item +* *When architecture changes* (new services, new trust boundaries, new +deployment targets) +* *Before major releases* (v1.0, v2.0, etc.) +* *After any security incident* affecting this project or its +dependencies + +Reviewer should update the "`Last Reviewed`" date and version in +Document Info above. diff --git a/packages/TradeUnionism.jl/docs/THREAT-MODEL.md b/packages/TradeUnionism.jl/docs/THREAT-MODEL.md deleted file mode 100644 index c33fe79d8..000000000 --- a/packages/TradeUnionism.jl/docs/THREAT-MODEL.md +++ /dev/null @@ -1,161 +0,0 @@ - - - -# Threat Model: {{PROJECT_NAME}} - -## Document Info - -| Field | Value | -|---------------|--------------------------------| -| Project | {{PROJECT_NAME}} | -| Version | 1.0 | -| Last Reviewed | {{DATE}} | -| Author | {{AUTHOR}} | -| Methodology | STRIDE | - -## Scope - -### In Scope - -- Application source code and build pipeline -- CI/CD workflows (GitHub Actions) -- Container images and runtime environment -- Secrets and credential management -- Dependencies (direct and transitive) -- Deployment artifacts (binaries, containers, SBOM) - -### Out of Scope - -- Physical security of hosting infrastructure -- GitHub/GitLab platform-level vulnerabilities -- End-user device security -- Social engineering attacks against maintainers (handled by org policy) - -## System Overview - -Brief description of {{PROJECT_NAME}} and its architecture. - -> See [TOPOLOGY.md](../TOPOLOGY.md) for the full architecture diagram and completion dashboard. - -## Assets - -| Asset | Classification | Owner | Notes | -|----------------------|----------------|-------------|--------------------------------------------| -| Source code | Internal | Maintainers | Public repos are still internal-integrity | -| Signing keys | Restricted | Release lead | Signing keys (e.g., Ed25519), GPG keys | -| CI/CD secrets | Restricted | Maintainers | GITHUB_TOKEN, deploy tokens, PATs | -| User/contributor data | Confidential | Org | Emails, contributor identity | -| Build artifacts | Internal | CI pipeline | Binaries, WASM bundles | -| Container images | Internal | CI pipeline | Chainguard-based, signed via image signing tool | -| SBOM / provenance | Public | CI pipeline | SLSA attestations | -| Dependencies | Public | Lockfile | Cargo.lock, deno.lock, gleam.toml | -| Infrastructure config | Confidential | Maintainers | Containerfiles, compose files, orchestration config | - -## Trust Boundaries - -| Boundary | From (Lower Trust) | To (Higher Trust) | -|-----------------------------|---------------------------|----------------------------| -| Pull request submission | External contributor | Repository codebase | -| CI/CD workflow execution | Workflow definition | Runner with secrets access | -| Container build boundary | Build stage | Runtime stage | -| External API calls | Third-party service | Application internals | -| User input (CLI/Web) | End user | Application logic | -| Dependency resolution | Package registry | Build environment | -| Forge mirroring | GitHub | GitLab / Bitbucket | - -## Threat Actors - -| Actor | Motivation | Capability | -|--------------------------|-------------------------------|------------| -| Script kiddie | Vandalism, clout | Low | -| Disgruntled contributor | Sabotage, backdoor insertion | Medium | -| Supply chain attacker | Wide-impact compromise | High | -| Nation state | Espionage, disruption | Very High | -| Automated bot | Credential stuffing, spam PRs | Low-Medium | - -## STRIDE Analysis - -### Spoofing - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unsigned commits impersonate maintainer | Source code | Medium | High | High | Require GPG-signed commits; vigilant code review | -| Forged bot actions (automated agents) | CI/CD pipeline | Low | High | Medium | Bot tokens scoped minimally; audit bot activity | -| Spoofed package registry identity | Dependencies | Low | High | Medium | Pin dependencies by hash; verify provenance | - -### Tampering - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Malicious pull request | Source code | Medium | High | High | Branch protection; required reviews; CodeQL | -| Dependency poisoning (typosquat) | Dependencies | Medium | High | High | Lockfiles; secret-scanner; security scans | -| Tampered container base image | Container images | Low | High | Medium | Chainguard images; image signing verification | -| Workflow file modification | CI/CD pipeline | Low | High | Medium | CODEOWNERS on .github/; workflow-linter | - -### Repudiation - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Unlogged deployment | Build artifacts | Medium | Medium | Medium | SLSA provenance; deployment audit trail | -| Denied merge of vulnerable code | Source code | Low | Medium | Low | Git history is immutable; signed commits | -| Secret rotation without record | CI/CD secrets | Low | Low | Low | Secret rotation logged in STATE.a2ml | - -### Information Disclosure - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Secrets leaked in git history | CI/CD secrets | Medium | High | High | TruffleHog in CI; secret-scanner workflow | -| Verbose error messages in prod | Application logic | Medium | Medium | Medium | Sanitize outputs; structured logging | -| SBOM reveals internal structure | Infrastructure | Low | Low | Low | Accepted risk; SBOM is intentionally public | - -### Denial of Service - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| CI resource exhaustion (fork bomb in PR) | CI/CD pipeline | Medium | Medium | Medium | Concurrency limits; timeout on workflows | -| Spam issues/PRs flooding triage | Maintainer time | Medium | Low | Low | GitHub rate limits; bot auto-close stale | -| Large binary commits bloating repo | Source code | Low | Medium | Low | .gitattributes LFS policy; pre-commit hooks | - -### Elevation of Privilege - -| Threat | Affected Asset | Likelihood | Impact | Risk | Mitigation | -|---------------------------------|-------------------|------------|--------|--------|------------------------------------------------| -| Workflow injection via PR title/body | CI/CD pipeline | Medium | High | High | Never interpolate PR fields in `run:`; use env vars | -| GITHUB_TOKEN over-scoped | CI/CD secrets | Medium | High | High | `permissions: read-all` default; per-job scoping | -| Container escape | Runtime environment | Low | High | Medium | Hardened container runtime; read-only rootfs; no-new-privileges | -| Compromised action dependency | CI/CD pipeline | Medium | High | High | SHA-pin all actions; never use `@latest` tags | - -## Mitigations in Place - -- **SLSA Provenance**: Build attestations via slsa-github-generator -- **Secret Scanning**: TruffleHog + secret-scanner workflow on every push -- **Static Analysis**: CodeQL on supported languages -- **Supply Chain**: OpenSSF Scorecard (scorecard.yml + scorecard-enforcer.yml) -- **Container Signing**: Ed25519 signatures on all published images (optional: use your signing tool) -- **Container Runtime**: Hardened container runtime with formal verification (optional) -- **Dependency Pinning**: All GitHub Actions SHA-pinned; lockfiles committed -- **Workflow Validation**: workflow-linter.yml checks all workflow changes -- **Security Scanning**: Neurosymbolic scanning (hypatia-scan.yml, optional) -- **Bot Governance**: Bot orchestration with confidence thresholds (optional) -- **Edge Security**: Gateway with policy enforcement (optional, where applicable) -- **SBOM**: Generated and published with releases - -## Residual Risks - -| Risk | Accepted Because | Review Trigger | -|-----------------------------------------------|---------------------------------------------------|-------------------------| -| Zero-day in GitHub Actions runner | Platform responsibility; no feasible mitigation | GitHub advisory | -| Maintainer account compromise | Mitigated by 2FA requirement; residual remains | Any suspicious activity | -| Transitive dependency vulnerability (0-day) | Lockfiles limit blast radius; scanning catches known CVEs | CVE database update | -| SBOM exposes internal component names | Transparency is a design goal | Policy change | - -## Review Schedule - -This threat model should be reviewed: - -- **Quarterly** as a standing item -- **When architecture changes** (new services, new trust boundaries, new deployment targets) -- **Before major releases** (v1.0, v2.0, etc.) -- **After any security incident** affecting this project or its dependencies - -Reviewer should update the "Last Reviewed" date and version in Document Info above. diff --git a/packages/TradeUnionism.jl/docs/decisions/0000-template.adoc b/packages/TradeUnionism.jl/docs/decisions/0000-template.adoc new file mode 100644 index 000000000..de603adff --- /dev/null +++ b/packages/TradeUnionism.jl/docs/decisions/0000-template.adoc @@ -0,0 +1,33 @@ +== [NUMBER]. [TITLE] + +Date: YYYY-MM-DD + +=== Status + +{empty}[Proposed | Accepted | Deprecated | Superseded by +link:NNNN-title.md[ADR-NNNN] | Rejected] + +=== Context + +What is the issue that we’re seeing that is motivating this decision or +change? + +=== Decision + +What is the change that we’re proposing and/or doing? + +=== Consequences + +What becomes easier or more difficult to do because of this change? + +==== Positive + +* … + +==== Negative + +* … + +==== Neutral + +* … diff --git a/packages/TradeUnionism.jl/docs/decisions/0000-template.md b/packages/TradeUnionism.jl/docs/decisions/0000-template.md deleted file mode 100644 index 2f7fc67de..000000000 --- a/packages/TradeUnionism.jl/docs/decisions/0000-template.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -# [NUMBER]. [TITLE] - -Date: YYYY-MM-DD - -## Status - -[Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](NNNN-title.md) | Rejected] - -## Context - -What is the issue that we're seeing that is motivating this decision or change? - -## Decision - -What is the change that we're proposing and/or doing? - -## Consequences - -What becomes easier or more difficult to do because of this change? - -### Positive - -- ... - -### Negative - -- ... - -### Neutral - -- ... diff --git a/packages/TradeUnionism.jl/docs/decisions/0001-adopt-rsr-standard.adoc b/packages/TradeUnionism.jl/docs/decisions/0001-adopt-rsr-standard.adoc new file mode 100644 index 000000000..8e404cbbc --- /dev/null +++ b/packages/TradeUnionism.jl/docs/decisions/0001-adopt-rsr-standard.adoc @@ -0,0 +1,94 @@ +== 1. Adopt Rhodium Standard Repository (RSR) Template + +Date: 2026-02-14 + +=== Status + +Accepted + +=== Context + +Managing multiple repositories with an ad-hoc approach led to +significant inconsistencies across the ecosystem. Common problems +included: + +* Missing or incomplete configuration files (SECURITY.md, +CONTRIBUTING.md, .editorconfig, etc.) +* State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the +repository root instead of the canonical `+.machine_readable/+` +directory +* Duplicate or conflicting workflow definitions across repos +* No standardized entry point for AI agents interacting with +repositories +* Inconsistent bot directive configurations leading to unreliable +automation +* No contractile enforcement or Justfile automation + +Without a single source of truth for repository structure, each new repo +required manual setup and inevitably drifted from best practices over +time. + +=== Decision + +Adopt the Rhodium Standard Repository (RSR) template +(`+rsr-template-repo+`) as the canonical starting point for all new +repositories. Existing repositories will migrate incrementally as they +receive active development. + +The RSR template provides: + +* *Machine-readable state files* in `+.machine_readable/+` (STATE.a2ml, +ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) +* *AI manifest* (`+0-AI-MANIFEST.a2ml+`) as a universal entry point for +all AI agents +* *Bot directives* in `+.machine_readable/bot_directives/+` for bot +orchestration integration +* *Contractiles* in `+.machine_readable/contractiles/+` (k9, dust, lust, +must, trust) for policy enforcement +* *Standardized workflows* (16+ GitHub Actions workflows, all +SHA-pinned) +* *Justfile automation* with standard recipes for common tasks +* *Security and governance files*: SECURITY.md, CONTRIBUTING.md, +CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) +* *Architecture Decision Records* in `+docs/decisions/+` + +New repositories are created by cloning the template: + +[source,bash] +---- +git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name +cd new-repo-name +rm -rf .git && git init +---- + +=== Consequences + +==== Positive + +* Consistency across all repositories, enforced from creation +* Automated compliance checking via `+rsr-antipattern.yml+` workflow +* Bot fleet can operate reliably across all repos with predictable +structure +* AI agents (Claude, Gemini, etc.) have a standardized entry point via +`+0-AI-MANIFEST.a2ml+` +* New contributors can onboard faster with familiar, documented +structure +* Reduced maintenance burden: fix once in template, propagate to all +repos +* Machine-readable state enables tooling and automation pipelines + +==== Negative + +* Migration effort for existing repos requires time and attention +* Learning curve for contributors unfamiliar with RSR conventions +* Template updates need propagation mechanism to existing repos +* Some repos may have unique needs that do not fit the standard template +without customization + +==== Neutral + +* Existing CI/CD pipelines continue to work; RSR workflows are additive +* Third-party dependencies retain their original licenses regardless of +repo structure +* ADR process itself is part of the template, enabling future decisions +to be recorded consistently diff --git a/packages/TradeUnionism.jl/docs/decisions/0001-adopt-rsr-standard.md b/packages/TradeUnionism.jl/docs/decisions/0001-adopt-rsr-standard.md deleted file mode 100644 index 806942f67..000000000 --- a/packages/TradeUnionism.jl/docs/decisions/0001-adopt-rsr-standard.md +++ /dev/null @@ -1,85 +0,0 @@ - - - -# 1. Adopt Rhodium Standard Repository (RSR) Template - -Date: 2026-02-14 - -## Status - -Accepted - -## Context - -Managing multiple repositories with an ad-hoc approach led to significant -inconsistencies across the ecosystem. Common problems included: - -- Missing or incomplete configuration files (SECURITY.md, CONTRIBUTING.md, - .editorconfig, etc.) -- State files (STATE.a2ml, META.a2ml, ECOSYSTEM.a2ml) placed in the repository - root instead of the canonical `.machine_readable/` directory -- Duplicate or conflicting workflow definitions across repos -- No standardized entry point for AI agents interacting with repositories -- Inconsistent bot directive configurations leading to unreliable automation -- No contractile enforcement or Justfile automation - -Without a single source of truth for repository structure, each new repo -required manual setup and inevitably drifted from best practices over time. - -## Decision - -Adopt the Rhodium Standard Repository (RSR) template (`rsr-template-repo`) as -the canonical starting point for all new repositories. Existing repositories -will migrate incrementally as they receive active development. - -The RSR template provides: - -- **Machine-readable state files** in `.machine_readable/` (STATE.a2ml, - ECOSYSTEM.a2ml, META.a2ml, AGENTIC.a2ml, NEUROSYM.a2ml, PLAYBOOK.a2ml) -- **AI manifest** (`0-AI-MANIFEST.a2ml`) as a universal entry point for all - AI agents -- **Bot directives** in `.machine_readable/bot_directives/` for bot orchestration integration -- **Contractiles** in `.machine_readable/contractiles/` (k9, dust, lust, must, trust) for - policy enforcement -- **Standardized workflows** (16+ GitHub Actions workflows, all SHA-pinned) -- **Justfile automation** with standard recipes for common tasks -- **Security and governance files**: SECURITY.md, CONTRIBUTING.md, - CODE_OF_CONDUCT.md, LICENSE (MPL-2.0) -- **Architecture Decision Records** in `docs/decisions/` - -New repositories are created by cloning the template: - -```bash -git clone https://github.com/{{OWNER}}/rsr-template-repo new-repo-name -cd new-repo-name -rm -rf .git && git init -``` - -## Consequences - -### Positive - -- Consistency across all repositories, enforced from creation -- Automated compliance checking via `rsr-antipattern.yml` workflow -- Bot fleet can operate reliably across all repos with predictable structure -- AI agents (Claude, Gemini, etc.) have a standardized entry point via - `0-AI-MANIFEST.a2ml` -- New contributors can onboard faster with familiar, documented structure -- Reduced maintenance burden: fix once in template, propagate to all repos -- Machine-readable state enables tooling and automation pipelines - -### Negative - -- Migration effort for existing repos requires time and attention -- Learning curve for contributors unfamiliar with RSR conventions -- Template updates need propagation mechanism to existing repos -- Some repos may have unique needs that do not fit the standard template - without customization - -### Neutral - -- Existing CI/CD pipelines continue to work; RSR workflows are additive -- Third-party dependencies retain their original licenses regardless of - repo structure -- ADR process itself is part of the template, enabling future decisions - to be recorded consistently diff --git a/packages/TradeUnionism.jl/docs/decisions/README.adoc b/packages/TradeUnionism.jl/docs/decisions/README.adoc new file mode 100644 index 000000000..3dc7a4856 --- /dev/null +++ b/packages/TradeUnionism.jl/docs/decisions/README.adoc @@ -0,0 +1,18 @@ +== Architecture Decision Records + +We record significant architectural decisions using +https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions[Architecture +Decision Records (ADRs)], as described by Michael Nygard. + +Each ADR captures the context, decision, and consequences of a choice +that affects the project’s structure, dependencies, or conventions. + +=== Creating a new ADR + +[source,bash] +---- +just adr "Title of decision" +---- + +This creates a new numbered file in `+docs/decisions/+` from the +template at `+0000-template.md+`. diff --git a/packages/TradeUnionism.jl/docs/decisions/README.md b/packages/TradeUnionism.jl/docs/decisions/README.md deleted file mode 100644 index 79851eea4..000000000 --- a/packages/TradeUnionism.jl/docs/decisions/README.md +++ /dev/null @@ -1,16 +0,0 @@ - - - -# Architecture Decision Records - -We record significant architectural decisions using [Architecture Decision Records (ADRs)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions), as described by Michael Nygard. - -Each ADR captures the context, decision, and consequences of a choice that affects the project's structure, dependencies, or conventions. - -## Creating a new ADR - -```bash -just adr "Title of decision" -``` - -This creates a new numbered file in `docs/decisions/` from the template at `0000-template.md`. diff --git a/packages/ViableSystems.jl/TOPOLOGY.md b/packages/ViableSystems.jl/TOPOLOGY.adoc similarity index 89% rename from packages/ViableSystems.jl/TOPOLOGY.md rename to packages/ViableSystems.jl/TOPOLOGY.adoc index 45ea60dae..e9274b541 100644 --- a/packages/ViableSystems.jl/TOPOLOGY.md +++ b/packages/ViableSystems.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== ViableSystems.jl — Project Topology -# ViableSystems.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ ENVIRONMENT / CONTEXT │ ├─────────────────────────────────────────┤ @@ -42,11 +38,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE CYBERNETICS @@ -66,26 +62,27 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████░░░░ ~60% Functional Cybernetic Base -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... CATWOE Analysis ──────► Root Definition ──────► Boundary Objects │ Variety Mapping ──────► VSM Structure ───────────┤ │ Recursive Checks ─────► Algedonic Loops ──────► COMPLETE -``` +.... -## 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/packages/ZeroProb.jl/ABI-FFI-README.adoc b/packages/ZeroProb.jl/ABI-FFI-README.adoc new file mode 100644 index 000000000..8e5244189 --- /dev/null +++ b/packages/ZeroProb.jl/ABI-FFI-README.adoc @@ -0,0 +1,409 @@ +\{\{~ Aditionally delete this line and fill out the template below ~}} + +== \{\{PROJECT}} ABI/FFI Documentation + +=== Overview + +This library follows the *Hyperpolymath RSR Standard* for ABI and FFI +design: + +* *ABI (Application Binary Interface)* defined in *Idris2* with formal +proofs +* *FFI (Foreign Function Interface)* implemented in *Zig* for C +compatibility +* *Generated C headers* bridge Idris2 ABI to Zig FFI +* *Any language* can call through standard C ABI + +=== Architecture + +.... +┌─────────────────────────────────────────────┐ +│ ABI Definitions (Idris2) │ +│ src/abi/ │ +│ - Types.idr (Type definitions) │ +│ - Layout.idr (Memory layout proofs) │ +│ - Foreign.idr (FFI declarations) │ +└─────────────────┬───────────────────────────┘ + │ + │ generates (at compile time) + ▼ +┌─────────────────────────────────────────────┐ +│ C Headers (auto-generated) │ +│ generated/abi/{{project}}.h │ +└─────────────────┬───────────────────────────┘ + │ + │ imported by + ▼ +┌─────────────────────────────────────────────┐ +│ FFI Implementation (Zig) │ +│ ffi/zig/src/main.zig │ +│ - Implements C-compatible functions │ +│ - Zero-cost abstractions │ +│ - Memory-safe by default │ +└─────────────────┬───────────────────────────┘ + │ + │ compiled to lib{{project}}.so/.a + ▼ +┌─────────────────────────────────────────────┐ +│ Any Language via C ABI │ +│ - Rust, ReScript, Julia, Python, etc. │ +└─────────────────────────────────────────────┘ +.... + +=== Directory Structure + +.... +{{project}}/ +├── src/ +│ ├── abi/ # ABI definitions (Idris2) +│ │ ├── Types.idr # Core type definitions with proofs +│ │ ├── Layout.idr # Memory layout verification +│ │ └── Foreign.idr # FFI function declarations +│ └── lib/ # Core library (any language) +│ +├── ffi/ +│ └── zig/ # FFI implementation (Zig) +│ ├── build.zig # Build configuration +│ ├── build.zig.zon # Dependencies +│ ├── src/ +│ │ └── main.zig # C-compatible FFI implementation +│ ├── test/ +│ │ └── integration_test.zig +│ └── include/ +│ └── {{project}}.h # C header (optional, can be generated) +│ +├── generated/ # Auto-generated files +│ └── abi/ +│ └── {{project}}.h # Generated from Idris2 ABI +│ +└── bindings/ # Language-specific wrappers (optional) + ├── rust/ + ├── rescript/ + └── julia/ +.... + +=== Why Idris2 for ABI? + +==== 1. *Formal Verification* + +Idris2’s dependent types allow proving properties about the ABI at +compile-time: + +[source,idris] +---- +-- Prove struct size is correct +public export +exampleStructSize : HasSize ExampleStruct 16 + +-- Prove field alignment is correct +public export +fieldAligned : Divides 8 (offsetOf ExampleStruct.field) + +-- Prove ABI is platform-compatible +public export +abiCompatible : Compatible (ABI 1) (ABI 2) +---- + +==== 2. *Type Safety* + +Encode invariants that C/Zig cannot express: + +[source,idris] +---- +-- Non-null pointer guaranteed at type level +data Handle : Type where + MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle + +-- Array with length proof +data Buffer : (n : Nat) -> Type where + MkBuffer : Vect n Byte -> Buffer n +---- + +==== 3. *Platform Abstraction* + +Platform-specific types with compile-time selection: + +[source,idris] +---- +CInt : Platform -> Type +CInt Linux = Bits32 +CInt Windows = Bits32 + +CSize : Platform -> Type +CSize Linux = Bits64 +CSize Windows = Bits64 +---- + +==== 4. *Safe Evolution* + +Prove that new ABI versions are backward-compatible: + +[source,idris] +---- +-- Compiler enforces compatibility +abiUpgrade : ABI 1 -> ABI 2 +abiUpgrade old = MkABI2 { + -- Must preserve all v1 fields + v1_compat = old, + -- Can add new fields + new_features = defaults +} +---- + +=== Why Zig for FFI? + +==== 1. *C ABI Compatibility* + +Zig exports C-compatible functions naturally: + +[source,zig] +---- +export fn library_function(param: i32) i32 { + return param * 2; +} +---- + +==== 2. *Memory Safety* + +Compile-time safety without runtime overhead: + +[source,zig] +---- +// Null check enforced at compile time +const handle = init() orelse return error.InitFailed; +defer free(handle); +---- + +==== 3. *Cross-Compilation* + +Built-in cross-compilation to any platform: + +[source,bash] +---- +zig build -Dtarget=x86_64-linux +zig build -Dtarget=aarch64-macos +zig build -Dtarget=x86_64-windows +---- + +==== 4. *Zero Dependencies* + +No runtime, no libc required (unless explicitly needed): + +[source,zig] +---- +// Minimal binary size +pub const lib = @import("std"); +// Only includes what you use +---- + +=== Building + +==== Build FFI Library + +[source,bash] +---- +cd ffi/zig +zig build # Build debug +zig build -Doptimize=ReleaseFast # Build optimized +zig build test # Run tests +---- + +==== Generate C Header from Idris2 ABI + +[source,bash] +---- +cd src/abi +idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h +---- + +==== Cross-Compile + +[source,bash] +---- +cd ffi/zig + +# Linux x86_64 +zig build -Dtarget=x86_64-linux + +# macOS ARM64 +zig build -Dtarget=aarch64-macos + +# Windows x86_64 +zig build -Dtarget=x86_64-windows +---- + +=== Usage + +==== From C + +[source,c] +---- +#include "{{project}}.h" + +int main() { + void* handle = {{project}}_init(); + if (!handle) return 1; + + int result = {{project}}_process(handle, 42); + if (result != 0) { + const char* err = {{project}}_last_error(); + fprintf(stderr, "Error: %s\n", err); + } + + {{project}}_free(handle); + return 0; +} +---- + +Compile with: + +[source,bash] +---- +gcc -o example example.c -l{{project}} -L./zig-out/lib +---- + +==== From Idris2 + +[source,idris] +---- +import {{PROJECT}}.ABI.Foreign + +main : IO () +main = do + Just handle <- init + | Nothing => putStrLn "Failed to initialize" + + Right result <- process handle 42 + | Left err => putStrLn $ "Error: " ++ errorDescription err + + free handle + putStrLn "Success" +---- + +==== From Rust + +[source,rust] +---- +#[link(name = "{{project}}")] +extern "C" { + fn {{project}}_init() -> *mut std::ffi::c_void; + fn {{project}}_free(handle: *mut std::ffi::c_void); + fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; +} + +fn main() { + unsafe { + let handle = {{project}}_init(); + assert!(!handle.is_null()); + + let result = {{project}}_process(handle, 42); + assert_eq!(result, 0); + + {{project}}_free(handle); + } +} +---- + +==== From Julia + +[source,julia] +---- +const lib{{project}} = "lib{{project}}" + +function init() + handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) + handle == C_NULL && error("Failed to initialize") + handle +end + +function process(handle, input) + result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) + result +end + +function cleanup(handle) + ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) +end + +# Usage +handle = init() +try + result = process(handle, 42) + println("Result: $result") +finally + cleanup(handle) +end +---- + +=== Testing + +==== Unit Tests (Zig) + +[source,bash] +---- +cd ffi/zig +zig build test +---- + +==== Integration Tests + +[source,bash] +---- +cd ffi/zig +zig build test-integration +---- + +==== ABI Verification (Idris2) + +[source,idris] +---- +-- Compile-time verification +%runElab verifyABI + +-- Runtime checks +main : IO () +main = do + verifyLayoutsCorrect + verifyAlignmentsCorrect + putStrLn "ABI verification passed" +---- + +=== Contributing + +When modifying the ABI/FFI: + +[arabic] +. *Update ABI first* (`+src/abi/*.idr+`) +* Modify type definitions +* Update proofs +* Ensure backward compatibility +. *Generate C header* ++ +[source,bash] +---- +idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h +---- +. *Update FFI implementation* (`+ffi/zig/src/main.zig+`) +* Implement new functions +* Match ABI types exactly +. *Add tests* +* Unit tests in Zig +* Integration tests +* ABI verification tests +. *Update documentation* +* Function signatures +* Usage examples +* Migration guide (if breaking changes) + +=== License + +\{\{LICENSE}} + +=== See Also + +* https://idris2.readthedocs.io[Idris2 Documentation] +* https://ziglang.org/documentation/master/[Zig Documentation] +* https://github.com/hyperpolymath/rhodium-standard-repositories[Rhodium +Standard Repositories] +* link:../ffi-migration-guide.md[FFI Migration Guide] +* link:../abi-migration-guide.md[ABI Migration Guide] diff --git a/packages/ZeroProb.jl/ABI-FFI-README.md b/packages/ZeroProb.jl/ABI-FFI-README.md deleted file mode 100644 index 08d35da64..000000000 --- a/packages/ZeroProb.jl/ABI-FFI-README.md +++ /dev/null @@ -1,385 +0,0 @@ -{{~ Aditionally delete this line and fill out the template below ~}} - -# {{PROJECT}} ABI/FFI Documentation - -## Overview - -This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design: - -- **ABI (Application Binary Interface)** defined in **Idris2** with formal proofs -- **FFI (Foreign Function Interface)** implemented in **Zig** for C compatibility -- **Generated C headers** bridge Idris2 ABI to Zig FFI -- **Any language** can call through standard C ABI - -## Architecture - -``` -┌─────────────────────────────────────────────┐ -│ ABI Definitions (Idris2) │ -│ src/abi/ │ -│ - Types.idr (Type definitions) │ -│ - Layout.idr (Memory layout proofs) │ -│ - Foreign.idr (FFI declarations) │ -└─────────────────┬───────────────────────────┘ - │ - │ generates (at compile time) - ▼ -┌─────────────────────────────────────────────┐ -│ C Headers (auto-generated) │ -│ generated/abi/{{project}}.h │ -└─────────────────┬───────────────────────────┘ - │ - │ imported by - ▼ -┌─────────────────────────────────────────────┐ -│ FFI Implementation (Zig) │ -│ ffi/zig/src/main.zig │ -│ - Implements C-compatible functions │ -│ - Zero-cost abstractions │ -│ - Memory-safe by default │ -└─────────────────┬───────────────────────────┘ - │ - │ compiled to lib{{project}}.so/.a - ▼ -┌─────────────────────────────────────────────┐ -│ Any Language via C ABI │ -│ - Rust, ReScript, Julia, Python, etc. │ -└─────────────────────────────────────────────┘ -``` - -## Directory Structure - -``` -{{project}}/ -├── src/ -│ ├── abi/ # ABI definitions (Idris2) -│ │ ├── Types.idr # Core type definitions with proofs -│ │ ├── Layout.idr # Memory layout verification -│ │ └── Foreign.idr # FFI function declarations -│ └── lib/ # Core library (any language) -│ -├── ffi/ -│ └── zig/ # FFI implementation (Zig) -│ ├── build.zig # Build configuration -│ ├── build.zig.zon # Dependencies -│ ├── src/ -│ │ └── main.zig # C-compatible FFI implementation -│ ├── test/ -│ │ └── integration_test.zig -│ └── include/ -│ └── {{project}}.h # C header (optional, can be generated) -│ -├── generated/ # Auto-generated files -│ └── abi/ -│ └── {{project}}.h # Generated from Idris2 ABI -│ -└── bindings/ # Language-specific wrappers (optional) - ├── rust/ - ├── rescript/ - └── julia/ -``` - -## Why Idris2 for ABI? - -### 1. **Formal Verification** - -Idris2's dependent types allow proving properties about the ABI at compile-time: - -```idris --- Prove struct size is correct -public export -exampleStructSize : HasSize ExampleStruct 16 - --- Prove field alignment is correct -public export -fieldAligned : Divides 8 (offsetOf ExampleStruct.field) - --- Prove ABI is platform-compatible -public export -abiCompatible : Compatible (ABI 1) (ABI 2) -``` - -### 2. **Type Safety** - -Encode invariants that C/Zig cannot express: - -```idris --- Non-null pointer guaranteed at type level -data Handle : Type where - MkHandle : (ptr : Bits64) -> {auto 0 nonNull : So (ptr /= 0)} -> Handle - --- Array with length proof -data Buffer : (n : Nat) -> Type where - MkBuffer : Vect n Byte -> Buffer n -``` - -### 3. **Platform Abstraction** - -Platform-specific types with compile-time selection: - -```idris -CInt : Platform -> Type -CInt Linux = Bits32 -CInt Windows = Bits32 - -CSize : Platform -> Type -CSize Linux = Bits64 -CSize Windows = Bits64 -``` - -### 4. **Safe Evolution** - -Prove that new ABI versions are backward-compatible: - -```idris --- Compiler enforces compatibility -abiUpgrade : ABI 1 -> ABI 2 -abiUpgrade old = MkABI2 { - -- Must preserve all v1 fields - v1_compat = old, - -- Can add new fields - new_features = defaults -} -``` - -## Why Zig for FFI? - -### 1. **C ABI Compatibility** - -Zig exports C-compatible functions naturally: - -```zig -export fn library_function(param: i32) i32 { - return param * 2; -} -``` - -### 2. **Memory Safety** - -Compile-time safety without runtime overhead: - -```zig -// Null check enforced at compile time -const handle = init() orelse return error.InitFailed; -defer free(handle); -``` - -### 3. **Cross-Compilation** - -Built-in cross-compilation to any platform: - -```bash -zig build -Dtarget=x86_64-linux -zig build -Dtarget=aarch64-macos -zig build -Dtarget=x86_64-windows -``` - -### 4. **Zero Dependencies** - -No runtime, no libc required (unless explicitly needed): - -```zig -// Minimal binary size -pub const lib = @import("std"); -// Only includes what you use -``` - -## Building - -### Build FFI Library - -```bash -cd ffi/zig -zig build # Build debug -zig build -Doptimize=ReleaseFast # Build optimized -zig build test # Run tests -``` - -### Generate C Header from Idris2 ABI - -```bash -cd src/abi -idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h -``` - -### Cross-Compile - -```bash -cd ffi/zig - -# Linux x86_64 -zig build -Dtarget=x86_64-linux - -# macOS ARM64 -zig build -Dtarget=aarch64-macos - -# Windows x86_64 -zig build -Dtarget=x86_64-windows -``` - -## Usage - -### From C - -```c -#include "{{project}}.h" - -int main() { - void* handle = {{project}}_init(); - if (!handle) return 1; - - int result = {{project}}_process(handle, 42); - if (result != 0) { - const char* err = {{project}}_last_error(); - fprintf(stderr, "Error: %s\n", err); - } - - {{project}}_free(handle); - return 0; -} -``` - -Compile with: -```bash -gcc -o example example.c -l{{project}} -L./zig-out/lib -``` - -### From Idris2 - -```idris -import {{PROJECT}}.ABI.Foreign - -main : IO () -main = do - Just handle <- init - | Nothing => putStrLn "Failed to initialize" - - Right result <- process handle 42 - | Left err => putStrLn $ "Error: " ++ errorDescription err - - free handle - putStrLn "Success" -``` - -### From Rust - -```rust -#[link(name = "{{project}}")] -extern "C" { - fn {{project}}_init() -> *mut std::ffi::c_void; - fn {{project}}_free(handle: *mut std::ffi::c_void); - fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32; -} - -fn main() { - unsafe { - let handle = {{project}}_init(); - assert!(!handle.is_null()); - - let result = {{project}}_process(handle, 42); - assert_eq!(result, 0); - - {{project}}_free(handle); - } -} -``` - -### From Julia - -```julia -const lib{{project}} = "lib{{project}}" - -function init() - handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ()) - handle == C_NULL && error("Failed to initialize") - handle -end - -function process(handle, input) - result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input) - result -end - -function cleanup(handle) - ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle) -end - -# Usage -handle = init() -try - result = process(handle, 42) - println("Result: $result") -finally - cleanup(handle) -end -``` - -## Testing - -### Unit Tests (Zig) - -```bash -cd ffi/zig -zig build test -``` - -### Integration Tests - -```bash -cd ffi/zig -zig build test-integration -``` - -### ABI Verification (Idris2) - -```idris --- Compile-time verification -%runElab verifyABI - --- Runtime checks -main : IO () -main = do - verifyLayoutsCorrect - verifyAlignmentsCorrect - putStrLn "ABI verification passed" -``` - -## Contributing - -When modifying the ABI/FFI: - -1. **Update ABI first** (`src/abi/*.idr`) - - Modify type definitions - - Update proofs - - Ensure backward compatibility - -2. **Generate C header** - ```bash - idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h - ``` - -3. **Update FFI implementation** (`ffi/zig/src/main.zig`) - - Implement new functions - - Match ABI types exactly - -4. **Add tests** - - Unit tests in Zig - - Integration tests - - ABI verification tests - -5. **Update documentation** - - Function signatures - - Usage examples - - Migration guide (if breaking changes) - -## License - -{{LICENSE}} - -## See Also - -- [Idris2 Documentation](https://idris2.readthedocs.io) -- [Zig Documentation](https://ziglang.org/documentation/master/) -- [Rhodium Standard Repositories](https://github.com/hyperpolymath/rhodium-standard-repositories) -- [FFI Migration Guide](../ffi-migration-guide.md) -- [ABI Migration Guide](../abi-migration-guide.md) diff --git a/packages/ZeroProb.jl/CODE_OF_CONDUCT.adoc b/packages/ZeroProb.jl/CODE_OF_CONDUCT.adoc new file mode 100644 index 000000000..9a23fee46 --- /dev/null +++ b/packages/ZeroProb.jl/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +\{\{PROJECT_NAME}} a harassment-free experience for everyone, regardless +of age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://%7B%7BFORGE%7D%7D/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/ZeroProb.jl/CODE_OF_CONDUCT.md b/packages/ZeroProb.jl/CODE_OF_CONDUCT.md deleted file mode 100644 index 2777a724e..000000000 --- a/packages/ZeroProb.jl/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in {{PROJECT_NAME}} a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://{{FORGE}}/{{OWNER}}/{{REPO}}/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: {{CURRENT_YEAR}} · Based on Contributor Covenant 2.1 diff --git a/packages/ZeroProb.jl/CONTRIBUTING.adoc b/packages/ZeroProb.jl/CONTRIBUTING.adoc new file mode 100644 index 000000000..205642748 --- /dev/null +++ b/packages/ZeroProb.jl/CONTRIBUTING.adoc @@ -0,0 +1,108 @@ +== Clone the repository + +git clone https://\{\{FORGE}}/\{\{OWNER}}/\{\{REPO}}.git cd \{\{REPO}} + +== Using Nix (recommended for reproducibility) + +nix develop + +== Or using toolbox/distrobox + +toolbox create \{\{REPO}}-dev toolbox enter \{\{REPO}}-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +\{\{REPO}}/ ├── 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_BRANCH}}` +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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed +- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements +- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/ZeroProb.jl/CONTRIBUTING.md b/packages/ZeroProb.jl/CONTRIBUTING.md deleted file mode 100644 index b39b3f7e8..000000000 --- a/packages/ZeroProb.jl/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://{{FORGE}}/{{OWNER}}/{{REPO}}.git -cd {{REPO}} - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create {{REPO}}-dev -toolbox enter {{REPO}}-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -{{REPO}}/ -├── 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_BRANCH}}` -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://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/{{OWNER}}/{{REPO}}/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/packages/ZeroProb.jl/SECURITY.adoc b/packages/ZeroProb.jl/SECURITY.adoc new file mode 100644 index 000000000..2b9c29253 --- /dev/null +++ b/packages/ZeroProb.jl/SECURITY.adoc @@ -0,0 +1,452 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[cols=",",] +|=== +|*Email* |\{\{SECURITY_EMAIL}} +|*PGP Key* |link:%7B%7BPGP_KEY_URL%7D%7D[Download Public Key] +|*Fingerprint* |`+{{PGP_FINGERPRINT}}+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL {{PGP_KEY_URL}} | gpg --import + +# Verify fingerprint +gpg --fingerprint {{SECURITY_EMAIL}} + +# Encrypt your report +gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+{{OWNER}}/{{REPO}}+`) and all its code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using \{\{PROJECT_NAME}}, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* link:%7B%7BPGP_KEY_URL%7D%7D[Our PGP Public Key] +* https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/security/advisories/new[Report +via GitHub] or \{\{SECURITY_EMAIL}} + +|*General questions* +|https://github.com/%7B%7BOWNER%7D%7D/%7B%7BREPO%7D%7D/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep \{\{PROJECT_NAME}} and its users safe._ 🛡️ + +''''' + +Last updated: \{\{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/ZeroProb.jl/SECURITY.md b/packages/ZeroProb.jl/SECURITY.md deleted file mode 100644 index 7dd7b29e7..000000000 --- a/packages/ZeroProb.jl/SECURITY.md +++ /dev/null @@ -1,406 +0,0 @@ -# Security Policy - - - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | {{SECURITY_EMAIL}} | -| **PGP Key** | [Download Public Key]({{PGP_KEY_URL}}) | -| **Fingerprint** | `{{PGP_FINGERPRINT}}` | - -```bash -# Import our PGP key -curl -sSL {{PGP_KEY_URL}} | gpg --import - -# Verify fingerprint -gpg --fingerprint {{SECURITY_EMAIL}} - -# Encrypt your report -gpg --armor --encrypt --recipient {{SECURITY_EMAIL}} report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`{{OWNER}}/{{REPO}}`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using {{PROJECT_NAME}}, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key]({{PGP_KEY_URL}}) -- [Security Advisories](https://github.com/{{OWNER}}/{{REPO}}/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/{{OWNER}}/{{REPO}}/security/advisories/new) or {{SECURITY_EMAIL}} | -| **General questions** | [GitHub Discussions](https://github.com/{{OWNER}}/{{REPO}}/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep {{PROJECT_NAME}} and its users safe.* 🛡️ - ---- - -Last updated: {{CURRENT_YEAR}} · Policy version: 1.0.0 diff --git a/packages/ZeroProb.jl/SONNET-TASKS.adoc b/packages/ZeroProb.jl/SONNET-TASKS.adoc new file mode 100644 index 000000000..7e57851ee --- /dev/null +++ b/packages/ZeroProb.jl/SONNET-TASKS.adoc @@ -0,0 +1,656 @@ +== SONNET-TASKS.md – ZeroProb.jl + +*Repo:* `+hyperpolymath/ZeroProb.jl+` *Audit date:* 2026-02-12 *Auditor +model:* claude-opus-4-6 *Honest completion:* ~62% + +STATE.scm claims 100% – this is FALSE. The core types, measures, +paradoxes, and applications code is real and functional. But the README +advertises an API that does not exist (4 functions mentioned in docs are +never implemented), visualization has zero tests, there are phantom +dependencies in Project.toml, examples/ has nothing to do with +ZeroProb.jl, license headers are wrong in multiple template files, the +`+DiscreteZeroProbEvent+` has no `+relevance()+` dispatch, +`+handles_zero_prob_event+` has a stub fallthrough that silently returns +true, `+hausdorff_measure+` only handles dimensions 0 and 1 (trivial), +and `+plot_black_swan_impact+` is defined but not exported. + +''''' + +=== GROUND RULES FOR SONNET + +[arabic] +. Read this file top-to-bottom before starting. +. Do ONE task at a time. Verify each before moving on. +. Do NOT modify SONNET-TASKS.md itself (except to check off items if +instructed). +. Run all verification commands and confirm they pass. +. Commit after each task with a descriptive message. +. If a task says "`line N`", confirm the line number – file may have +shifted. +. Do NOT introduce new dependencies unless the task explicitly says to. +. Update `+.machine_readable/STATE.scm+` after all tasks are done to +reflect honest completion. + +''''' + +=== TASK 1: Implement the 4 missing functions advertised in README.adoc + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/README.adoc+` (lines 29, 76-89, +105-109, 115-128) - `+/var$REPOS_DIR/ZeroProb.jl/src/ZeroProb.jl+` +(export list) - `+/var$REPOS_DIR/ZeroProb.jl/src/measures.jl+` (add +implementations) + +*Problem:* The README.adoc advertises these functions in code examples +and the API reference: + +[arabic] +. `+density_ratio(dist, x, baseline)+` – a 3-argument form comparing +density at x vs baseline point. The actual implementation +(`+measures.jl+` line 46) is +`+density_ratio(event::ContinuousZeroProbEvent)+` which takes a single +event, not (dist, x, baseline). +. `+hausdorff_dimension(set)+` – mentioned at README line 88 +(`+dimension = hausdorff_dimension(cantor_set)+`). Never implemented +anywhere. +. `+construct_cantor_set(iterations=10)+` – mentioned at README line 87. +Never implemented anywhere. +. `+estimate_convergence_rate(ε_values, probs)+` – mentioned at README +lines 108-109 and API reference at line 128. Never implemented anywhere. +. `+epsilon_neighborhood_prob(dist, x, ε)+` – the README uses this name +(lines 47, 105, 124) but the actual function is +`+epsilon_neighborhood(event, ε)+`. Different name AND different +signature (takes event, not dist+x). + +*What to do:* + +Option A (recommended): Implement the missing functions in +`+src/measures.jl+`: - +`+density_ratio(dist::Distribution, x::Real, baseline::Real)+` – returns +`+pdf(dist, x) / pdf(dist, baseline)+` as a true ratio - +`+hausdorff_dimension(points; method=:box_counting)+` – box-counting +dimension estimation - `+construct_cantor_set(; iterations::Int=10)+` – +returns the Cantor set as a vector of intervals - +`+estimate_convergence_rate(ε_values::Vector, prob_values::Vector)+` – +log-log linear regression for convergence rate - +`+epsilon_neighborhood_prob+` as an alias for `+epsilon_neighborhood+` +with (dist, x, ε) signature + +Add all 5 to the export list in `+src/ZeroProb.jl+`. + +Option B: Fix the README to match the actual API. Only do this if Option +A is too much work. + +*Verification:* + +[source,julia] +---- +using ZeroProb, Distributions + +# density_ratio 3-arg form +dist = Normal(0, 1) +r = density_ratio(dist, 0.0, 3.0) +@assert r > 1.0 # Center is denser than tail +@assert r isa Float64 + +# hausdorff_dimension +cantor = construct_cantor_set(iterations=8) +dim = hausdorff_dimension(cantor) +@assert 0.5 < dim < 0.7 # Should be ~log(2)/log(3) ≈ 0.631 + +# estimate_convergence_rate +event = ContinuousZeroProbEvent(Normal(0,1), 0.0, :epsilon) +εs = [0.1, 0.01, 0.001, 0.0001] +probs = [epsilon_neighborhood(event, ε) for ε in εs] +rate = estimate_convergence_rate(εs, probs) +@assert rate isa Float64 +@assert rate > 0.0 + +# epsilon_neighborhood_prob alias +p = epsilon_neighborhood_prob(Normal(0,1), 0.0, 0.1) +@assert p > 0.0 +---- + +''''' + +=== TASK 2: Add `+relevance()+` dispatch for DiscreteZeroProbEvent + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/src/measures.jl+` - +`+/var$REPOS_DIR/ZeroProb.jl/test/test_measures.jl+` + +*Problem:* `+relevance()+` is only implemented for +`+ContinuousZeroProbEvent+` (measures.jl line 140). There is no +`+relevance()+` method for `+DiscreteZeroProbEvent+`. Calling +`+relevance(DiscreteZeroProbEvent(...))+` will throw a MethodError at +runtime. + +The `+DiscreteZeroProbEvent+` struct does not have a +`+relevance_measure+` field, so the dispatch needs a different approach +– it should return the pdf value (which is 0 by construction, since the +constructor asserts `+p == 0.0+`). + +*What to do:* Add to `+measures.jl+`: + +[source,julia] +---- +function relevance(event::DiscreteZeroProbEvent{T}; kwargs...) where T + # For discrete zero-prob events, relevance is based on the probability mass + # which is 0 by construction. Return 0.0 to be consistent. + return 0.0 +end +---- + +Also add `+relevance_score+` for `+DiscreteZeroProbEvent+`: + +[source,julia] +---- +function relevance_score(event::DiscreteZeroProbEvent{T}, application::Symbol) where T + return 0.0 # Discrete zero-prob events have no relevance by construction +end +---- + +Add tests to `+test_measures.jl+`: + +[source,julia] +---- +@testset "DiscreteZeroProbEvent relevance" begin + dist = Geometric(0.5) + event = DiscreteZeroProbEvent(dist, -1) + @test relevance(event) == 0.0 + @test relevance_score(event, :black_swan) == 0.0 +end +---- + +*Verification:* + +[source,julia] +---- +using ZeroProb, Distributions +dist = Geometric(0.5) +event = DiscreteZeroProbEvent(dist, -1) +@assert relevance(event) == 0.0 +@assert relevance_score(event, :black_swan) == 0.0 +@assert relevance_score(event, :betting) == 0.0 +---- + +''''' + +=== TASK 3: Export and test `+plot_black_swan_impact+` + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/src/ZeroProb.jl+` (lines 90-91 +export list) - `+/var$REPOS_DIR/ZeroProb.jl/src/visualization.jl+` (line +216, `+plot_black_swan_impact+`) + +*Problem:* `+plot_black_swan_impact+` is defined in `+visualization.jl+` +(line 216) but is NOT in the export list in `+ZeroProb.jl+` (lines +90-91). The export list only exports: + +.... +plot_zero_probability, plot_continuum_paradox, +plot_density_vs_probability, plot_epsilon_neighborhood +.... + +Missing: `+plot_black_swan_impact+`. + +*What to do:* Add `+plot_black_swan_impact+` to the export list on line +91 of `+src/ZeroProb.jl+`. + +*Verification:* + +[source,julia] +---- +using ZeroProb +@assert isdefined(ZeroProb, :plot_black_swan_impact) +@assert hasmethod(plot_black_swan_impact, Tuple{BlackSwanEvent}) +---- + +''''' + +=== TASK 4: Add visualization tests + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/test/runtests.jl+` - Create +`+/var$REPOS_DIR/ZeroProb.jl/test/test_visualization.jl+` + +*Problem:* There are ZERO tests for any of the 5 visualization +functions: - `+plot_zero_probability+` - `+plot_continuum_paradox+` - +`+plot_density_vs_probability+` - `+plot_epsilon_neighborhood+` - +`+plot_black_swan_impact+` + +The visualization module `+using Plots+` at the top of +`+visualization.jl+`, but Plots is listed as a dependency in +Project.toml, so it should load. However, none of the plotting functions +are tested to verify they at least return a plot object without +crashing. + +*What to do:* Create `+test/test_visualization.jl+`: + +[source,julia] +---- +# SPDX-License-Identifier: CC-BY-SA-4.0 + +using Plots + +@testset "Visualization" begin + @testset "plot_zero_probability" begin + dist = Normal(0, 1) + event = ContinuousZeroProbEvent(dist, 0.0, :density) + p = plot_zero_probability(event) + @test p isa Plots.Plot + end + + @testset "plot_continuum_paradox" begin + dist = Normal(0, 1) + p = plot_continuum_paradox(dist, num_points=5) + @test p isa Plots.Plot + end + + @testset "plot_density_vs_probability" begin + event = ContinuousZeroProbEvent(Normal(0, 1), 0.0, :density) + p = plot_density_vs_probability(event, ε_max=1.0) + @test p isa Plots.Plot + end + + @testset "plot_epsilon_neighborhood" begin + event = ContinuousZeroProbEvent(Normal(0, 1), 0.0, :epsilon) + p = plot_epsilon_neighborhood(event, ε=0.5) + @test p isa Plots.Plot + end + + @testset "plot_black_swan_impact" begin + crash = MarketCrashEvent(severity=:catastrophic) + p = plot_black_swan_impact(crash, samples=100) + @test p isa Plots.Plot + end +end +---- + +Add `+include("test_visualization.jl")+` to `+test/runtests.jl+`. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ZeroProb.jl +julia --project=. -e 'using Pkg; Pkg.test()' +---- + +All 5 visualization tests should pass. + +''''' + +=== TASK 5: Remove phantom dependencies from Project.toml + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/Project.toml+` (lines 8, 11) + +*Problem:* Project.toml lists two dependencies that are never used +anywhere in the source code: + +[arabic] +. `+Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"+` (line 8) – grep +confirms Makie is never imported or used in any `+.jl+` file. The +visualization module uses `+Plots+`, not `+Makie+`. +. `+Zstd_jll = "3161d3a3-bdf6-5164-811a-617609db77b4"+` (line 11) – grep +confirms Zstd_jll is never imported or used anywhere. This is a +compression library JLL wrapper with no connection to probability +theory. + +These add unnecessary compile-time overhead and dependency weight. + +*What to do:* 1. Remove the `+Makie+` line from `+[deps]+` 2. Remove the +`+Zstd_jll+` line from `+[deps]+` 3. Remove the `+Makie = "0.20"+` line +from `+[compat]+` 4. Remove the `+Zstd_jll = "1.5.7"+` line from +`+[compat]+` 5. Run `+julia --project=. -e 'using Pkg; Pkg.resolve()'+` +to regenerate Manifest.toml + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ZeroProb.jl +julia --project=. -e 'using Pkg; Pkg.resolve(); using ZeroProb; println("OK")' +---- + +Should load without error and without Makie/Zstd_jll. + +''''' + +=== TASK 6: Fix the `+handles_zero_prob_event+` stub fallthrough + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/src/applications.jl+` (lines +339-341) + +*Problem:* The catch-all branch at the bottom of +`+handles_zero_prob_event+` (line 339-341): + +[source,julia] +---- + else + @warn "No specific `handles_zero_prob_event` implementation for type $(typeof(event)). Returning true as a stub." + return true + end +---- + +This silently returns `+true+` for any unknown event type, which is +dangerous. If someone creates a new `+ZeroProbEvent+` subtype, +`+handles_zero_prob_event+` will claim the model handles it when it was +never actually tested. + +*What to do:* Change line 341 from `+return true+` to `+return false+` +and update the warning message: + +[source,julia] +---- + else + @warn "No specific `handles_zero_prob_event` implementation for type $(typeof(event)). Returning false (unverified)." + return false + end +---- + +Also add a test for this behavior in `+test/test_applications.jl+`: + +[source,julia] +---- +@testset "handles_zero_prob_event unknown type" begin + # Create a custom ZeroProbEvent subtype + struct TestZeroProbEvent <: ZeroProbEvent end + model = x -> x + # Unknown types should return false (not silently true) + @test handles_zero_prob_event(model, TestZeroProbEvent()) == false +end +---- + +*Verification:* + +[source,julia] +---- +using ZeroProb +struct MyCustomEvent <: ZeroProbEvent end +model = x -> x +@assert handles_zero_prob_event(model, MyCustomEvent()) == false +---- + +''''' + +=== TASK 7: Replace examples/ with actual ZeroProb.jl examples + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/examples/SafeDOMExample.res+` +(DELETE) - `+/var$REPOS_DIR/ZeroProb.jl/examples/web-project-deno.json+` +(DELETE) - Create `+/var$REPOS_DIR/ZeroProb.jl/examples/basic_usage.jl+` +- Create `+/var$REPOS_DIR/ZeroProb.jl/examples/black_swan_analysis.jl+` + +*Problem:* The examples/ directory contains two files that have NOTHING +to do with ZeroProb.jl: - `+SafeDOMExample.res+` – a ReScript file about +DOM mounting with AGPL license header - `+web-project-deno.json+` – a +Deno project config for a web project + +These are leftover RSR template files. A Julia probability library +should have Julia examples. + +*What to do:* 1. Delete `+SafeDOMExample.res+` and +`+web-project-deno.json+` 2. Create `+examples/basic_usage.jl+` +demonstrating: - Creating ContinuousZeroProbEvent instances - Computing +probability (always 0) vs relevance (non-zero) - All three relevance +measures (density, hausdorff, epsilon) - The continuum paradox function +3. Create `+examples/black_swan_analysis.jl+` demonstrating: - Creating +a MarketCrashEvent - Computing probability and expected impact - Using +handles_black_swan to test a model - BettingEdgeCase expected value +computation + +Both files must have: - `+# SPDX-License-Identifier: CC-BY-SA-4.0+` +header - +`+# Copyright (c) 2026 Jonathan D.A. Jewell +` +- Comments explaining each step - Must be runnable: +`+julia --project=.. examples/basic_usage.jl+` + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ZeroProb.jl +julia --project=. examples/basic_usage.jl +julia --project=. examples/black_swan_analysis.jl +---- + +Both should run without error and produce output. + +''''' + +=== TASK 8: Fix AGPL license headers in template files + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/.gitignore+` (line 1: +`+# SPDX-License-Identifier: CC-BY-SA-4.0+`) - +`+/var$REPOS_DIR/ZeroProb.jl/.gitattributes+` (line 1: +`+# SPDX-License-Identifier: CC-BY-SA-4.0+`) - +`+/var$REPOS_DIR/ZeroProb.jl/ffi/zig/build.zig+` (line 2: +`+// SPDX-License-Identifier: CC-BY-SA-4.0+`) - +`+/var$REPOS_DIR/ZeroProb.jl/ffi/zig/src/main.zig+` (line 6: +`+// SPDX-License-Identifier: CC-BY-SA-4.0+`) - +`+/var$REPOS_DIR/ZeroProb.jl/ffi/zig/test/integration_test.zig+` (line +2: `+// SPDX-License-Identifier: CC-BY-SA-4.0+`) - +`+/var$REPOS_DIR/ZeroProb.jl/docs/CITATIONS.adoc+` (line 13: +`+license = {AGPL-3.0-or-later}+`) - +`+/var$REPOS_DIR/ZeroProb.jl/RSR_OUTLINE.adoc+` (lines 72, 160 mention +AGPL) + +*Problem:* Per CLAUDE.md, AGPL-3.0 is the OLD license and must NEVER be +used. All hyperpolymath original code must use `+MPL-2.0+`. These are +leftover RSR template headers that were never updated. + +*What to do:* Replace `+AGPL-3.0-or-later+` with `+MPL-2.0+` in all +files listed above. + +For `+docs/CITATIONS.adoc+`, also fix the author from +`+Polymath, Hyper+` to `+Jewell, Jonathan D.A.+`, the title from +`+RSR-template-repo+` to `+ZeroProb.jl+`, the year from `+2025+` to +`+2026+`, and the URL to +`+https://github.com/hyperpolymath/ZeroProb.jl+`. + +For `+RSR_OUTLINE.adoc+`, update line 72 and 160 to reference MPL-2.0 +instead of AGPL. + +*Verification:* + +[source,bash] +---- +cd /var$REPOS_DIR/ZeroProb.jl +grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.adoc" --include=".git*" . | grep -v ".git/" +---- + +Should return NO matches (zero lines). + +''''' + +=== TASK 9: Make `+hausdorff_measure+` non-trivial (support dimensions > 1) + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/src/measures.jl+` (lines 70-78) + +*Problem:* The current `+hausdorff_measure+` implementation is trivial: + +[source,julia] +---- +function hausdorff_measure(event::ContinuousZeroProbEvent{T}, dimension::Int=0) where T + if dimension == 0 + return 1.0 # Single point has unit 0-dimensional Hausdorff measure + elseif dimension == 1 + return 0.0 # But zero 1-dimensional measure + else + throw(ArgumentError("Only dimensions 0 and 1 currently supported")) + end +end +---- + +This throws on any dimension other than 0 or 1. For a point set, the +Hausdorff measure of dimension d > 0 is always 0 (a single point has +zero d-dimensional measure for any d > 0). Dimension 0 is always 1 +(counting measure). So the function should handle all non-negative +integer dimensions, not just 0 and 1. + +*What to do:* Replace the function body: + +[source,julia] +---- +function hausdorff_measure(event::ContinuousZeroProbEvent{T}, dimension::Int=0) where T + @assert dimension >= 0 "Hausdorff dimension must be non-negative" + if dimension == 0 + return 1.0 # Single point has unit 0-dimensional Hausdorff measure (counting measure) + else + return 0.0 # Single point has zero d-dimensional Hausdorff measure for all d > 0 + end +end +---- + +Update tests in `+test_measures.jl+` to cover higher dimensions: + +[source,julia] +---- +@testset "hausdorff_measure higher dimensions" begin + dist = Normal(0, 1) + event = ContinuousZeroProbEvent(dist, 0.0, :hausdorff) + @test hausdorff_measure(event, 0) == 1.0 + @test hausdorff_measure(event, 1) == 0.0 + @test hausdorff_measure(event, 2) == 0.0 + @test hausdorff_measure(event, 10) == 0.0 + @test_throws AssertionError hausdorff_measure(event, -1) +end +---- + +*Verification:* + +[source,julia] +---- +using ZeroProb, Distributions +event = ContinuousZeroProbEvent(Normal(0,1), 0.0, :hausdorff) +@assert hausdorff_measure(event, 0) == 1.0 +@assert hausdorff_measure(event, 2) == 0.0 +@assert hausdorff_measure(event, 5) == 0.0 +# Should NOT throw: +hausdorff_measure(event, 100) +---- + +''''' + +=== TASK 10: Fix STATE.scm to reflect honest completion + +*Files:* - `+/var$REPOS_DIR/ZeroProb.jl/.machine_readable/STATE.scm+` + +*Problem:* STATE.scm line 22 claims `+(overall-completion 100)+` and +line 21 claims `+(phase "complete")+`. This is false. After completing +tasks 1-9, update STATE.scm to reflect the true state. + +Before tasks 1-9 are done, the honest completion is ~62%: - Types: 100% +(solid) - Measures: 70% (missing DiscreteZeroProbEvent dispatch, +hausdorff trivial, advertised functions missing) - Paradoxes: 95% +(functional, well-documented) - Applications: 80% (stub fallthrough, +placeholder comments) - Visualization: 50% (implemented but untested, +one function not exported) - Examples: 0% (wrong language, wrong +project) - Documentation: 60% (README advertises vaporware API) - +License compliance: 70% (AGPL remnants throughout) + +After tasks 1-9 are done, it should be ~90%. + +*What to do:* Update STATE.scm: - `+(phase "active")+` (or "`complete`" +only after all tasks done) - `+(overall-completion NN)+` – set to the +actual number after completing other tasks - Update `+(updated ...)+` to +today’s date - Add honest component completion percentages - Add +blockers if any remain - Add session history entry documenting this +audit + +*Verification:* + +[source,bash] +---- +cat /var$REPOS_DIR/ZeroProb.jl/.machine_readable/STATE.scm +# Verify: no "100" completion unless everything is actually done +# Verify: updated date is 2026-02-12 or later +# Verify: phase is not "complete" unless all tasks are done +---- + +''''' + +=== FINAL VERIFICATION + +After ALL tasks are completed, run this full verification sequence: + +[source,bash] +---- +cd /var$REPOS_DIR/ZeroProb.jl + +# 1. Full test suite passes +julia --project=. -e 'using Pkg; Pkg.test()' + +# 2. No AGPL references remain +grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.adoc" --include=".git*" . | grep -v ".git/" | wc -l +# Expected: 0 + +# 3. No phantom dependencies +julia --project=. -e 'using Pkg; deps = keys(Pkg.project().dependencies); @assert !("Makie" in deps); @assert !("Zstd_jll" in deps); println("No phantom deps")' + +# 4. All advertised functions exist +julia --project=. -e ' +using ZeroProb, Distributions + +# Core types +@assert isdefined(ZeroProb, :ContinuousZeroProbEvent) +@assert isdefined(ZeroProb, :DiscreteZeroProbEvent) +@assert isdefined(ZeroProb, :AlmostSureEvent) +@assert isdefined(ZeroProb, :SureEvent) + +# Measures +@assert isdefined(ZeroProb, :probability) +@assert isdefined(ZeroProb, :relevance) +@assert isdefined(ZeroProb, :density_ratio) +@assert isdefined(ZeroProb, :hausdorff_measure) +@assert isdefined(ZeroProb, :epsilon_neighborhood) +@assert isdefined(ZeroProb, :relevance_score) + +# Visualization +@assert isdefined(ZeroProb, :plot_zero_probability) +@assert isdefined(ZeroProb, :plot_continuum_paradox) +@assert isdefined(ZeroProb, :plot_density_vs_probability) +@assert isdefined(ZeroProb, :plot_epsilon_neighborhood) +@assert isdefined(ZeroProb, :plot_black_swan_impact) + +# Applications +@assert isdefined(ZeroProb, :BlackSwanEvent) +@assert isdefined(ZeroProb, :MarketCrashEvent) +@assert isdefined(ZeroProb, :BettingEdgeCase) +@assert isdefined(ZeroProb, :handles_black_swan) +@assert isdefined(ZeroProb, :handles_zero_prob_events) + +println("All exports verified") +' + +# 5. Examples run +julia --project=. examples/basic_usage.jl +julia --project=. examples/black_swan_analysis.jl + +# 6. DiscreteZeroProbEvent relevance works +julia --project=. -e ' +using ZeroProb, Distributions +event = DiscreteZeroProbEvent(Geometric(0.5), -1) +@assert relevance(event) == 0.0 +println("DiscreteZeroProbEvent relevance OK") +' + +# 7. Unknown event type returns false (not true) +julia --project=. -e ' +using ZeroProb +struct TestEvent <: ZeroProbEvent end +@assert handles_zero_prob_event(x->x, TestEvent()) == false +println("Unknown event fallthrough returns false OK") +' + +# 8. hausdorff_measure handles arbitrary dimensions +julia --project=. -e ' +using ZeroProb, Distributions +event = ContinuousZeroProbEvent(Normal(0,1), 0.0, :hausdorff) +@assert hausdorff_measure(event, 5) == 0.0 +println("hausdorff_measure arbitrary dims OK") +' + +# 9. STATE.scm is honest +grep "overall-completion 100" .machine_readable/STATE.scm +# Expected: no output (should NOT claim 100% unless everything is done) +---- + +If all 9 verification steps pass with expected output, the audit tasks +are complete. diff --git a/packages/ZeroProb.jl/SONNET-TASKS.md b/packages/ZeroProb.jl/SONNET-TASKS.md deleted file mode 100644 index c827807f0..000000000 --- a/packages/ZeroProb.jl/SONNET-TASKS.md +++ /dev/null @@ -1,575 +0,0 @@ -# SONNET-TASKS.md -- ZeroProb.jl - -**Repo:** `hyperpolymath/ZeroProb.jl` -**Audit date:** 2026-02-12 -**Auditor model:** claude-opus-4-6 -**Honest completion:** ~62% - -STATE.scm claims 100% -- this is FALSE. The core types, measures, paradoxes, -and applications code is real and functional. But the README advertises an API -that does not exist (4 functions mentioned in docs are never implemented), -visualization has zero tests, there are phantom dependencies in Project.toml, -examples/ has nothing to do with ZeroProb.jl, license headers are wrong in -multiple template files, the `DiscreteZeroProbEvent` has no `relevance()` -dispatch, `handles_zero_prob_event` has a stub fallthrough that silently -returns true, `hausdorff_measure` only handles dimensions 0 and 1 (trivial), -and `plot_black_swan_impact` is defined but not exported. - ---- - -## GROUND RULES FOR SONNET - -1. Read this file top-to-bottom before starting. -2. Do ONE task at a time. Verify each before moving on. -3. Do NOT modify SONNET-TASKS.md itself (except to check off items if instructed). -4. Run all verification commands and confirm they pass. -5. Commit after each task with a descriptive message. -6. If a task says "line N", confirm the line number -- file may have shifted. -7. Do NOT introduce new dependencies unless the task explicitly says to. -8. Update `.machine_readable/STATE.scm` after all tasks are done to reflect honest completion. - ---- - -## TASK 1: Implement the 4 missing functions advertised in README.adoc - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/README.adoc` (lines 29, 76-89, 105-109, 115-128) -- `/var$REPOS_DIR/ZeroProb.jl/src/ZeroProb.jl` (export list) -- `/var$REPOS_DIR/ZeroProb.jl/src/measures.jl` (add implementations) - -**Problem:** -The README.adoc advertises these functions in code examples and the API reference: - -1. `density_ratio(dist, x, baseline)` -- a 3-argument form comparing density at x vs baseline point. The actual implementation (`measures.jl` line 46) is `density_ratio(event::ContinuousZeroProbEvent)` which takes a single event, not (dist, x, baseline). - -2. `hausdorff_dimension(set)` -- mentioned at README line 88 (`dimension = hausdorff_dimension(cantor_set)`). Never implemented anywhere. - -3. `construct_cantor_set(iterations=10)` -- mentioned at README line 87. Never implemented anywhere. - -4. `estimate_convergence_rate(ε_values, probs)` -- mentioned at README lines 108-109 and API reference at line 128. Never implemented anywhere. - -5. `epsilon_neighborhood_prob(dist, x, ε)` -- the README uses this name (lines 47, 105, 124) but the actual function is `epsilon_neighborhood(event, ε)`. Different name AND different signature (takes event, not dist+x). - -**What to do:** - -Option A (recommended): Implement the missing functions in `src/measures.jl`: -- `density_ratio(dist::Distribution, x::Real, baseline::Real)` -- returns `pdf(dist, x) / pdf(dist, baseline)` as a true ratio -- `hausdorff_dimension(points; method=:box_counting)` -- box-counting dimension estimation -- `construct_cantor_set(; iterations::Int=10)` -- returns the Cantor set as a vector of intervals -- `estimate_convergence_rate(ε_values::Vector, prob_values::Vector)` -- log-log linear regression for convergence rate -- `epsilon_neighborhood_prob` as an alias for `epsilon_neighborhood` with (dist, x, ε) signature - -Add all 5 to the export list in `src/ZeroProb.jl`. - -Option B: Fix the README to match the actual API. Only do this if Option A is too much work. - -**Verification:** -```julia -using ZeroProb, Distributions - -# density_ratio 3-arg form -dist = Normal(0, 1) -r = density_ratio(dist, 0.0, 3.0) -@assert r > 1.0 # Center is denser than tail -@assert r isa Float64 - -# hausdorff_dimension -cantor = construct_cantor_set(iterations=8) -dim = hausdorff_dimension(cantor) -@assert 0.5 < dim < 0.7 # Should be ~log(2)/log(3) ≈ 0.631 - -# estimate_convergence_rate -event = ContinuousZeroProbEvent(Normal(0,1), 0.0, :epsilon) -εs = [0.1, 0.01, 0.001, 0.0001] -probs = [epsilon_neighborhood(event, ε) for ε in εs] -rate = estimate_convergence_rate(εs, probs) -@assert rate isa Float64 -@assert rate > 0.0 - -# epsilon_neighborhood_prob alias -p = epsilon_neighborhood_prob(Normal(0,1), 0.0, 0.1) -@assert p > 0.0 -``` - ---- - -## TASK 2: Add `relevance()` dispatch for DiscreteZeroProbEvent - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/src/measures.jl` -- `/var$REPOS_DIR/ZeroProb.jl/test/test_measures.jl` - -**Problem:** -`relevance()` is only implemented for `ContinuousZeroProbEvent` (measures.jl line 140). There is no `relevance()` method for `DiscreteZeroProbEvent`. Calling `relevance(DiscreteZeroProbEvent(...))` will throw a MethodError at runtime. - -The `DiscreteZeroProbEvent` struct does not have a `relevance_measure` field, so the dispatch needs a different approach -- it should return the pdf value (which is 0 by construction, since the constructor asserts `p == 0.0`). - -**What to do:** -Add to `measures.jl`: -```julia -function relevance(event::DiscreteZeroProbEvent{T}; kwargs...) where T - # For discrete zero-prob events, relevance is based on the probability mass - # which is 0 by construction. Return 0.0 to be consistent. - return 0.0 -end -``` - -Also add `relevance_score` for `DiscreteZeroProbEvent`: -```julia -function relevance_score(event::DiscreteZeroProbEvent{T}, application::Symbol) where T - return 0.0 # Discrete zero-prob events have no relevance by construction -end -``` - -Add tests to `test_measures.jl`: -```julia -@testset "DiscreteZeroProbEvent relevance" begin - dist = Geometric(0.5) - event = DiscreteZeroProbEvent(dist, -1) - @test relevance(event) == 0.0 - @test relevance_score(event, :black_swan) == 0.0 -end -``` - -**Verification:** -```julia -using ZeroProb, Distributions -dist = Geometric(0.5) -event = DiscreteZeroProbEvent(dist, -1) -@assert relevance(event) == 0.0 -@assert relevance_score(event, :black_swan) == 0.0 -@assert relevance_score(event, :betting) == 0.0 -``` - ---- - -## TASK 3: Export and test `plot_black_swan_impact` - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/src/ZeroProb.jl` (lines 90-91 export list) -- `/var$REPOS_DIR/ZeroProb.jl/src/visualization.jl` (line 216, `plot_black_swan_impact`) - -**Problem:** -`plot_black_swan_impact` is defined in `visualization.jl` (line 216) but is NOT in the export list in `ZeroProb.jl` (lines 90-91). The export list only exports: -``` -plot_zero_probability, plot_continuum_paradox, -plot_density_vs_probability, plot_epsilon_neighborhood -``` - -Missing: `plot_black_swan_impact`. - -**What to do:** -Add `plot_black_swan_impact` to the export list on line 91 of `src/ZeroProb.jl`. - -**Verification:** -```julia -using ZeroProb -@assert isdefined(ZeroProb, :plot_black_swan_impact) -@assert hasmethod(plot_black_swan_impact, Tuple{BlackSwanEvent}) -``` - ---- - -## TASK 4: Add visualization tests - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/test/runtests.jl` -- Create `/var$REPOS_DIR/ZeroProb.jl/test/test_visualization.jl` - -**Problem:** -There are ZERO tests for any of the 5 visualization functions: -- `plot_zero_probability` -- `plot_continuum_paradox` -- `plot_density_vs_probability` -- `plot_epsilon_neighborhood` -- `plot_black_swan_impact` - -The visualization module `using Plots` at the top of `visualization.jl`, but Plots is listed as a dependency in Project.toml, so it should load. However, none of the plotting functions are tested to verify they at least return a plot object without crashing. - -**What to do:** -Create `test/test_visualization.jl`: -```julia -# SPDX-License-Identifier: CC-BY-SA-4.0 - -using Plots - -@testset "Visualization" begin - @testset "plot_zero_probability" begin - dist = Normal(0, 1) - event = ContinuousZeroProbEvent(dist, 0.0, :density) - p = plot_zero_probability(event) - @test p isa Plots.Plot - end - - @testset "plot_continuum_paradox" begin - dist = Normal(0, 1) - p = plot_continuum_paradox(dist, num_points=5) - @test p isa Plots.Plot - end - - @testset "plot_density_vs_probability" begin - event = ContinuousZeroProbEvent(Normal(0, 1), 0.0, :density) - p = plot_density_vs_probability(event, ε_max=1.0) - @test p isa Plots.Plot - end - - @testset "plot_epsilon_neighborhood" begin - event = ContinuousZeroProbEvent(Normal(0, 1), 0.0, :epsilon) - p = plot_epsilon_neighborhood(event, ε=0.5) - @test p isa Plots.Plot - end - - @testset "plot_black_swan_impact" begin - crash = MarketCrashEvent(severity=:catastrophic) - p = plot_black_swan_impact(crash, samples=100) - @test p isa Plots.Plot - end -end -``` - -Add `include("test_visualization.jl")` to `test/runtests.jl`. - -**Verification:** -```bash -cd /var$REPOS_DIR/ZeroProb.jl -julia --project=. -e 'using Pkg; Pkg.test()' -``` -All 5 visualization tests should pass. - ---- - -## TASK 5: Remove phantom dependencies from Project.toml - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/Project.toml` (lines 8, 11) - -**Problem:** -Project.toml lists two dependencies that are never used anywhere in the source code: - -1. `Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"` (line 8) -- grep confirms Makie is never imported or used in any `.jl` file. The visualization module uses `Plots`, not `Makie`. - -2. `Zstd_jll = "3161d3a3-bdf6-5164-811a-617609db77b4"` (line 11) -- grep confirms Zstd_jll is never imported or used anywhere. This is a compression library JLL wrapper with no connection to probability theory. - -These add unnecessary compile-time overhead and dependency weight. - -**What to do:** -1. Remove the `Makie` line from `[deps]` -2. Remove the `Zstd_jll` line from `[deps]` -3. Remove the `Makie = "0.20"` line from `[compat]` -4. Remove the `Zstd_jll = "1.5.7"` line from `[compat]` -5. Run `julia --project=. -e 'using Pkg; Pkg.resolve()'` to regenerate Manifest.toml - -**Verification:** -```bash -cd /var$REPOS_DIR/ZeroProb.jl -julia --project=. -e 'using Pkg; Pkg.resolve(); using ZeroProb; println("OK")' -``` -Should load without error and without Makie/Zstd_jll. - ---- - -## TASK 6: Fix the `handles_zero_prob_event` stub fallthrough - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/src/applications.jl` (lines 339-341) - -**Problem:** -The catch-all branch at the bottom of `handles_zero_prob_event` (line 339-341): -```julia - else - @warn "No specific `handles_zero_prob_event` implementation for type $(typeof(event)). Returning true as a stub." - return true - end -``` - -This silently returns `true` for any unknown event type, which is dangerous. If someone creates a new `ZeroProbEvent` subtype, `handles_zero_prob_event` will claim the model handles it when it was never actually tested. - -**What to do:** -Change line 341 from `return true` to `return false` and update the warning message: -```julia - else - @warn "No specific `handles_zero_prob_event` implementation for type $(typeof(event)). Returning false (unverified)." - return false - end -``` - -Also add a test for this behavior in `test/test_applications.jl`: -```julia -@testset "handles_zero_prob_event unknown type" begin - # Create a custom ZeroProbEvent subtype - struct TestZeroProbEvent <: ZeroProbEvent end - model = x -> x - # Unknown types should return false (not silently true) - @test handles_zero_prob_event(model, TestZeroProbEvent()) == false -end -``` - -**Verification:** -```julia -using ZeroProb -struct MyCustomEvent <: ZeroProbEvent end -model = x -> x -@assert handles_zero_prob_event(model, MyCustomEvent()) == false -``` - ---- - -## TASK 7: Replace examples/ with actual ZeroProb.jl examples - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/examples/SafeDOMExample.res` (DELETE) -- `/var$REPOS_DIR/ZeroProb.jl/examples/web-project-deno.json` (DELETE) -- Create `/var$REPOS_DIR/ZeroProb.jl/examples/basic_usage.jl` -- Create `/var$REPOS_DIR/ZeroProb.jl/examples/black_swan_analysis.jl` - -**Problem:** -The examples/ directory contains two files that have NOTHING to do with ZeroProb.jl: -- `SafeDOMExample.res` -- a ReScript file about DOM mounting with AGPL license header -- `web-project-deno.json` -- a Deno project config for a web project - -These are leftover RSR template files. A Julia probability library should have Julia examples. - -**What to do:** -1. Delete `SafeDOMExample.res` and `web-project-deno.json` -2. Create `examples/basic_usage.jl` demonstrating: - - Creating ContinuousZeroProbEvent instances - - Computing probability (always 0) vs relevance (non-zero) - - All three relevance measures (density, hausdorff, epsilon) - - The continuum paradox function -3. Create `examples/black_swan_analysis.jl` demonstrating: - - Creating a MarketCrashEvent - - Computing probability and expected impact - - Using handles_black_swan to test a model - - BettingEdgeCase expected value computation - -Both files must have: -- `# SPDX-License-Identifier: CC-BY-SA-4.0` header -- `# Copyright (c) 2026 Jonathan D.A. Jewell ` -- Comments explaining each step -- Must be runnable: `julia --project=.. examples/basic_usage.jl` - -**Verification:** -```bash -cd /var$REPOS_DIR/ZeroProb.jl -julia --project=. examples/basic_usage.jl -julia --project=. examples/black_swan_analysis.jl -``` -Both should run without error and produce output. - ---- - -## TASK 8: Fix AGPL license headers in template files - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/.gitignore` (line 1: `# SPDX-License-Identifier: CC-BY-SA-4.0`) -- `/var$REPOS_DIR/ZeroProb.jl/.gitattributes` (line 1: `# SPDX-License-Identifier: CC-BY-SA-4.0`) -- `/var$REPOS_DIR/ZeroProb.jl/ffi/zig/build.zig` (line 2: `// SPDX-License-Identifier: CC-BY-SA-4.0`) -- `/var$REPOS_DIR/ZeroProb.jl/ffi/zig/src/main.zig` (line 6: `// SPDX-License-Identifier: CC-BY-SA-4.0`) -- `/var$REPOS_DIR/ZeroProb.jl/ffi/zig/test/integration_test.zig` (line 2: `// SPDX-License-Identifier: CC-BY-SA-4.0`) -- `/var$REPOS_DIR/ZeroProb.jl/docs/CITATIONS.adoc` (line 13: `license = {AGPL-3.0-or-later}`) -- `/var$REPOS_DIR/ZeroProb.jl/RSR_OUTLINE.adoc` (lines 72, 160 mention AGPL) - -**Problem:** -Per CLAUDE.md, AGPL-3.0 is the OLD license and must NEVER be used. All hyperpolymath original code must use `MPL-2.0`. These are leftover RSR template headers that were never updated. - -**What to do:** -Replace `AGPL-3.0-or-later` with `MPL-2.0` in all files listed above. - -For `docs/CITATIONS.adoc`, also fix the author from `Polymath, Hyper` to `Jewell, Jonathan D.A.`, the title from `RSR-template-repo` to `ZeroProb.jl`, the year from `2025` to `2026`, and the URL to `https://github.com/hyperpolymath/ZeroProb.jl`. - -For `RSR_OUTLINE.adoc`, update line 72 and 160 to reference MPL-2.0 instead of AGPL. - -**Verification:** -```bash -cd /var$REPOS_DIR/ZeroProb.jl -grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.adoc" --include=".git*" . | grep -v ".git/" -``` -Should return NO matches (zero lines). - ---- - -## TASK 9: Make `hausdorff_measure` non-trivial (support dimensions > 1) - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/src/measures.jl` (lines 70-78) - -**Problem:** -The current `hausdorff_measure` implementation is trivial: -```julia -function hausdorff_measure(event::ContinuousZeroProbEvent{T}, dimension::Int=0) where T - if dimension == 0 - return 1.0 # Single point has unit 0-dimensional Hausdorff measure - elseif dimension == 1 - return 0.0 # But zero 1-dimensional measure - else - throw(ArgumentError("Only dimensions 0 and 1 currently supported")) - end -end -``` - -This throws on any dimension other than 0 or 1. For a point set, the Hausdorff measure of dimension d > 0 is always 0 (a single point has zero d-dimensional measure for any d > 0). Dimension 0 is always 1 (counting measure). So the function should handle all non-negative integer dimensions, not just 0 and 1. - -**What to do:** -Replace the function body: -```julia -function hausdorff_measure(event::ContinuousZeroProbEvent{T}, dimension::Int=0) where T - @assert dimension >= 0 "Hausdorff dimension must be non-negative" - if dimension == 0 - return 1.0 # Single point has unit 0-dimensional Hausdorff measure (counting measure) - else - return 0.0 # Single point has zero d-dimensional Hausdorff measure for all d > 0 - end -end -``` - -Update tests in `test_measures.jl` to cover higher dimensions: -```julia -@testset "hausdorff_measure higher dimensions" begin - dist = Normal(0, 1) - event = ContinuousZeroProbEvent(dist, 0.0, :hausdorff) - @test hausdorff_measure(event, 0) == 1.0 - @test hausdorff_measure(event, 1) == 0.0 - @test hausdorff_measure(event, 2) == 0.0 - @test hausdorff_measure(event, 10) == 0.0 - @test_throws AssertionError hausdorff_measure(event, -1) -end -``` - -**Verification:** -```julia -using ZeroProb, Distributions -event = ContinuousZeroProbEvent(Normal(0,1), 0.0, :hausdorff) -@assert hausdorff_measure(event, 0) == 1.0 -@assert hausdorff_measure(event, 2) == 0.0 -@assert hausdorff_measure(event, 5) == 0.0 -# Should NOT throw: -hausdorff_measure(event, 100) -``` - ---- - -## TASK 10: Fix STATE.scm to reflect honest completion - -**Files:** -- `/var$REPOS_DIR/ZeroProb.jl/.machine_readable/STATE.scm` - -**Problem:** -STATE.scm line 22 claims `(overall-completion 100)` and line 21 claims `(phase "complete")`. This is false. After completing tasks 1-9, update STATE.scm to reflect the true state. - -Before tasks 1-9 are done, the honest completion is ~62%: -- Types: 100% (solid) -- Measures: 70% (missing DiscreteZeroProbEvent dispatch, hausdorff trivial, advertised functions missing) -- Paradoxes: 95% (functional, well-documented) -- Applications: 80% (stub fallthrough, placeholder comments) -- Visualization: 50% (implemented but untested, one function not exported) -- Examples: 0% (wrong language, wrong project) -- Documentation: 60% (README advertises vaporware API) -- License compliance: 70% (AGPL remnants throughout) - -After tasks 1-9 are done, it should be ~90%. - -**What to do:** -Update STATE.scm: -- `(phase "active")` (or "complete" only after all tasks done) -- `(overall-completion NN)` -- set to the actual number after completing other tasks -- Update `(updated ...)` to today's date -- Add honest component completion percentages -- Add blockers if any remain -- Add session history entry documenting this audit - -**Verification:** -```bash -cat /var$REPOS_DIR/ZeroProb.jl/.machine_readable/STATE.scm -# Verify: no "100" completion unless everything is actually done -# Verify: updated date is 2026-02-12 or later -# Verify: phase is not "complete" unless all tasks are done -``` - ---- - -## FINAL VERIFICATION - -After ALL tasks are completed, run this full verification sequence: - -```bash -cd /var$REPOS_DIR/ZeroProb.jl - -# 1. Full test suite passes -julia --project=. -e 'using Pkg; Pkg.test()' - -# 2. No AGPL references remain -grep -r "AGPL" --include="*.jl" --include="*.zig" --include="*.adoc" --include=".git*" . | grep -v ".git/" | wc -l -# Expected: 0 - -# 3. No phantom dependencies -julia --project=. -e 'using Pkg; deps = keys(Pkg.project().dependencies); @assert !("Makie" in deps); @assert !("Zstd_jll" in deps); println("No phantom deps")' - -# 4. All advertised functions exist -julia --project=. -e ' -using ZeroProb, Distributions - -# Core types -@assert isdefined(ZeroProb, :ContinuousZeroProbEvent) -@assert isdefined(ZeroProb, :DiscreteZeroProbEvent) -@assert isdefined(ZeroProb, :AlmostSureEvent) -@assert isdefined(ZeroProb, :SureEvent) - -# Measures -@assert isdefined(ZeroProb, :probability) -@assert isdefined(ZeroProb, :relevance) -@assert isdefined(ZeroProb, :density_ratio) -@assert isdefined(ZeroProb, :hausdorff_measure) -@assert isdefined(ZeroProb, :epsilon_neighborhood) -@assert isdefined(ZeroProb, :relevance_score) - -# Visualization -@assert isdefined(ZeroProb, :plot_zero_probability) -@assert isdefined(ZeroProb, :plot_continuum_paradox) -@assert isdefined(ZeroProb, :plot_density_vs_probability) -@assert isdefined(ZeroProb, :plot_epsilon_neighborhood) -@assert isdefined(ZeroProb, :plot_black_swan_impact) - -# Applications -@assert isdefined(ZeroProb, :BlackSwanEvent) -@assert isdefined(ZeroProb, :MarketCrashEvent) -@assert isdefined(ZeroProb, :BettingEdgeCase) -@assert isdefined(ZeroProb, :handles_black_swan) -@assert isdefined(ZeroProb, :handles_zero_prob_events) - -println("All exports verified") -' - -# 5. Examples run -julia --project=. examples/basic_usage.jl -julia --project=. examples/black_swan_analysis.jl - -# 6. DiscreteZeroProbEvent relevance works -julia --project=. -e ' -using ZeroProb, Distributions -event = DiscreteZeroProbEvent(Geometric(0.5), -1) -@assert relevance(event) == 0.0 -println("DiscreteZeroProbEvent relevance OK") -' - -# 7. Unknown event type returns false (not true) -julia --project=. -e ' -using ZeroProb -struct TestEvent <: ZeroProbEvent end -@assert handles_zero_prob_event(x->x, TestEvent()) == false -println("Unknown event fallthrough returns false OK") -' - -# 8. hausdorff_measure handles arbitrary dimensions -julia --project=. -e ' -using ZeroProb, Distributions -event = ContinuousZeroProbEvent(Normal(0,1), 0.0, :hausdorff) -@assert hausdorff_measure(event, 5) == 0.0 -println("hausdorff_measure arbitrary dims OK") -' - -# 9. STATE.scm is honest -grep "overall-completion 100" .machine_readable/STATE.scm -# Expected: no output (should NOT claim 100% unless everything is done) -``` - -If all 9 verification steps pass with expected output, the audit tasks are complete. diff --git a/packages/ZeroProb.jl/TOPOLOGY.md b/packages/ZeroProb.jl/TOPOLOGY.adoc similarity index 89% rename from packages/ZeroProb.jl/TOPOLOGY.md rename to packages/ZeroProb.jl/TOPOLOGY.adoc index bf2318d7c..9ace48cc9 100644 --- a/packages/ZeroProb.jl/TOPOLOGY.md +++ b/packages/ZeroProb.jl/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== ZeroProb.jl — Project Topology -# ZeroProb.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -43,11 +39,11 @@ │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE MEASURES @@ -71,26 +67,27 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~95% Stable Mathematical Toolkit -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... ZeroProb Types ──────► Density Ratios ──────► Paradox Demonstrations │ Hausdorff Measure ───► Epsilon-Neighborhood ───────┤ │ Black Swans ─────────► Application Models ────► COMPLETE -``` +.... -## 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/registries/General/CONTRIBUTING.adoc b/registries/General/CONTRIBUTING.adoc new file mode 100644 index 000000000..d512386b9 --- /dev/null +++ b/registries/General/CONTRIBUTING.adoc @@ -0,0 +1,270 @@ +== Contribution guidelines + +Anyone can help improve the General registry! Here are a few ways. + +=== As a package author + +You can register your package! See +https://github.com/JuliaRegistries/General#registering-a-package-in-general[Registering +a package in General] in the README for how to do that. The "`FAQ`" +section in the README helps answer many more questions, like +https://github.com/JuliaRegistries/General#do-i-need-to-register-a-package-to-install-it[do +I need to register a package to install it?], +https://github.com/JuliaRegistries/General#should-i-register-my-package[should +I register my package?], and more. + +* Please be aware of the +https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules[package +naming guidelines] +* We strongly encourage authors to follow best practices like having +documentation (or a descriptive README), tests, and continuous +integration. + +=== As a Julia community member + +You (yes, you!) can help General be the best registry it can be. + +==== New package registrations + +The first step to getting involved with General is to check out new +package registrations. They are filed under the +https://github.com/JuliaRegistries/General/pulls?q=is%3Apr+is%3Aopen+label%3A%22new+package%22["`new +package`" label], and a automatic feed posts them in the +`+#new-packages-feed+` channel in the +https://julialang.org/slack/[community Slack] or +https://julialang.zulipchat.com/register/[Zulip]. + +When registration is triggered for a new package (or new version of a +package), link:RegistryCI[RegistryCI.jl]-powered AutoMerge automatically +runs and performs +https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/[some +basic checks]. These are merely guidelines, and not all checks must pass +— if a check fails, the registration can still be manually merged. There +are a few ways to help here: + +[arabic] +. First, whenever you are engaging with a package author, remember to +always be polite and kind– if you are feeling frustrated, it may be +better to not comment at all and let someone else respond instead. Not +everyone understands things from the same explanations, and some folks +may need to translate or overcome other barriers to understanding, or +may simply disagree with you. When we are helping maintain the General +registry, we are acting as representatives of the Julia community, and +need to be mindful of that. +. If an AutoMerge guideline fails and the package author does not seem +to know how to address it, you can help guide them through the process. +Pointing them to the FAQ can help, as can updating the FAQ and other +guidance to make the process more clear. Sometimes folks also just need +a bit of help to understand the process, and writing a note can help. +. If an AutoMerge fails but you think the package should be manually +merged, comment in the PR to explain why. +* One common issue here is the name similarity check. This exists to +prevent malicious +https://en.wikipedia.org/wiki/Typosquatting[typosquatting]. For example, +https://github.com/FluxML/Flux.jl[Flux] is a popular machine learning +package. A malicious actor could try to register FIux (with an +uppercase-eye instead of a lowercase-ell), and encourage users to +install it by writing a tutorial or such. They could then add malicious +code to the package to try to steal secrets. Such an event would be an +extreme security violation and the package would be yanked or removed +from the registry as soon as possible– but we try to be a bit safer by +proactively screening names to require manual merging if they are "`too +similar`" to an existing package name. ++ +If a package fails the name similarity check, you can help out by taking +a look at the two names as well as the package code itself, and try to +make a determination if it looks "`too close`" (e.g. Websockets vs +WebSocket), and if the package code contains anything that would +indicate malicious activity. You can make a comment in the PR indicating +whether or not you think the name similarity is okay. Include +`+[noblock]+` in the comment if you don’t want to block AutoMerge. If +you have link:permissions[triage]-level access or higher to General, you +can additionally override automerge by adding the label _Override +AutoMerge: name similarity is okay_. +. Regardless of AutoMerge’s status, if you think perhaps something more +should be done before registration, feel free to leave a comment in the +PR explaining what you think should be done first. Any comment without +`+[noblock]+` included in it will block AutoMerge from automatically +merging the pull request (editing `+[noblock]+` into old comments *will* +allow it to resume). +* For example, occasionally someone will register a package without any +content in order to reserve the package name, with the intent to add +content later. We don’t allow that in General, and ask authors to add +content first before registering. +* Sometimes authors register packages without any description of what +the package is for in the README or without documentation. Since +registration is a mechanism to share code with the whole Julia +community, such a description is important for the package to be useful. +While we don’t strictly require such documentation, it can help to give +a polite and gentle nudge in the PR comments, or show folks how to write +documentation and/or what is helpful to include in a README. We want to +encourage best practices (in an inclusive and friendly way!) even when +they are not strict requirements. +* Sometimes package names are possibly confusing or don’t conform to our +link:naming-guidelines[naming guidelines], but AutoMerge does not detect +this. Feel free to comment, describing what you think is confusing or +non-compliant about the current name, and any suggestions you have for a +more clear name. + +==== Other PRs to General + +Sometimes, the registry needs to be updated in other ways that involve +manual pull requests (PRs) rather than auto-generated ones. The most +common reason is to update the URL for a repository. + +===== Updating the URL for a repository + +If someone transfers a GitHub repository, +https://github.com/JuliaRegistries/General#how-do-i-transfer-a-package-to-an-organization-or-another-user[we +ask] that they update the URL stored in General. This is done by +manually making a PR to General to update the URL. You can review such a +PR by checking that the old URL redirects to the new one. * If it does, +that’s a clear sign that the change is legitimate and the new URL is +correct. If you have write permissions to General, you can merge the PR; +otherwise you can approve it or comment. * If it does not, you can ask +the author why. This should be handled on a case-by-case basis. Be sure +to check that: 1. The package is not being hijacked; check for example +that the person making the PR has registered a version of the package +before, indicating they are authorized to do so. 2. All the registered +revisions of the package are accessible in the new repository. +Specifically, this means checking that all the git-tree-shas can be +found in the new repository. See +link:#appendix-checking-if-a-repository-contains-all-registered-versions-of-a-package[the +appendix] below for a script to automate this checking. + +==== Other ways to help + +Besides helping out with PRs to General, you can… + +* …improve https://github.com/JuliaRegistries/General#general[General’s +README], the +https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/[RegistryCI +documentation], or these guidelines! +* …add new checks to AutoMerge (in RegistryCI) or improve existing ones. +* …address open issues in +https://github.com/JuliaRegistries/General/issues[General], +https://github.com/JuliaRegistries/RegistryCI.jl/issues[RegistryCI.jl], +or +https://github.com/JuliaRegistries/Registrator.jl/issues[Registrator.jl]. +* …write blog posts and documentation to help folks get started with +writing documentation, tests, and setting up CI for their own packages, +and find appropriate places to link to it and help out new package +authors. + +Additionally, if you have elevated permissions to General, there’s a few +more things you can do: + +* [triage] You can add or remove labels to PRs to help communicate the +status and to automatically override AutoMerge for name similairty +failures +** Specifically, adding the label +`+Override AutoMerge: name similarity is okay+` will retrigger AutoMerge +and cause it to ignore the distance check between the package name and +existing package names. This will not override any other guidelines +(e.g. name too short). +* [triage] You can close PRs if the package author requests it or the +registration is superseded by another registration request. +* [write] You can merge PRs that have the _needs to be manually merged +in 3 days_ label once the requisite waiting period has passed, assuming +there are no outstanding objections in the PR comments. +* [write] You can choose to facilitate expedited merge requests, after +manually reviewing the package. You generally should not merge your own +registrations or those you are involved with (though you can make +requests to another maintainer). See also +https://github.com/JuliaRegistries/General/#who-can-approve-an-early-merge[this +FAQ entry]. +* [write] You can merge improvements to the README, these guidelines, or +our workflows. +* [admin] You can give other contributors triage-level access so they +can apply labels to PRs, or write-level permissions to merge PRs. + +=== Appendix: Checking if a repository contains all registered versions of a package + +When someone wishes to move a package from one repo to another, it is +important that the new repo contains all of the tree hashes +corresponding to registered versions of a package. That way these old +versions of the package can continue to be installed from the new +repository. In order to check if a given repository contains all of the +registered versions of a package, the following script can be used: + +[source,julia] +---- +using RegistryInstances, UUIDs, Git + +const GENERAL_UUID = UUID("23338594-aafe-5451-b93e-139f81909106") + +pretty_print_row(row) = println(row.pkg_name, ": v", row.version, " ", row.found ? "found" : "is missing") +pretty_print_table(table) = foreach(pretty_print_row, table) + +function check_all_found(table) + idx = findfirst(row -> !row.found, table) + idx === nothing && return nothing + row = table[idx] + error(string("Repository missing v", row.version, " of package $(row.pkg_name)")) +end + +function check_packages_versions(pkg_names, repo_url; registry_uuid=GENERAL_UUID, verbose=true, throw=true) + if isdir(repo_url) + dir = repo_url + else + dir = mktempdir() + run(`$(git()) clone $(repo_url) $dir`) + end + + registry = only(filter!(r -> r.uuid == registry_uuid, reachable_registries())) + + table = @NamedTuple{pkg_name::String, version::VersionNumber, found::Bool, tree_sha::Base.SHA1}[] + + for pkg_name in pkg_names + pkg = registry.pkgs[only(uuids_from_name(registry, pkg_name))] + versions = registry_info(pkg).version_info + for version in sort(collect(keys(versions))) + tree_sha = versions[version].git_tree_sha1 + found = success(`$(git()) -C $dir rev-parse -q --verify "$(tree_sha)^{tree}"`) + + push!(table, (; pkg_name, version, found, tree_sha)) + end + end + verbose && pretty_print_table(table) + throw && check_all_found(table) + return table +end + +check_package_versions(pkg_name, repo_url; kw...) = check_packages_versions([pkg_name], repo_url; kw...) +---- + +For example, in +https://github.com/JuliaRegistries/General/pull/75319[General#75319], a +package author wanted to update the URL associated to their package +"`FastParzenWindows`". At the time, the package had 1 registered +version. We can check that it is present in the new repository via: + +[source,julia] +---- +julia> check_package_versions("FastParzenWindows", "https://github.com/ngiann/FastParzenWindows.jl.git"); +Cloning into '/var/folders/jb/plyyfc_d2bz195_0rc0n_zcw0000gp/T/jl_ke9E8C'... +...text omitted... +FastParzenWindows: v0.1.2 found +---- + +We see that this version was found in the new repository. This script +was based on +https://github.com/JuliaRegistries/General/pull/35965#issuecomment-832721704[this +comment from General#35965], which involved checking if 4 packages in +the same repository all had their versions present in the new +repository. That example can be handled as follows: + +[source,julia] +---- +pkg_names = ["ReinforcementLearningBase", "ReinforcementLearningCore", + "ReinforcementLearningEnvironments", "ReinforcementLearningZoo"] +check_packages_versions(pkg_names, "https://github.com/JuliaReinforcementLearning/ReinforcementLearning.jl.git") +---- + +You can also use this script against local repositories when modifying +Git commit history: + +[source,julia] +---- +check_package_versions("FastParzenWindows", ".") +---- diff --git a/registries/General/CONTRIBUTING.md b/registries/General/CONTRIBUTING.md deleted file mode 100644 index f1eaba4d2..000000000 --- a/registries/General/CONTRIBUTING.md +++ /dev/null @@ -1,171 +0,0 @@ -# Contribution guidelines - -Anyone can help improve the General registry! Here are a few ways. - -## As a package author - -You can register your package! -See [Registering a package in General](https://github.com/JuliaRegistries/General#registering-a-package-in-general) in the README for how to do that. -The "FAQ" section in the README helps answer many more questions, like [do I need to register a package to install it?](https://github.com/JuliaRegistries/General#do-i-need-to-register-a-package-to-install-it), [should I register my package?](https://github.com/JuliaRegistries/General#should-i-register-my-package), and more. - -* Please be aware of the [package naming guidelines](https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules) -* We strongly encourage authors to follow best practices like having documentation (or a descriptive README), tests, and continuous integration. - -## As a Julia community member - -You (yes, you!) can help General be the best registry it can be. - -### New package registrations - -The first step to getting involved with General is to check out new package registrations. -They are filed under the ["new package" label](https://github.com/JuliaRegistries/General/pulls?q=is%3Apr+is%3Aopen+label%3A%22new+package%22), and a automatic feed posts them in the `#new-packages-feed` channel in the [community Slack](https://julialang.org/slack/) or [Zulip](https://julialang.zulipchat.com/register/). - -When registration is triggered for a new package (or new version of a package), [RegistryCI.jl](RegistryCI)-powered AutoMerge automatically runs and performs [some basic checks](https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/). -These are merely guidelines, and not all checks must pass --- if a check fails, the registration can still be manually merged. -There are a few ways to help here: - -1. First, whenever you are engaging with a package author, remember to always be polite and kind-- if you are feeling frustrated, it may be better to not comment at all and let someone else respond instead. -Not everyone understands things from the same explanations, and some folks may need to translate or overcome other barriers to understanding, or may simply disagree with you. -When we are helping maintain the General registry, we are acting as representatives of the Julia community, and need to be mindful of that. -2. If an AutoMerge guideline fails and the package author does not seem to know how to address it, you can help guide them through the process. -Pointing them to the [FAQ](FAQ) can help, as can updating the FAQ and other guidance to make the process more clear. -Sometimes folks also just need a bit of help to understand the process, and writing a note can help. -3. If an AutoMerge fails but you think the package should be manually merged, comment in the PR to explain why. - * One common issue here is the name similarity check. - This exists to prevent malicious [typosquatting](https://en.wikipedia.org/wiki/Typosquatting). - For example, [Flux](https://github.com/FluxML/Flux.jl) is a popular machine learning package. - A malicious actor could try to register FIux (with an uppercase-eye instead of a lowercase-ell), and encourage users to install it by writing a tutorial or such. - They could then add malicious code to the package to try to steal secrets. - Such an event would be an extreme security violation and the package would be yanked or removed from the registry as soon as possible-- but we try to be a bit safer by proactively screening names to require manual merging if they are "too similar" to an existing package name. - - If a package fails the name similarity check, you can help out by taking a look at the two names as well as the package code itself, and try to make a determination if it looks "too close" (e.g. Websockets vs WebSocket), and if the package code contains anything that would indicate malicious activity. - You can make a comment in the PR indicating whether or not you think the name similarity is okay. Include `[noblock]` in the comment if you don't want to block AutoMerge. - If you have [triage](permissions)-level access or higher to General, you can additionally override automerge by adding the label _Override AutoMerge: name similarity is okay_. - -4. Regardless of AutoMerge's status, if you think perhaps something more should be done before registration, feel free to leave a comment in the PR explaining what you think should be done first. -Any comment without `[noblock]` included in it will block AutoMerge from automatically merging the pull request (editing `[noblock]` into old comments **will** allow it to resume). - * For example, occasionally someone will register a package without any content in order to reserve the package name, with the intent to add content later. - We don't allow that in General, and ask authors to add content first before registering. - * Sometimes authors register packages without any description of what the package is for in the README or without documentation. - Since registration is a mechanism to share code with the whole Julia community, such a description is important for the package to be useful. - While we don't strictly require such documentation, it can help to give a polite and gentle nudge in the PR comments, or show folks how to write documentation and/or what is helpful to include in a README. - We want to encourage best practices (in an inclusive and friendly way!) even when they are not strict requirements. - * Sometimes package names are possibly confusing or don't conform to our [naming guidelines](naming-guidelines), but AutoMerge does not detect this. - Feel free to comment, describing what you think is confusing or non-compliant about the current name, and any suggestions you have for a more clear name. - -### Other PRs to General - -Sometimes, the registry needs to be updated in other ways that involve manual pull requests (PRs) rather than auto-generated ones. -The most common reason is to update the URL for a repository. - -#### Updating the URL for a repository - -If someone transfers a GitHub repository, [we ask](https://github.com/JuliaRegistries/General#how-do-i-transfer-a-package-to-an-organization-or-another-user) that they update the URL stored in General. -This is done by manually making a PR to General to update the URL. -You can review such a PR by checking that the old URL redirects to the new one. -* If it does, that's a clear sign that the change is legitimate and the new URL is correct. - If you have write permissions to General, you can merge the PR; otherwise you can approve it or comment. -* If it does not, you can ask the author why. This should be handled on a case-by-case basis. Be sure to check that: - 1. The package is not being hijacked; check for example that the person making the PR has registered a version of the package before, indicating they are authorized to do so. - 2. All the registered revisions of the package are accessible in the new repository. - Specifically, this means checking that all the git-tree-shas can be found in the new repository. - See [the appendix](#appendix-checking-if-a-repository-contains-all-registered-versions-of-a-package) below for a script to automate this checking. - -### Other ways to help - -Besides helping out with PRs to General, you can... - -* ...improve [General's README](https://github.com/JuliaRegistries/General#general), the [RegistryCI documentation](https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/), or these guidelines! -* ...add new checks to AutoMerge (in [RegistryCI](RegistryCI)) or improve existing ones. -* ...address open issues in [General](https://github.com/JuliaRegistries/General/issues), [RegistryCI.jl](https://github.com/JuliaRegistries/RegistryCI.jl/issues), or [Registrator.jl](https://github.com/JuliaRegistries/Registrator.jl/issues). -* ...write blog posts and documentation to help folks get started with writing documentation, tests, and setting up CI for their own packages, and find appropriate places to link to it and help out new package authors. - -Additionally, if you have elevated [permissions](permissions) to General, there's a few more things you can do: - -* [triage] You can add or remove labels to PRs to help communicate the status and to automatically override AutoMerge for name similairty failures - * Specifically, adding the label `Override AutoMerge: name similarity is okay` will retrigger AutoMerge and cause it to ignore the distance check between the package name and existing package names. This will not override any other guidelines (e.g. name too short). -* [triage] You can close PRs if the package author requests it or the registration is superseded by another registration request. -* [write] You can merge PRs that have the _needs to be manually merged in 3 days_ label once the requisite waiting period has passed, assuming there are no outstanding objections in the PR comments. -* [write] You can choose to facilitate expedited merge requests, after manually reviewing the package. -You generally should not merge your own registrations or those you are involved with (though you can make requests to another maintainer). See also [this FAQ entry](https://github.com/JuliaRegistries/General/#who-can-approve-an-early-merge). -* [write] You can merge improvements to the README, these guidelines, or our workflows. -* [admin] You can give other contributors triage-level access so they can apply labels to PRs, or write-level permissions to merge PRs. - -## Appendix: Checking if a repository contains all registered versions of a package - -When someone wishes to move a package from one repo to another, it is important that the new repo contains all of the tree hashes corresponding to registered versions of a package. That way these old versions of the package can continue to be installed from the new repository. In order to check if a given repository contains all of the registered versions of a package, the following script can be used: - -```julia -using RegistryInstances, UUIDs, Git - -const GENERAL_UUID = UUID("23338594-aafe-5451-b93e-139f81909106") - -pretty_print_row(row) = println(row.pkg_name, ": v", row.version, " ", row.found ? "found" : "is missing") -pretty_print_table(table) = foreach(pretty_print_row, table) - -function check_all_found(table) - idx = findfirst(row -> !row.found, table) - idx === nothing && return nothing - row = table[idx] - error(string("Repository missing v", row.version, " of package $(row.pkg_name)")) -end - -function check_packages_versions(pkg_names, repo_url; registry_uuid=GENERAL_UUID, verbose=true, throw=true) - if isdir(repo_url) - dir = repo_url - else - dir = mktempdir() - run(`$(git()) clone $(repo_url) $dir`) - end - - registry = only(filter!(r -> r.uuid == registry_uuid, reachable_registries())) - - table = @NamedTuple{pkg_name::String, version::VersionNumber, found::Bool, tree_sha::Base.SHA1}[] - - for pkg_name in pkg_names - pkg = registry.pkgs[only(uuids_from_name(registry, pkg_name))] - versions = registry_info(pkg).version_info - for version in sort(collect(keys(versions))) - tree_sha = versions[version].git_tree_sha1 - found = success(`$(git()) -C $dir rev-parse -q --verify "$(tree_sha)^{tree}"`) - - push!(table, (; pkg_name, version, found, tree_sha)) - end - end - verbose && pretty_print_table(table) - throw && check_all_found(table) - return table -end - -check_package_versions(pkg_name, repo_url; kw...) = check_packages_versions([pkg_name], repo_url; kw...) -``` - -For example, in [General#75319](https://github.com/JuliaRegistries/General/pull/75319), a package author wanted to update the URL associated -to their package "FastParzenWindows". At the time, the package had 1 registered version. We can check that it is present in the new repository via: - -```julia -julia> check_package_versions("FastParzenWindows", "https://github.com/ngiann/FastParzenWindows.jl.git"); -Cloning into '/var/folders/jb/plyyfc_d2bz195_0rc0n_zcw0000gp/T/jl_ke9E8C'... -...text omitted... -FastParzenWindows: v0.1.2 found -``` - -We see that this version was found in the new repository. This script was based on [this comment from General#35965](https://github.com/JuliaRegistries/General/pull/35965#issuecomment-832721704), -which involved checking if 4 packages in the same repository all had their versions present in the new repository. That example can be handled as follows: - -```julia -pkg_names = ["ReinforcementLearningBase", "ReinforcementLearningCore", - "ReinforcementLearningEnvironments", "ReinforcementLearningZoo"] -check_packages_versions(pkg_names, "https://github.com/JuliaReinforcementLearning/ReinforcementLearning.jl.git") -``` - -You can also use this script against local repositories when modifying Git commit history: - -```julia -check_package_versions("FastParzenWindows", ".") -``` - -[FAQ]: https://github.com/JuliaRegistries/General#faq] -[naming-guidelines]: https://pkgdocs.julialang.org/dev/creating-packages/#Package-naming-guidelines-1 -[permissions]: https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permission-levels-for-repositories-owned-by-an-organization -[RegistryCI]: https://github.com/JuliaRegistries/RegistryCI.jl/ diff --git a/registries/General/LICENSE.adoc b/registries/General/LICENSE.adoc new file mode 100644 index 000000000..7fec5d5f2 --- /dev/null +++ b/registries/General/LICENSE.adoc @@ -0,0 +1,22 @@ +== MIT License + +Copyright (c) 2017 contributors + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"`Software`"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "`AS IS`", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/registries/General/LICENSE.md b/registries/General/LICENSE.md deleted file mode 100644 index 7d14f05ec..000000000 --- a/registries/General/LICENSE.md +++ /dev/null @@ -1,21 +0,0 @@ -# MIT License - -Copyright (c) 2017 contributors - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/registries/General/README.adoc b/registries/General/README.adoc new file mode 100644 index 000000000..8eceff564 --- /dev/null +++ b/registries/General/README.adoc @@ -0,0 +1,575 @@ +== General + +[width="100%",cols="28%,72%",options="header",] +|=== +|Workflow |Status +|AutoMerge +|https://github.com/JuliaRegistries/General/actions/workflows/automerge.yml[image:https://github.com/JuliaRegistries/General/actions/workflows/automerge.yml/badge.svg[AutoMerge +status,title="AutoMerge status"]] + +|Registry consistency tests +|https://github.com/JuliaRegistries/General/actions/workflows/registry-consistency-ci.yml[image:https://github.com/JuliaRegistries/General/actions/workflows/registry-consistency-ci.yml/badge.svg?branch=master[Registry +consistency tests,title="Registry consistency tests"]] + +|TagBot Triggers +|https://github.com/JuliaRegistries/General/actions/workflows/TagBotTriggers.yml[image:https://github.com/JuliaRegistries/General/actions/workflows/TagBotTriggers.yml/badge.svg[TagBot +Triggers status,title="TagBot Triggers status"]] + +|Update Manifests +|https://github.com/JuliaRegistries/General/actions/workflows/update_manifests.yml[image:https://github.com/JuliaRegistries/General/actions/workflows/update_manifests.yml/badge.svg[Update +Manifests status,title="Update Manifests status"]] +|=== + +General is the default Julia package registry. Package registries are +used by Julia’s package manager +https://julialang.github.io/Pkg.jl/v1/[Pkg.jl] and includes information +about packages such as versions, dependencies and compatibility +constraints. + +The General registry is open for everyone to use and provides access to +a large ecosystem of packages. + +If you are registering a new package, please make sure that you have +read the +https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules[package +naming rules]. + +Follow along new package registrations with the `+#new-packages-feed+` +channels in the https://julialang.org/slack/[community Slack] or +https://julialang.zulipchat.com/register/[Zulip]! + +See our *link:./CONTRIBUTING.md[Contributing Guidelines]* for ways to +get involved! + +=== Registering a package in General + +New packages and new versions of packages are added to the General +registry by pull requests against this GitHub repository. It is *_highly +recommended_* that you use +https://github.com/JuliaRegistries/Registrator.jl[Registrator.jl] to +automate this process. Registrator can either be used as a +https://github.com/JuliaRegistries/Registrator.jl#via-the-github-app[GitHub +App] or through a +https://github.com/JuliaRegistries/Registrator.jl#via-the-web-interface[web +interface], as described in the +https://github.com/JuliaRegistries/Registrator.jl/blob/master/README.md[Registrator +README]. + +When Registrator is triggered a pull request is opened against this +repository. Pull requests that meet certain guidelines are merged +automatically, see link:#automatic-merging-of-pull-requests[Automatic +merging of pull requests]. Other pull requests need to be manually +reviewed and merged by a human. + +It is *_highly recommended_* to also use +https://github.com/JuliaRegistries/TagBot[TagBot], which automatically +tags a release in your repository after the new release of your package +is merged into the registry. + +Registered packages MUST have an https://opensource.org/licenses[Open +Source Initiative approved license], clearly marked via the license file +(see below for definition) in the package repository. Packages that wrap +proprietary libraries (or otherwise restrictive libraries) are +acceptable if the licenses of those libraries permit open source +distribution of the Julia wrapper code. The more restrictive license of +the wrapped code: 1. MUST be mentioned in either the third party notice +file or the license file (preferably the third party notice file). 2. +SHOULD be mentioned in the README file. + +Please note that: - "`README file`" refers to the plain text file named +`+README.md+`, `+README+`, or something similar. - "`License file`" +refers to the plain text file named `+LICENSE.md+`, `+LICENSE+`, +`+COPYING+`, or something similar. - "`Third party notice file`" refers +to the plain text file named `+THIRD_PARTY_NOTICE.md+`, +`+THIRD_PARTY_NOTICE+`, or something similar. + +==== Automatic merging of pull requests + +Pull requests that meet certain criteria are automatically merged +periodically. Only pull requests that are opened by +https://github.com/JuliaRegistries/Registrator.jl[Registrator] are +candidates for automatic merging. + +The full list of AutoMerge guidelines is available in the +https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/[RegistryCI +documentation]. + +Please report issues with automatic merging to the +https://github.com/JuliaRegistries/RegistryCI.jl[RegistryCI repo]. + +Currently the waiting period is as follows: + +* New Julia packages: 3 days (this allows time for community feedback) +* New versions of existing packages: 15 minutes +* JLL package (binary dependencies): 15 minutes, for either a new +package or a new version + +=== FAQ + +==== Do I need to register a package to install it? + +No, you can simply do +`+using Pkg; Pkg.add(url="https://github.com/JuliaLang/Example.jl")+` or +`+] add https://github.com/JuliaLang/Example.jl+` in the Pkg REPL mode +to e.g. install the package `+Example.jl+`, even if it was not +registered. When a package is installed this way, the URL is saved in +the Manifest.toml, so that file is needed to resolve Pkg environments +that have unregistered packages installed. + +Registering allows the package to be added by `+Pkg.add("Example")+` or +`+] add Example+` in the Pkg REPL mode. This is true if the package is +installed in any registry you have installed, not just General; you can +even create your own registry! + +==== Should I register my package now? + +If your package is at a stage where it might be useful to others, or +provide functionality other packages in General might want to rely on, +go for it! + +We ask that you consider the following best practices. + +* It is easier for others to use your package if it has *documentation* +that explains what the package is for and how to use it. This could be +in the form of a README or hosted documentation such as that generated +by https://github.com/JuliaDocs/Documenter.jl[Documenter.jl]. +* And in order to provide reliable functionality for your users, it is +also important to setup *tests* (see +https://pkgdocs.julialang.org/v1/creating-packages/#Adding-tests-to-the-package[the +Pkg.jl docs] and the https://docs.julialang.org/en/v1/stdlib/Test/[Test +stdlib docs]), which can be automatically run by free *continuous +integration* services such as GitHub Actions. As part of the test suite, +tools like https://github.com/JuliaTesting/Aqua.jl[Aqua.jl] and +https://github.com/aviatesk/JET.jl[JET.jl] can help you remove bugs or +typos and improve the general quality of your code. + +Packages like +https://github.com/invenia/PkgTemplates.jl[PkgTemplates.jl] or +https://github.com/tpapp/PkgSkeleton.jl[PkgSkeleton.jl] provide easy +ways to setup documentation, tests, and continuous integration. + +Some types of packages should not be registered, or are not yet ready +for registration: + +* The General registry is not a place for "`personal packages`" that +consist of collections of "`utility functions`" nor for packages that +are only useful for a closed group (like a research group or a company). +For that, it is easy to set up your own registry using for example +https://github.com/GunnarFarneback/LocalRegistry.jl[LocalRegistry.jl]. +The https://pkgdocs.julialang.org/v1/registries/[Pkg documentation about +registries] might be useful if you decide to go this route. +* Packages that are +https://simonwillison.net/2025/Mar/19/vibe-coding/["`vibe-coded`"] +(generated by an LLM *without human review*) are not suitable for +registration. See the +link:#is-there-any-policy-regarding-the-use-of-llms-in-registered-packages[LLM +policy]. +* "`Empty`" packages that do not yet have functionality are not ready to +be registered. + +==== Is there any policy regarding the use of LLM’s in registered packages? + +It is perfectly fine to register packages that have been produced with +the +https://discourse.julialang.org/t/the-use-of-claude-code-in-sciml-repos/131009/8[_assistance_] +of a large language model (LLM) such as Claude Code or any similar tool. +However, it is essential that a human maintainer has a full +understanding of the generated code. + +https://discourse.julialang.org/t/should-general-have-a-guideline-or-rule-preventing-registration-of-vibe-coded-packages/133205[It +is not okay to submit vibe-coded packages], defined as "`building +software with an LLM without reviewing the code it writes`". Packages +that exhibit obvious signs of https://en.wikipedia.org/wiki/AI_slop["`AI +slop`"] may be blocked from registration. To ensure that a package +containing LLM-generated components is suitable for this registry, +follow best practices as much as possible: + +* If your package contains substantial contributions from a generative +AI tool, please disclose so with details in the README. +* Review and understand all generated code, by hand. +* Avoid lengthy, verbose, and over-selling READMEs; review and trim down +any documentation generated by an LLM. Being concise is a +https://julialang.org/community/standards/#be_concise[community value]. +* Ensure that the +https://pkgdocs.julialang.org/v1/creating-packages/#Adding-tests-to-the-package[code +is tested] and that these tests run in continuous integration (CI), such +as GitHub Actions. Collect and track coverage information. +* Build and deploy documentation in CI, using a system like +https://documenter.juliadocs.org/stable/[Documenter.jl] where +appropriate. + +When communicating about a package registration, make sure to express +_your own_ thoughts and ideas. Don’t rely on an LLM to think for you. We +want to hear from you! Occasionally, folks will copy feedback on a +registration directly into an LLM that doesn’t have the context or +understanding to reply accurately; please don’t do this. + +==== Can my package in this registry depend on unregistered packages? + +No. In this registry, your package cannot depend on other packages that +are unregistered. In addition, your package cannot depend on an +unregistered version of an otherwise registered package. Both of these +scenarios would cause this registry to be unreproducible. + +==== Can my package be registered if it requires a version of Julia that is not yet released? + +Yes, if your package is ready for use, it can be registered before Julia +itself has a compatible release. The +https://pkgdocs.julialang.org/v1/compatibility/[`+compat+` mechanism] +should be used to indicate which versions of Julia your package is +compatible with. However, AutoMerge will fail to load your package (as +currently it only operates on the latest release of Julia), so the +initial package registration and every new version will require manual +merging until a compatible version of Julia has been released. + +==== My pull request was not approved for automatic merging, what do I do? + +It is recommended that you fix the release to conform to the guidelines +and then retrigger Registrator on the branch/commit that includes the +fix. + +If you for some reason can’t (or won’t) adhere to the guidelines you +will have to wait for a human to review/merge the pull request. You can +contact a human in the `+#pkg-registration+` channel in the official +Julia Slack to expedite this process. + +==== My package fails to load because it needs proprietary software/additional setup to work, what can I do? + +Before merging a pull request, AutoMerge will check that your package +can be installed and loaded. It is OK for your package to not be fully +functional, but making it at least load successfully would streamline +registration, as it does not require manual intervention from the +registry maintainers. This would also let other packages depend on it, +and use its functionalities only when the proprietary software is +available in the system, as done for example by the +https://github.com/JuliaGPU/CUDA.jl[`+CUDA.jl+`] package. If you are not +able or willing to make your package always loadable without the +proprietary dependency (which is the preferred solution), you can check +if the environment variable `+JULIA_REGISTRYCI_AUTOMERGE+` is equal to +`+true+` and make your package loadable during AutoMerge at least, so +that it can be registered without manual intervention. Examples of +packages with proprietary software that use the environment variable +check include https://github.com/jump-dev/Gurobi.jl[`+Gurobi.jl+`] and +https://github.com/jump-dev/CPLEX.jl[`+CPLEX.jl+`]. + +==== My pull request has a merge conflict, what do I do? + +Retrigger Registrator. + +==== How do I retrigger Registrator in order to update my pull request? + +Do what you did when you triggered Registrator the first time. + +For more details, please see the +https://github.com/JuliaRegistries/Registrator.jl/blob/master/README.md[Registrator.jl +README]. + +==== I commented `+@JuliaRegistrator register+` on a pull request in the General registry, but nothing happened. + +If you want to retrigger Registrator by using the Registrator +comment-bot, you need to post the `+@JuliaRegistrator register+` comment +on a commit in *your repository* (the repository that contains your +package). Do not post any comments of the form `+@JuliaRegistrator ...+` +in the `+JuliaRegistries/General+` repository. + +==== AutoMerge is blocked by one of my comments, how do I unblock it? + +Simply edit `+[noblock]+` into all your comments. AutoMerge periodically +checks each PR, and if there are no blocking comments when it checks +(i.e. all comments have `+[noblock]+` present), it will continue to +merge (assuming of course that all of its other checks have passed). + +==== Are there any requirements for package names in the General registry? + +Package names can only use ASCII letters and numbers. Beyond that, there +are no _hard_ requirements, but it is _highly recommended_ to follow the +https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules[package +naming guidelines]. + +==== What to do when asked to reconsider/update the package name? + +If someone comments on the name of your package when you first release +it it is often because it does not follow the +https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules[naming +guidelines]. If you think that your package should not follow those +conventions for some reason or another, just explain why. Otherwise, it +is often a good idea to just rename the package – it is more disruptive +to do so after it is already registered, and sticking to the conventions +makes it easier for users to navigate Julia’s many varied packages. + +As long as the package is not yet registered, renaming the package from +`+OldName.jl+` to `+NewName.jl+` is reasonably straightforward: + +* https://help.github.com/en/github/administering-a-repository/renaming-a-repository[Rename +the GitHub repository] to `+NewName.jl+` +* Rename the file `+src/OldName.jl+` to `+src/NewName.jl+` +* Rename the top-level module to `+NewName+` +* Rename the package name in `+Project.toml+` from `+OldName+` to +`+NewName+` +* Update tests, documentation, etc, to reference the new name +* Once you are done renaming the package, retrigger registration. This +will make a new pull request to General. It is helpful to comment in the +old pull request that it can be closed, linking to the new one. + +==== How do I rename an existing registered package? + +Technically, you can’t rename a package once registered, as this would +break existing users. But you can re-register the package again under a +new name with a new UUID, which basically has the same effect. + +* Follow the instructions above for renaming a package: rename on +GitHub, rename files etc. +** if you rename the repository so it has a new URL, make a PR to edit +the URL stored in the registry for the old package name to point to the +new URL +(https://github.com/JuliaRegistries/General/pull/40190/files[example]). +This allows the old versions of the package under the previous name to +continue to work. +* Generate a new UUID for the Project.toml +* Increment the version in the Project.toml as a breaking change. +* link:#registering-a-package-in-general[Register] it as if it were a +new package +* Comment on the PR, that this is a rename. +* It will have to go through the normal criteria for registering a new +package. +** In particular, even if you get it merged manually, it will need to +wait 3 days from the PR being opened. +** This gives others and yourself the chance to point out any naming +issues. + +You also should let your users know about the rename, e.g. by placing a +note in the README, or opening PRs/issues on downstream packages to +change over. + +==== How do I transfer a package to an organization or another user? + +* Use the +https://help.github.com/en/github/administering-a-repository/transferring-a-repository[GitHub +transfer option] in the settings. +* Make a pull request to +https://github.com/JuliaRegistries/General/pulls[this repository] in +which you edit the repo URL in the package’s Package.toml file (e.g +https://github.com/JuliaRegistries/General/blob/master/E/Example/Package.toml#L3[E/Example/Package.toml]). +* If the PR is not attended to, or if you have any questions, you can +ask for help in the `+#pkg-registration+` Slack channel. + +Technically if you skip the second step things will keep working, +because GitHub will redirect; but it is best practice. For this reason, +when you try to register a new release, the Julia Registrator will +complain if the second step is skipped. + +==== How do I move a package into a subdirectory of a repository? + +If you have a package that has already been registered, and decide to +change the repository layout so that it instead resides in a +subdirectory, do this: + +* Move the files with normal git commands, without changing the revision +history. +* Make a manual pull request to +https://github.com/JuliaRegistries/General/pulls[this repository] in +which you add a `+subdir+` field in the package’s Package.toml file (e.g +https://github.com/JuliaRegistries/General/blob/af591c91b2377b5e24dce1c5917162493620447c/M/Makie/Package.toml#L4[M/Makie/Package.toml]). + +Notes: - See the +https://github.com/JuliaRegistries/Registrator.jl?tab=readme-ov-file#registering-a-package-in-a-subdirectory[Registrator +instructions] for how to register a package in a subdirectory. - If you +fail to make the manual pull request, the next time you register your +package, the Registrator PR will include the addition of the `+subdir+` +field but it won’t be AutoMerged. Since a PR that both adds a `+subdir+` +and contains all other changes for a new version is hard for humans to +review, you will be asked to do the manual pull request first. - A copy +(not a symbolic link) of the license file needs to be in the package +subdirectory. - A new package that has not previously been registered +can be placed directly in a subdirectory and will be handled by +AutoMerge like any other package. + +==== How do I move a subdirectory package to its own repository? + +Follow these steps to move a +https://pkgdocs.julialang.org/v1/managing-packages/#Adding-a-package-in-a-subdirectory-of-a-repository[subdirectory +package] to its own repository. These steps are focused on GitHub hosted +packages but are still applicable for packages hosted elsewhere: + +[arabic] +. Follow Github’s documentation on +https://docs.github.com/en/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository[splitting +a subfolder out into a new repository] and set the subdirectory package +to be the new root folder of the new repository via +`+git-filter-repo+`’s `+--subdirectory-filter+` flag. In order to avoid +having to modify the package’s `+git-tree-sha1+` entries in the registry +it is important that subdirectory package’s contents remain identical +for the registered releases. Specifically, this means one should not use +`+git-filter-repo+`’s `+--path+` functionality to transfer additional +top-level directories (such as `+.github/workflows+`) when transferring +the history, as this would modify root tree SHA. +. link:./CONTRIBUTING.md#appendix-checking-if-a-repository-contains-all-registered-versions-of-a-package[Check +that the new repository contains all registered versions of the +package]. +. Make a pull request to +https://github.com/JuliaRegistries/General/pulls[this repository] in +which you edit the repo URL in the package’s `+Package.toml+` file (e.g +https://github.com/JuliaRegistries/General/blob/master/E/Example/Package.toml#L3[`+E/Example/Package.toml+`]), +and remove the `+subdir+` line. Be sure to include the printed output +from the second step in your pull request, so the reviewer can see that +the new repository indeed contains all registered versions of the +package. See https://github.com/JuliaRegistries/General/pull/106369[this +pull request] for an example of moving a subdirectory package to its own +repository. + +==== How do I transfer a package to General from another registry? + +You can simply register your next release in General (and don’t change +the package’s name or UUID!). This will be treated as a new package +registration in General and be subject to the usual 3-day waiting +period. Once registered, Pkg.jl will look at all the versions from all +registries it knows about, and use the compat mechanism to figure out +what version to resolve to as usual, regardless if some versions are in +different registries from others. + +==== How do I close a PR that Registrator has opened for my package? + +If the PR is blocked from merging (which you can do by leaving a +comment), then you can just ignore it, as it will eventually be closed +by stale-PR automation. If you need it closed sooner for some reason, +you can make a request on the +https://julialang.slack.com/archives/C6M4DQA5P[#pkg-registration] +channel on the public Julia Language Slack for someone to close it. + +==== Where do I report a problem with a package in the General registry? + +Report it to the package repository. + +==== How do I remove a package or version from the registry? + +You can’t. Package registrations are *permanent*. A version can not be +overwritten in the registry, and code cannot be deleted. + +==== Can my package be registered without an https://opensource.org/licenses[OSI approved license]? + +No, sorry. The registry is maintained by volunteers, and we don’t have a +legal team who can thoroughly review licenses. It is very easy to +accidentally wander into legally murky territory when combining common +OSI licensesfootnote:[Note that even within the world of OSI licenses, +there are combinations of OSI licenses which are not legal to use +together, such as GPL2 with Apache2.] like GPL with non-OSI licenses and +we don’t want to subject Julia users to that risk when installing +packages registered in General. See +https://github.com/JuliaRegistries/General/pull/31549#issuecomment-796671872[these] +https://github.com/JuliaRegistries/General/pull/31549#issuecomment-804196208[comments] +for more discussion. We are not lawyers and this is not legal advice. + +==== Can my package registration PR be merged early? + +New packages must typically wait for the 3 day timer to expire before +they are merged, either automatically by the bot or manually. This +waiting period allows time for community comment and review, and to +provide time to check things like: + +* the name is appropriate (e.g. "`safe for work`", not typosquatting, +and fitting with the +https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-guidelines[Pkg +naming guidelines]) +* the package is functional and non-empty +* the code is not malicious (e.g. exploiting security vulnerabilities) +* there is some form of README or documentation to enable users to use +the package + +If there is some urgent need for the package to be registered (for +example, an upcoming talk featuring the package or other external +deadline), the waiting period can be expedited by request made in the +https://julialang.slack.com/archives/C6M4DQA5P[#pkg-registration] +channel on the public Julia Language Slack, or directly on the PR +itself. This request should include a link to the registration PR and +why an expedited merge is needed. In this case, a registry maintainer +(see below) can manually review the package (often with stricter +standards than the typical package faces, given the lack of bandwidth to +review all packages thoroughly). + +==== Who can approve an early merge? + +Any registry maintainer may merge a package registration PR early. Early +merges should still be discussed on the +https://julialang.slack.com/archives/C6M4DQA5P[#pkg-registration] slack +channel before merging. Registry maintainers are discouraged from +merging packages they directly _or_ indirectly maintain as mentioned in +https://github.com/JuliaRegistries/General/blob/master/CONTRIBUTING.md#other-ways-to-help[CONTRIBUTING.md]. + +==== When is yanking a release appropriate? + +Releases that have already merged can be marked as "`yanked`" by adding +`+yanked = true+` under the release entry in `+Versions.toml+` +(https://github.com/JuliaRegistries/General/pull/94858/files[example]). +This tells Pkg to no longer resolve those versions (e.g. when running +`+Pkg.add()+` or `+Pkg.resolve()+`). However, to maintain perfect +reproducibility of environments specified with a full manifest, yanked +versions that are specifically listed in a manifest will continue to +instantiate when running `+Pkg.instantiate()+` and yanked versions +cannot be re-registered in General with different source code. + +If a release is very broken (e.g. contains security vulnerabilities or +bugs that are significantly worse than the package erroring on load), +then it may be yanked. Releasing an ordinary patch release—potentially +reusing the exact same source code as a previous release without the +major bug—is a faster, easier to deploy, and less disruptive way to +prevent most users from installing a specific version. If you seek to +yank a very broken release, you should typically also release a patch +release. + +There is however, a special category of bugged releases that can not be +resolved by having a patch release. These also may to be resolved by +yanking. That special category is when the compat bounds have been set +too wide. i.e. say `+v2.10.0+` was released using a feature not on julia +`+v1.6+` but the compat entry for julia was not raised in the release. +In this case releasing a `+v2.10.1+` with the corrected julia compat +would not solve the issue as on julia v1.6 Pkg would still resolve the +broken `+v2.10.0+`, and as a minor bump, reverting the code changes +would not be valid in a patch bump. In this case one may either submit a +PR to retroactively adjust the compat bounds of previous versions (best +user-facing results, but slow and error-prone to implement) or yank the +offending release. See the +https://github.com/SciML/ColPrac?tab=readme-ov-file#accidental-support-for-an-unsupported-dependency[SciML +collaborative practices for more guidance]. + +If yanking is urgent, open a PR and raise it on the +`+#pkg-registration+` https://julialang.org/slack/[slack channel] + +For releases with actively exploited security vulnerabilities +(i.e. malicious code) yanking is not sufficient. In this case, the +release should be completely deleted from the registry and a new patch +release should be issued. This is a drastic measure that breaks +reproducibility guarantees and has never been performed as of April, +2024. + +==== My new package registration PR fails one or more AutoMerge checks because of reason [X]. However, the General registry already contains a package PastPackage that does thing [X]. Will registry maintainers consider this PastPackage when they evaluate my new package registration PR? + +As a general rule, no. If your package registration does not meet +AutoMerge guidelines, then the presence of previous exceptions to those +guidelines does not justify an exception for your package, and registry +maintainers will not consider past packages to be any kind of precedent +that applies to current and future registrations. + +=== Registry maintenance + +The General registry is a shared resource that belongs to the entire +Julia community. Therefore, we welcome comments and suggestions from +everyone in the Julia community. However, all decisions regarding the +General registry are ultimately up to the discretion of the registry +maintainers. + +See our *link:./CONTRIBUTING.md[Contributing Guidelines]* for ways to +get involved! + +=== Disclaimer + +The General registry is open for everyone to register packages in. The +General registry is not a curated list of Julia packages. In particular +this means that: + +* packages included in the General registry are *not* +reviewed/scrutinized; +* packages included in the General registry are *not* "`official`" +packages and *not* endorsed/approved by the JuliaLang organization; +* the General registry and its maintainers are *not* responsible for the +package code you install through the General registry – you are +responsible for reviewing your code dependencies. diff --git a/registries/General/README.md b/registries/General/README.md deleted file mode 100644 index a09c31873..000000000 --- a/registries/General/README.md +++ /dev/null @@ -1,419 +0,0 @@ -# General - -| Workflow | Status | -| --------------------------- | ---------------------------------------------------------------------- | -| AutoMerge | [![AutoMerge status][AutoMerge-img]][AutoMerge-url] | -| Registry consistency tests | [![Registry consistency tests][CI-img]][CI-url] | -| TagBot Triggers | [![TagBot Triggers status][TagBotTriggers-img]][TagBotTriggers-url] | -| Update Manifests | [![Update Manifests status][UpdateManifests-img]][UpdateManifests-url] | - -[AutoMerge-url]: https://github.com/JuliaRegistries/General/actions/workflows/automerge.yml -[AutoMerge-img]: https://github.com/JuliaRegistries/General/actions/workflows/automerge.yml/badge.svg "AutoMerge status" -[CI-url]: https://github.com/JuliaRegistries/General/actions/workflows/registry-consistency-ci.yml -[CI-img]: https://github.com/JuliaRegistries/General/actions/workflows/registry-consistency-ci.yml/badge.svg?branch=master "Registry consistency tests" -[TagBotTriggers-url]: https://github.com/JuliaRegistries/General/actions/workflows/TagBotTriggers.yml -[TagBotTriggers-img]: https://github.com/JuliaRegistries/General/actions/workflows/TagBotTriggers.yml/badge.svg "TagBot Triggers status" -[UpdateManifests-url]: https://github.com/JuliaRegistries/General/actions/workflows/update_manifests.yml -[UpdateManifests-img]: https://github.com/JuliaRegistries/General/actions/workflows/update_manifests.yml/badge.svg "Update Manifests status" - -General is the default Julia package registry. Package registries are used by Julia's -package manager [Pkg.jl][pkg] and includes information about packages such as versions, -dependencies and compatibility constraints. - -The General registry is open for everyone to use and provides access to a large ecosystem -of packages. - -If you are registering a new package, please make sure that you have read the [package naming rules](https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules). - -Follow along new package registrations with the `#new-packages-feed` channels in the -[community Slack](https://julialang.org/slack/) or [Zulip](https://julialang.zulipchat.com/register/)! - -See our **[Contributing Guidelines](./CONTRIBUTING.md)** for ways to get involved! - -## Registering a package in General - -New packages and new versions of packages are added to the General registry by pull requests -against this GitHub repository. It is ***highly recommended*** that you use -[Registrator.jl][registrator] to automate this process. Registrator can either be used as a -[GitHub App][registrator-app] or through a [web interface][registrator-web], as described in -the [Registrator README][registrator-readme]. - -When Registrator is triggered a pull request is opened against this repository. Pull -requests that meet certain guidelines are merged automatically, see -[Automatic merging of pull requests](#automatic-merging-of-pull-requests). Other pull -requests need to be manually reviewed and merged by a human. - -It is ***highly recommended*** to also use [TagBot][tagbot], which automatically tags a release in your -repository after the new release of your package is merged into the registry. - -Registered packages MUST have an [Open Source Initiative approved license](https://opensource.org/licenses), -clearly marked via the license file (see below for definition) in the package repository. -Packages that wrap proprietary libraries (or otherwise restrictive libraries) are -acceptable if the licenses of those libraries permit open source distribution of the Julia wrapper code. -The more restrictive license of the wrapped code: -1. MUST be mentioned in either the third party notice file or the license file (preferably the third party notice file). -2. SHOULD be mentioned in the README file. - -Please note that: -- "README file" refers to the plain text file named `README.md`, `README`, or something similar. -- "License file" refers to the plain text file named `LICENSE.md`, `LICENSE`, `COPYING`, or something similar. -- "Third party notice file" refers to the plain text file named `THIRD_PARTY_NOTICE.md`, `THIRD_PARTY_NOTICE`, or something similar. - -### Automatic merging of pull requests - -Pull requests that meet certain criteria are automatically merged periodically. -Only pull requests that are opened by [Registrator][registrator] are candidates -for automatic merging. - -The full list of AutoMerge guidelines is available in the -[RegistryCI documentation][automerge-guidelines]. - -Please report issues with automatic merging to the [RegistryCI repo][registryci]. - -Currently the waiting period is as follows: - - - New Julia packages: 3 days (this allows time for community feedback) - - New versions of existing packages: 15 minutes - - JLL package (binary dependencies): 15 minutes, for either a new package or a new version - -## FAQ - -### Do I need to register a package to install it? - -No, you can simply do `using Pkg; Pkg.add(url="https://github.com/JuliaLang/Example.jl")` -or `] add https://github.com/JuliaLang/Example.jl` in the Pkg REPL mode -to e.g. install the package `Example.jl`, even if it was not registered. When a package -is installed this way, the URL is saved in the Manifest.toml, so that file is needed -to resolve Pkg environments that have unregistered packages installed. - -Registering allows the package to be added by `Pkg.add("Example")` or `] add Example` -in the Pkg REPL mode. This is true if the package is installed in any registry -you have installed, not just General; you can even create your own registry! - -### Should I register my package now? - -If your package is at a stage where it might be useful to others, or provide functionality other -packages in General might want to rely on, go for it! - -We ask that you consider the following best practices. - -* It is easier for others to use your package if it has **documentation** that explains -what the package is for and how to use it. This could be in the form of a README -or hosted documentation such as that generated by -[Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). -* And in order to provide reliable functionality for your users, it is also important -to setup **tests** (see -[the Pkg.jl docs](https://pkgdocs.julialang.org/v1/creating-packages/#Adding-tests-to-the-package) -and the [Test stdlib docs](https://docs.julialang.org/en/v1/stdlib/Test/)), which -can be automatically run by free **continuous integration** services such as GitHub Actions. As part of the test suite, tools like [Aqua.jl](https://github.com/JuliaTesting/Aqua.jl) and [JET.jl](https://github.com/aviatesk/JET.jl) can help you remove bugs or typos and improve the general quality of your code. - -Packages like [PkgTemplates.jl](https://github.com/invenia/PkgTemplates.jl) or -[PkgSkeleton.jl](https://github.com/tpapp/PkgSkeleton.jl) provide easy ways to setup -documentation, tests, and continuous integration. - -Some types of packages should not be registered, or are not yet ready for registration: - -* The General registry is not a place for "personal packages" that consist of -collections of "utility functions" nor for packages that are only useful for a closed group -(like a research group or a company). For that, it is easy to set up your own registry using -for example [LocalRegistry.jl](https://github.com/GunnarFarneback/LocalRegistry.jl). The -[Pkg documentation about registries](https://pkgdocs.julialang.org/v1/registries/) might be useful -if you decide to go this route. -* Packages that are ["vibe-coded"](https://simonwillison.net/2025/Mar/19/vibe-coding/) -(generated by an LLM **without human review**) are not suitable for registration. See the -[LLM policy](#is-there-any-policy-regarding-the-use-of-llms-in-registered-packages). -* "Empty" packages that do not yet have functionality are not ready to be registered. - -### Is there any policy regarding the use of LLM's in registered packages? - -It is perfectly fine to register packages that have been produced with the -[_assistance_](https://discourse.julialang.org/t/the-use-of-claude-code-in-sciml-repos/131009/8) -of a large language model (LLM) such as Claude Code or any similar -tool. However, it is essential that a human maintainer has a full -understanding of the generated code. - -[It is not okay to submit vibe-coded packages](https://discourse.julialang.org/t/should-general-have-a-guideline-or-rule-preventing-registration-of-vibe-coded-packages/133205), -defined as "building software with an LLM without reviewing the code it -writes". Packages that exhibit obvious signs of ["AI slop"](https://en.wikipedia.org/wiki/AI_slop) -may be blocked from registration. To ensure that a package containing -LLM-generated components is suitable for this registry, follow best -practices as much as possible: - -* If your package contains substantial contributions from a generative AI tool, please disclose so with details in the README. -* Review and understand all generated code, by hand. -* Avoid lengthy, verbose, and over-selling READMEs; review and trim -down any documentation generated by an LLM. Being concise is a [community value](https://julialang.org/community/standards/#be_concise). -* Ensure that the [code is tested](https://pkgdocs.julialang.org/v1/creating-packages/#Adding-tests-to-the-package) -and that these tests run in continuous integration (CI), such as GitHub Actions. -Collect and track coverage information. -* Build and deploy documentation in CI, using a system like -[Documenter.jl](https://documenter.juliadocs.org/stable/) where appropriate. - -When communicating about a package registration, make sure to express _your -own_ thoughts and ideas. Don't rely on an LLM to think for you. We want to hear -from you! Occasionally, folks will copy feedback on a registration directly -into an LLM that doesn't have the context or understanding to reply accurately; -please don't do this. - -### Can my package in this registry depend on unregistered packages? - -No. In this registry, your package cannot depend on other packages that are -unregistered. In addition, your package cannot depend on an unregistered -version of an otherwise registered package. Both of these scenarios would cause -this registry to be unreproducible. - -### Can my package be registered if it requires a version of Julia that is not yet released? - -Yes, if your package is ready for use, it can be registered before Julia itself has a compatible release. -The [`compat` mechanism](https://pkgdocs.julialang.org/v1/compatibility/) -should be used to indicate which versions of Julia your package is compatible with. -However, AutoMerge will fail to load your package (as currently it only operates on the latest release of Julia), -so the initial package registration and every new version will require manual merging until a compatible version -of Julia has been released. - -### My pull request was not approved for automatic merging, what do I do? - -It is recommended that you fix the release to conform to the guidelines and -then retrigger Registrator on the branch/commit that includes the fix. - -If you for some reason can't (or won't) adhere to the guidelines you will have -to wait for a human to review/merge the pull request. You can contact a human -in the `#pkg-registration` channel in the official Julia Slack to expedite this process. - -### My package fails to load because it needs proprietary software/additional setup to work, what can I do? - -Before merging a pull request, AutoMerge will check that your package can be installed and -loaded. It is OK for your package to not be fully functional, but making it at least load -successfully would streamline registration, as it does not require manual intervention from -the registry maintainers. This would also let other packages depend on it, and use its -functionalities only when the proprietary software is available in the system, as done for -example by the [`CUDA.jl`](https://github.com/JuliaGPU/CUDA.jl) package. If you are not -able or willing to make your package always loadable without the proprietary dependency -(which is the preferred solution), you can check if the environment variable -`JULIA_REGISTRYCI_AUTOMERGE` is equal to `true` and make your package loadable during -AutoMerge at least, so that it can be registered without manual intervention. Examples of -packages with proprietary software that use the environment variable check include -[`Gurobi.jl`](https://github.com/jump-dev/Gurobi.jl) and -[`CPLEX.jl`](https://github.com/jump-dev/CPLEX.jl). - -### My pull request has a merge conflict, what do I do? - -Retrigger Registrator. - -### How do I retrigger Registrator in order to update my pull request? - -Do what you did when you triggered Registrator the first time. - -For more details, please see the [Registrator.jl README](https://github.com/JuliaRegistries/Registrator.jl/blob/master/README.md). - -### I commented `@JuliaRegistrator register` on a pull request in the General registry, but nothing happened. - -If you want to retrigger Registrator by using the Registrator comment-bot, -you need to post the `@JuliaRegistrator register` comment on a commit in -**your repository** (the repository that contains your package). Do not post -any comments of the form `@JuliaRegistrator ...` in the `JuliaRegistries/General` -repository. - -### AutoMerge is blocked by one of my comments, how do I unblock it? - -Simply edit `[noblock]` into all your comments. AutoMerge periodically -checks each PR, and if there are no blocking comments when it checks -(i.e. all comments have `[noblock]` present), it will continue to merge -(assuming of course that all of its other checks have passed). - -### Are there any requirements for package names in the General registry? - -Package names can only use ASCII letters and numbers. Beyond that, there are -no *hard* requirements, but it is *highly recommended* to follow -the [package naming guidelines][naming-guidelines]. - -### What to do when asked to reconsider/update the package name? - -If someone comments on the name of your package when you first release it it is often -because it does not follow the [naming guidelines][naming-guidelines]. If you think that -your package should not follow those conventions for some reason or another, just explain -why. Otherwise, it is often a good idea to just rename the package -- it is more disruptive -to do so after it is already registered, and sticking to the conventions makes it easier -for users to navigate Julia's many varied packages. - -As long as the package is not yet registered, renaming the package from -`OldName.jl` to `NewName.jl` is reasonably straightforward: - -* [Rename the GitHub repository][github-rename] to `NewName.jl` -* Rename the file `src/OldName.jl` to `src/NewName.jl` -* Rename the top-level module to `NewName` -* Rename the package name in `Project.toml` from `OldName` to `NewName` -* Update tests, documentation, etc, to reference the new name -* Once you are done renaming the package, retrigger registration. - This will make a new pull request to General. It is helpful to comment - in the old pull request that it can be closed, linking to the new one. - -### How do I rename an existing registered package? - -Technically, you can't rename a package once registered, as this would break existing users. -But you can re-register the package again under a new name with a new UUID, which basically -has the same effect. - - - Follow the instructions above for renaming a package: rename on GitHub, rename files etc. - - if you rename the repository so it has a new URL, make a PR to edit the URL stored in the - registry for the old package name to point to the new URL ([example](https://github.com/JuliaRegistries/General/pull/40190/files)). - This allows the old versions of the package under the previous name to continue to work. - - Generate a new UUID for the Project.toml - - Increment the version in the Project.toml as a breaking change. - - [Register](#registering-a-package-in-general) it as if it were a new package - - Comment on the PR, that this is a rename. - - It will have to go through the normal criteria for registering a new package. - - In particular, even if you get it merged manually, it will need to wait 3 days from the PR being opened. - - This gives others and yourself the chance to point out any naming issues. - -You also should let your users know about the rename, e.g. by placing a note in the README, -or opening PRs/issues on downstream packages to change over. - -### How do I transfer a package to an organization or another user? - - - Use the [GitHub transfer option][github-transfer] in the settings. - - Make a pull request to [this repository](https://github.com/JuliaRegistries/General/pulls) in which you edit the repo URL in the package's Package.toml file (e.g [E/Example/Package.toml](https://github.com/JuliaRegistries/General/blob/master/E/Example/Package.toml#L3)). - - If the PR is not attended to, or if you have any questions, you can ask for help in the `#pkg-registration` Slack channel. - -Technically if you skip the second step things will keep working, because GitHub will redirect; -but it is best practice. For this reason, when you try to register a new release, the Julia -Registrator will complain if the second step is skipped. - -### How do I move a package into a subdirectory of a repository? - -If you have a package that has already been registered, and decide to change the repository layout so that it instead resides in a subdirectory, do this: - -- Move the files with normal git commands, without changing the revision history. -- Make a manual pull request to [this repository](https://github.com/JuliaRegistries/General/pulls) in which you add a `subdir` field in the package's Package.toml file (e.g [M/Makie/Package.toml](https://github.com/JuliaRegistries/General/blob/af591c91b2377b5e24dce1c5917162493620447c/M/Makie/Package.toml#L4)). - -Notes: -- See the [Registrator instructions](https://github.com/JuliaRegistries/Registrator.jl?tab=readme-ov-file#registering-a-package-in-a-subdirectory) for how to register a package in a subdirectory. -- If you fail to make the manual pull request, the next time you register your package, the Registrator PR will include the addition of the `subdir` field but it won't be AutoMerged. Since a PR that both adds a `subdir` and contains all other changes for a new version is hard for humans to review, you will be asked to do the manual pull request first. -- A copy (not a symbolic link) of the license file needs to be in the package subdirectory. -- A new package that has not previously been registered can be placed directly in a subdirectory and will be handled by AutoMerge like any other package. - -### How do I move a subdirectory package to its own repository? - -Follow these steps to move a [subdirectory package](https://pkgdocs.julialang.org/v1/managing-packages/#Adding-a-package-in-a-subdirectory-of-a-repository) to its own repository. These steps are focused on GitHub hosted packages but are still applicable for packages hosted elsewhere: - -1. Follow Github's documentation on [splitting a subfolder out into a new repository][github-subfolder] and set the subdirectory package to be the new root folder of the new repository via `git-filter-repo`'s `--subdirectory-filter` flag. In order to avoid having to modify the package's `git-tree-sha1` entries in the registry it is important that subdirectory package's contents remain identical for the registered releases. Specifically, this means one should not use `git-filter-repo`'s `--path` functionality to transfer additional top-level directories (such as `.github/workflows`) when transferring the history, as this would modify root tree SHA. -2. [Check that the new repository contains all registered versions of the package](./CONTRIBUTING.md#appendix-checking-if-a-repository-contains-all-registered-versions-of-a-package). -3. Make a pull request to [this repository](https://github.com/JuliaRegistries/General/pulls) in which you edit the repo URL in the package's `Package.toml` file (e.g [`E/Example/Package.toml`](https://github.com/JuliaRegistries/General/blob/master/E/Example/Package.toml#L3)), and remove the `subdir` line. Be sure to include the printed output from the second step in your pull request, so the reviewer can see that the new repository indeed contains all registered versions of the package. See [this pull request](https://github.com/JuliaRegistries/General/pull/106369) for an example of moving a subdirectory package to its own repository. - -### How do I transfer a package to General from another registry? - -You can simply register your next release in General (and don't change the package's name or UUID!). -This will be treated as a new package registration in General and be subject to the usual 3-day waiting period. -Once registered, Pkg.jl will look at all the versions from all registries it knows about, and use the compat -mechanism to figure out what version to resolve to as usual, regardless if some versions are in different registries -from others. - -### How do I close a PR that Registrator has opened for my package? - -If the PR is blocked from merging (which you can do by leaving a comment), then you can just ignore it, as it will eventually be closed by stale-PR automation. -If you need it closed sooner for some reason, you can make a request on the [#pkg-registration](https://julialang.slack.com/archives/C6M4DQA5P) channel on the -public Julia Language Slack for someone to close it. - -### Where do I report a problem with a package in the General registry? - -Report it to the package repository. - -### How do I remove a package or version from the registry? - -You can't. Package registrations are **permanent**. A version can not be overwritten in the -registry, and code cannot be deleted. - -### Can my package be registered without an [OSI approved license](https://opensource.org/licenses)? - -No, sorry. The registry is maintained by volunteers, and we don't have a legal team who can thoroughly review licenses. -It is very easy to accidentally wander into legally murky territory when combining common OSI licenses[^1] like GPL -with non-OSI licenses and we don't want to subject Julia users to that risk when installing packages registered in General. -See [these](https://github.com/JuliaRegistries/General/pull/31549#issuecomment-796671872) [comments](https://github.com/JuliaRegistries/General/pull/31549#issuecomment-804196208) for more discussion. We are not lawyers and this is not legal advice. - -[^1]: Note that even within the world of OSI licenses, there are combinations of OSI licenses which are not -legal to use together, such as GPL2 with Apache2. - -### Can my package registration PR be merged early? - -New packages must typically wait for the 3 day timer to expire before they are merged, either automatically by the bot or manually. -This waiting period allows time for community comment and review, and to provide time to check things like: - -- the name is appropriate (e.g. "safe for work", not typosquatting, and fitting with the [Pkg naming guidelines](https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-guidelines)) -- the package is functional and non-empty -- the code is not malicious (e.g. exploiting security vulnerabilities) -- there is some form of README or documentation to enable users to use the package - -If there is some urgent need for the package to be registered (for example, an upcoming talk featuring the package or other external deadline), the waiting period can be expedited by request made in the [#pkg-registration](https://julialang.slack.com/archives/C6M4DQA5P) channel on the -public Julia Language Slack, or directly on the PR itself. This request should include a link to the registration PR and why an expedited merge is needed. In this case, a registry maintainer (see below) can manually review the package (often with stricter standards than the typical package faces, given the lack of bandwidth to review all packages thoroughly). - -### Who can approve an early merge? - -Any registry maintainer may merge a package registration PR early. -Early merges should still be discussed on the [#pkg-registration](https://julialang.slack.com/archives/C6M4DQA5P) slack channel before merging. -Registry maintainers are discouraged from merging packages they directly *or* indirectly maintain as mentioned in [CONTRIBUTING.md](https://github.com/JuliaRegistries/General/blob/master/CONTRIBUTING.md#other-ways-to-help). - -### When is yanking a release appropriate? - -Releases that have already merged can be marked as "yanked" by adding `yanked = true` under the release -entry in `Versions.toml` ([example](https://github.com/JuliaRegistries/General/pull/94858/files)). This -tells Pkg to no longer resolve those versions (e.g. when running `Pkg.add()` or `Pkg.resolve()`). However, -to maintain perfect reproducibility of environments specified with a full manifest, yanked versions that -are specifically listed in a manifest will continue to instantiate when running `Pkg.instantiate()` and -yanked versions cannot be re-registered in General with different source code. - -If a release is very broken (e.g. contains security vulnerabilities or bugs that are significantly worse -than the package erroring on load), then it may be yanked. Releasing an ordinary patch release—potentially -reusing the exact same source code as a previous release without the major bug—is a faster, easier to -deploy, and less disruptive way to prevent most users from installing a specific version. If you seek to -yank a very broken release, you should typically also release a patch release. - -There is however, a special category of bugged releases that can not be resolved by having a patch release. -These also may to be resolved by yanking. That special category is when the compat bounds have been set too -wide. i.e. say `v2.10.0` was released using a feature not on julia `v1.6` but the compat entry for julia was -not raised in the release. In this case releasing a `v2.10.1` with the corrected julia compat would not -solve the issue as on julia v1.6 Pkg would still resolve the broken `v2.10.0`, and as a minor bump, reverting -the code changes would not be valid in a patch bump. In this case one may either submit a PR to retroactively -adjust the compat bounds of previous versions (best user-facing results, but slow and error-prone to implement) -or yank the offending release. See the [SciML collaborative practices for more guidance](https://github.com/SciML/ColPrac?tab=readme-ov-file#accidental-support-for-an-unsupported-dependency). - -If yanking is urgent, open a PR and raise it on the `#pkg-registration` [slack channel](https://julialang.org/slack/) - -For releases with actively exploited security vulnerabilities (i.e. malicious code) yanking is not sufficient. -In this case, the release should be completely deleted from the registry and a new patch release should be -issued. This is a drastic measure that breaks reproducibility guarantees and has never been performed as of -April, 2024. - -### My new package registration PR fails one or more AutoMerge checks because of reason [X]. However, the General registry already contains a package PastPackage that does thing [X]. Will registry maintainers consider this PastPackage when they evaluate my new package registration PR? - -As a general rule, no. If your package registration does not meet AutoMerge guidelines, then the presence of previous exceptions to those guidelines does not justify an exception for your package, and registry maintainers will not consider past packages to be any kind of precedent that applies to current and future registrations. - -## Registry maintenance - -The General registry is a shared resource that belongs to the entire Julia community. Therefore, we welcome comments and suggestions from everyone in the Julia community. However, all decisions regarding the General registry are ultimately up to the discretion of the registry maintainers. - -See our **[Contributing Guidelines](./CONTRIBUTING.md)** for ways to get involved! - -## Disclaimer - -The General registry is open for everyone to register packages in. The General registry is -not a curated list of Julia packages. In particular this means that: - - - packages included in the General registry are **not** reviewed/scrutinized; - - packages included in the General registry are **not** "official" packages and **not** - endorsed/approved by the JuliaLang organization; - - the General registry and its maintainers are **not** responsible for the package code - you install through the General registry -- you are responsible for reviewing your - code dependencies. - -[pkg]: https://julialang.github.io/Pkg.jl/v1/ -[registrator]: https://github.com/JuliaRegistries/Registrator.jl -[registrator-app]: https://github.com/JuliaRegistries/Registrator.jl#via-the-github-app -[registrator-web]: https://github.com/JuliaRegistries/Registrator.jl#via-the-web-interface -[registrator-readme]: https://github.com/JuliaRegistries/Registrator.jl/blob/master/README.md -[tagbot]: https://github.com/JuliaRegistries/TagBot -[naming-guidelines]: https://pkgdocs.julialang.org/v1/creating-packages/#Package-naming-rules -[automerge-guidelines]: https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/ -[registryci]: https://github.com/JuliaRegistries/RegistryCI.jl -[github-rename]: https://help.github.com/en/github/administering-a-repository/renaming-a-repository -[github-subfolder]: https://docs.github.com/en/get-started/using-git/splitting-a-subfolder-out-into-a-new-repository -[github-transfer]: https://help.github.com/en/github/administering-a-repository/transferring-a-repository