diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..134a2fd --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== 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* |j.d.a.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* j.d.a.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 j.d.a.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/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index a4a1d90..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,311 +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** | j.d.a.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** j.d.a.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 j.d.a.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/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..8ab219a --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/Exnovation.jl.git cd +Exnovation.jl + +== Using Guix (recommended for reproducibility) + +guix 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.guix # Guix +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/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index d6611a2..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,120 +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/EXPLAINME.adoc b/EXPLAINME.adoc index ab1bded..e0ae719 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -126,7 +126,7 @@ Tests live in `test/runtests.jl`. Coverage includes: | `standards` | The exnovation concept is directly applied to the account's own technology - lifecycle policy — TypeScript is under active exnovation in favour of ReScript, + lifecycle policy — TypeScript is under active exnovation in favour of AffineScript, Node.js in favour of Deno. This package is the analytical tool for that process. | `nextgen-languages` diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc index e41020d..9b836fb 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 e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..69e0024 --- /dev/null +++ b/README.adoc @@ -0,0 +1,171 @@ +https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/Exnovation.jl[image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF +Best Practices]] +https://github.com/hyperpolymath/palimpsest-license[image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: +PMPL-1.0]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Project-Topology-9558B2[Topology]] +link:TOPOLOGY.md[image:https://img.shields.io/badge/Completion-100%25-green[100]] + +A Julia framework for modeling *exnovation decisions*—phasing out legacy +practices to enable innovation. + +[[toc]] + +== 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 + +=== Example: Modeling a Legacy Phase-Out + +[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) + + transition = legacy_process --> new_process + @ensure transition.cost < 1500 + @ensure transition.risk < 0.5 +end + +strategy = LegacySystem() +result = simulate(strategy, horizon=5) +---- + +== Features + +=== Scenario Simulation + +Simulate the impact of phasing out legacy systems over time, with +support for: - Cost-benefit analysis - Risk assessment - Resource +allocation + +[source,julia] +---- +@exnovate EnergyTransition begin + coal :: EnergySource(legacy=true, emissions=1000) + solar :: EnergySource(legacy=false, emissions=0) + + transition = coal --> solar + @ensure transition.emissions_reduction > 90% +end +---- + +=== Dependency Mapping + +Visualize and analyze dependencies between legacy and new systems to +identify critical path dependencies and bottlenecks. + +[source,julia] +---- +dependencies = map_dependencies(legacy_system, new_system) +plot(dependencies) +---- + +=== Formal Validation + +Ensure that exnovation strategies meet organizational constraints and +regulatory requirements. + +[source,julia] +---- +@exnovate ComplianceCheck begin + old_policy :: Policy(legacy=true, compliance_risk=0.9) + new_policy :: Policy(legacy=false, compliance_risk=0.1) + + transition = old_policy --> new_policy + @prove transition.compliance_risk < 0.2 +end +---- + +=== Integration with Julia Ecosystem + +Leverage Julia’s data science and optimization tools for advanced +analysis. + +[source,julia] +---- +using DataFrames, Plots + +results = simulate(exnovation_strategy, iterations=1000) +df = DataFrame(results) +plot(df, x=:time, y=:cost, group=:scenario) +---- + +== Quick Start + +=== Installation + +[source,julia] +---- +using Pkg +Pkg.add("Exnovation") +---- + +=== Hello World + +[source,julia] +---- +using Exnovation + +@exnovate SimpleTransition begin + old :: System(legacy=true, cost=100) + new :: System(legacy=false, cost=50) + + transition = old --> new + @ensure transition.cost < 120 +end + +strategy = SimpleTransition() +result = simulate(strategy) +---- + +== Why Exnovation.jl? + +=== The Problem + +Organizations often struggle to retire legacy systems due to: - Complex +dependencies - Uncertain costs and risks - Resistance to change + +=== 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 + +== Project Structure + +.... +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 +.... + +== Roadmap + +* [x] *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/README.md b/README.md deleted file mode 100644 index 067b399..0000000 --- a/README.md +++ /dev/null @@ -1,175 +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/Exnovation.jl) -[![License: PMPL-1.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) -[![Topology](https://img.shields.io/badge/Project-Topology-9558B2)](TOPOLOGY.md) -[![100](https://img.shields.io/badge/Completion-100%25-green)](TOPOLOGY.md) - -A Julia framework for modeling **exnovation decisions**—phasing out -legacy practices to enable innovation. - -
- -
- -# 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 - -## Example: Modeling a Legacy Phase-Out - -```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) - - transition = legacy_process --> new_process - @ensure transition.cost < 1500 - @ensure transition.risk < 0.5 -end - -strategy = LegacySystem() -result = simulate(strategy, horizon=5) -``` - -# Features - -## Scenario Simulation - -Simulate the impact of phasing out legacy systems over time, with -support for: - Cost-benefit analysis - Risk assessment - Resource -allocation - -```julia -@exnovate EnergyTransition begin - coal :: EnergySource(legacy=true, emissions=1000) - solar :: EnergySource(legacy=false, emissions=0) - - transition = coal --> solar - @ensure transition.emissions_reduction > 90% -end -``` - -## Dependency Mapping - -Visualize and analyze dependencies between legacy and new systems to -identify critical path dependencies and bottlenecks. - -```julia -dependencies = map_dependencies(legacy_system, new_system) -plot(dependencies) -``` - -## Formal Validation - -Ensure that exnovation strategies meet organizational constraints and -regulatory requirements. - -```julia -@exnovate ComplianceCheck begin - old_policy :: Policy(legacy=true, compliance_risk=0.9) - new_policy :: Policy(legacy=false, compliance_risk=0.1) - - transition = old_policy --> new_policy - @prove transition.compliance_risk < 0.2 -end -``` - -## Integration with Julia Ecosystem - -Leverage Julia’s data science and optimization tools for advanced -analysis. - -```julia -using DataFrames, Plots - -results = simulate(exnovation_strategy, iterations=1000) -df = DataFrame(results) -plot(df, x=:time, y=:cost, group=:scenario) -``` - -# Quick Start - -## Installation - -```julia -using Pkg -Pkg.add("Exnovation") -``` - -## Hello World - -```julia -using Exnovation - -@exnovate SimpleTransition begin - old :: System(legacy=true, cost=100) - new :: System(legacy=false, cost=50) - - transition = old --> new - @ensure transition.cost < 120 -end - -strategy = SimpleTransition() -result = simulate(strategy) -``` - -# Why Exnovation.jl? - -## The Problem - -Organizations often struggle to retire legacy systems due to: - Complex -dependencies - Uncertain costs and risks - Resistance to change - -## 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 - -# Project Structure - - 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 - -# Roadmap - -- [x] **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/REQUIRES_INITIALISATION.adoc b/REQUIRES_INITIALISATION.adoc new file mode 100644 index 0000000..88f764c --- /dev/null +++ b/REQUIRES_INITIALISATION.adoc @@ -0,0 +1,56 @@ +== REQUIRES INITIALISATION + +*This repository is not finished being set up.* 1 substitution token(s) +across 1 file(s) still have no value. + +=== Why this is not already done + +This repo was created from `+hyperpolymath/rsr-template-repo+`. The mint +(`+just repo-init+`) fills every token that has a single mechanical +answer — owner, repo, author, dates, licence, branch — and it has done +so here. + +The tokens below are the ones it _deliberately cannot_ answer. They need +a decision or a fact that exists only in your head: what this project is +for, what command builds it, which port the service listens on, whether +a PGP key is held at all. The template’s own token vocabulary says as +much — you cannot sensibly answer "`required invariants`" in a +thirty-second bootstrap. + +They were left *visibly unfilled on purpose*. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +=== Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it +early does not finish the setup, it just conceals it — and the next +person or agent to arrive will reasonably assume the repo is complete. + +* *If you are a person:* delete this file yourself once the last item is +done. +* *If you are an agent:* resolve what you legitimately can, leave the +rest, and delete this file only when no token below remains anywhere in +the tree. Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically +once nothing is outstanding, so the safest way to finish is to fix the +tokens and let the check confirm it. + +=== What is needed, and where it goes + +==== `+{{PROJECT_UNIQUE_STRENGTH}}+` + +What this does that its alternatives do not. + +Appears in: + +* `+.machine_readable/bot_directives/methodology.a2ml+` + +''''' + +Generated by the estate top-up pass. Rationale and the governing rulings +are in `+hyperpolymath/standards+`; the token vocabulary is +`+.machine_readable/ai/PLACEHOLDERS.adoc+` in `+rsr-template-repo+`. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md deleted file mode 100644 index 9f1a17e..0000000 --- a/REQUIRES_INITIALISATION.md +++ /dev/null @@ -1,54 +0,0 @@ - - -# REQUIRES INITIALISATION - -**This repository is not finished being set up.** 1 substitution token(s) across 1 file(s) still have no value. - -## Why this is not already done - -This repo was created from `hyperpolymath/rsr-template-repo`. The mint -(`just repo-init`) fills every token that has a single mechanical answer — -owner, repo, author, dates, licence, branch — and it has done so here. - -The tokens below are the ones it *deliberately cannot* answer. They need a -decision or a fact that exists only in your head: what this project is for, -what command builds it, which port the service listens on, whether a PGP key -is held at all. The template's own token vocabulary says as much — you cannot -sensibly answer "required invariants" in a thirty-second bootstrap. - -They were left **visibly unfilled on purpose**. The alternatives were both -worse: inventing plausible values would put confident falsehoods into a -security policy and an architecture document, and silently deleting the -sections would hide the fact that a decision is owed. A visible gap is -honest; a fabricated answer is not. - -## Do not delete this file until every item below is resolved - -This file is the only marker that the work is outstanding. Deleting it early -does not finish the setup, it just conceals it — and the next person or agent -to arrive will reasonably assume the repo is complete. - -- **If you are a person:** delete this file yourself once the last item is done. -- **If you are an agent:** resolve what you legitimately can, leave the rest, - and delete this file only when no token below remains anywhere in the tree. - Do not delete it to make a gate go green. - -Re-running the estate top-up tool will remove this file automatically once -nothing is outstanding, so the safest way to finish is to fix the tokens and -let the check confirm it. - -## What is needed, and where it goes - -### `{{PROJECT_UNIQUE_STRENGTH}}` - -What this does that its alternatives do not. - -Appears in: - -- `.machine_readable/bot_directives/methodology.a2ml` - ---- - -Generated by the estate top-up pass. Rationale and the governing rulings are -in `hyperpolymath/standards`; the token vocabulary is -`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/ROADMAP.adoc b/ROADMAP.adoc index e51899f..5715f53 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -1,19 +1,165 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= 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/ROADMAP.md b/ROADMAP.md deleted file mode 100644 index 09bd7d5..0000000 --- a/ROADMAP.md +++ /dev/null @@ -1,137 +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/RSR_OUTLINE.adoc b/RSR_OUTLINE.adoc index b7b64a8..f2aa8e4 100644 --- a/RSR_OUTLINE.adoc +++ b/RSR_OUTLINE.adoc @@ -148,8 +148,8 @@ project/ === Language Tiers -* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, ReScript -* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix +* **Tier 1** (Gold): Rust, Elixir, Zig, Ada, Haskell, AffineScript +* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Guix * **Infrastructure**: Guix channels, derivations === Required Files @@ -163,12 +163,12 @@ project/ * `.well-known/security.txt` * `.well-known/ai.txt` * `.well-known/humans.txt` -* `guix.scm` OR `flake.nix` +* `guix.scm` OR `flake.guix` === Prohibited * Python outside `salt/` directory -* TypeScript/JavaScript (use ReScript) +* TypeScript/JavaScript (use AffineScript) * CUE (use Guile/Nickel) * `Dockerfile` (use `Containerfile`) diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..7b0e643 --- /dev/null +++ b/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* |j.d.a.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 j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.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 j.d.a.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/SECURITY.md b/SECURITY.md deleted file mode 100644 index 8badde7..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,392 +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** | j.d.a.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 j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.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 j.d.a.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/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..b5198be --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,32 @@ +== TEST-NEEDS: Exnovation.jl + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State + +[cols=",,",options="header",] +|=== +|Category |Count |Details +|*Source modules* |2 |51 lines +|*Test files* |1 |178 lines, 32 @test/@testset +|*Benchmarks* |0 |None +|=== + +=== What’s Missing + +* [ ] *Performance*: No benchmarks + +=== FLAGGED ISSUES + +* *32 tests for 51 source lines* – test lines 3.5x source lines. Very +well tested for size. + +=== Priority: P3 (LOW) + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 104f4e2..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,30 +0,0 @@ - -# TEST-NEEDS: Exnovation.jl - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State - -| Category | Count | Details | -|----------|-------|---------| -| **Source modules** | 2 | 51 lines | -| **Test files** | 1 | 178 lines, 32 @test/@testset | -| **Benchmarks** | 0 | None | - -## What's Missing - -- [ ] **Performance**: No benchmarks - -## FLAGGED ISSUES -- **32 tests for 51 source lines** -- test lines 3.5x source lines. Very well tested for size. - -## Priority: P3 (LOW) - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 88% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 300ede6..992d73c 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,15 +1,8 @@ - - - +== Exnovation.jl — Project Topology -# Exnovation.jl — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ EXTERNALS / ECOSYSTEM │ ├─────────────────────────────────────────┤ @@ -46,11 +39,11 @@ Copyright (c) Jonathan D.A. Jewell │ .github/workflows/ (RSR Gate) │ │ Project.toml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE MODELS @@ -71,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/docs/src/api.md b/docs/src/api.adoc similarity index 53% rename from docs/src/api.md rename to docs/src/api.adoc index 5f5196b..b98f028 100644 --- a/docs/src/api.md +++ b/docs/src/api.adoc @@ -1,14 +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 @@ -22,11 +19,12 @@ FailureSummary ImpactModel PortfolioItem StageGate -``` +---- -## Functions +=== Functions -```@docs +[source,@docs] +---- assess_exnovation normalize_score recommendation @@ -38,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/docs/src/index.md b/docs/src/index.adoc similarity index 60% rename from docs/src/index.md rename to docs/src/index.adoc index a2934af..c42e71a 100644 --- a/docs/src/index.md +++ b/docs/src/index.adoc @@ -1,23 +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") @@ -50,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/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..42c2927 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — Exnovation.jl (Developer) + +=== What is Exnovation.jl? + +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 cb2b2eb..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — Exnovation.jl (Developer) - -## What is Exnovation.jl? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..9702907 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — Exnovation.jl (User) + +=== What is Exnovation.jl? + +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 d649f1d..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,20 +0,0 @@ - -# LLM Warmup — Exnovation.jl (User) - -## What is Exnovation.jl? -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