From a9690093bf2f3adc16283ef922439485485a53f5 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:30:19 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- .claude/PROJECT.adoc | 34 +++++ .claude/PROJECT.md | 33 ----- ARCHITECTURE.adoc | 48 +++++++ ARCHITECTURE.md | 47 ------- CODE_OF_CONDUCT.adoc | 295 +++++++++++++++++++++++++++++++++++++++++++ CODE_OF_CONDUCT.md | 228 --------------------------------- GOVERNANCE.adoc | 60 +++++++++ GOVERNANCE.md | 60 --------- SECURITY.adoc | 242 +++++++++++++++++++++++++++++++++++ SECURITY.md | 262 -------------------------------------- llm-warmup-dev.adoc | 19 +++ llm-warmup-dev.md | 16 --- llm-warmup-user.adoc | 19 +++ llm-warmup-user.md | 16 --- 14 files changed, 717 insertions(+), 662 deletions(-) create mode 100644 .claude/PROJECT.adoc delete mode 100644 .claude/PROJECT.md create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md diff --git a/.claude/PROJECT.adoc b/.claude/PROJECT.adoc new file mode 100644 index 0000000..5b17653 --- /dev/null +++ b/.claude/PROJECT.adoc @@ -0,0 +1,34 @@ +== NextGen Language Evangeliser - Claude Code Instructions + +This repository contains the Next Generation Language Evangeliser +project. + +=== Project Structure + +.... +nextgen-language-evangeliser/ +├── .claude/ # AI assistant instructions +├── .git/ # Version control +├── .gitignore # Git ignore rules +├── .editorconfig # Editor configuration +└── ... # Evangelism files +.... + +=== Build Commands + +Refer to project-specific documentation. + +=== Coding Conventions + +* Follow hyperpolymath standards +* All code must have SPDX license headers +* Use approved languages only (see CLAUDE.md) +* Document all non-obvious decisions + +=== Security + +* No hardcoded secrets +* All secrets through environment variables or secret management +* SHA-pinned dependencies where applicable +* HTTPS only, no HTTP URLs +* No MD5/SHA1 for security purposes diff --git a/.claude/PROJECT.md b/.claude/PROJECT.md deleted file mode 100644 index 1226316..0000000 --- a/.claude/PROJECT.md +++ /dev/null @@ -1,33 +0,0 @@ -# NextGen Language Evangeliser - Claude Code Instructions - -This repository contains the Next Generation Language Evangeliser project. - -## Project Structure - -``` -nextgen-language-evangeliser/ -├── .claude/ # AI assistant instructions -├── .git/ # Version control -├── .gitignore # Git ignore rules -├── .editorconfig # Editor configuration -└── ... # Evangelism files -``` - -## Build Commands - -Refer to project-specific documentation. - -## Coding Conventions - -- Follow hyperpolymath standards -- All code must have SPDX license headers -- Use approved languages only (see CLAUDE.md) -- Document all non-obvious decisions - -## Security - -- No hardcoded secrets -- All secrets through environment variables or secret management -- SHA-pinned dependencies where applicable -- HTTPS only, no HTTP URLs -- No MD5/SHA1 for security purposes diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..20997c8 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,295 @@ +== Code of Conduct + +=== Compassionate Code Contribution Pledge (CCCP) + +==== Our Philosophy: "`Celebrate Good, Minimize Bad, Show Better`" + +This Code of Conduct is based on the *Compassionate Code Contribution +Pledge (CCCP)*, which extends beyond traditional codes of conduct to +address *emotional safety* in software development. + +We recognize that: - *Imposter syndrome* is real and affects many +developers - *Public shaming* for technical mistakes is harmful and +counterproductive - *Learning requires safety* to experiment, fail, and +grow - *Diversity in experience* makes our community stronger + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a *harassment-free, psychologically safe 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, religion +* Sexual identity and orientation +* Technical skill level or background + +We pledge to act and interact in ways that contribute to an *open, +welcoming, diverse, inclusive, and healthy* community. + +=== Our Standards + +==== Positive Behaviors ✅ + +Examples of behavior that contributes to a positive environment: + +* *Celebrating knowledge*: Recognizing what others already know and can +do +* *Encouraging learning*: Supporting others in their learning journey +* *Constructive feedback*: Providing feedback that builds up rather than +tears down +* *Empathy*: Showing understanding and compassion towards others +* *Respect*: Being respectful of differing opinions, viewpoints, and +experiences +* *Graciousness*: Accepting constructive criticism gracefully +* *Community focus*: Prioritizing what’s best for the overall community +* *Accountability*: Taking responsibility for mistakes and learning from +them +* *Patience*: Remembering everyone was a beginner once + +==== Unacceptable Behaviors ❌ + +Examples of unacceptable behavior: + +* *Shaming*: Belittling or ridiculing someone for not knowing something +* *Harassment*: Trolling, insulting/derogatory comments, personal or +political attacks +* *Privacy violations*: Publishing others’ private information without +permission +* *RTFM attitudes*: Hostile responses like "`Read the manual`" or +"`Google it`" +* *Gatekeeping*: Implying someone isn’t a "`real`" developer/programmer +* *Unwelcome advances*: Sexual attention or advances of any kind +* *Professional misconduct*: Other conduct inappropriate in a +professional setting +* *Discrimination*: Any form of discrimination based on protected +characteristics +* *Imposter syndrome exploitation*: Deliberately undermining someone’s +confidence + +=== Emotional Safety Commitments + +Beyond traditional code of conduct elements, we specifically commit to: + +==== 1. *No Shaming for Not Knowing* + +* ❌ "`How do you not know this?`" +* ❌ "`This is basic stuff`" +* ❌ "`Everyone knows that`" +* ✅ "`Great question! Here’s how it works…`" +* ✅ "`I learned this recently too! Let me share…`" + +==== 2. *Mistakes Are Learning Opportunities* + +* ❌ "`Wow, this code is terrible`" +* ❌ "`Did you even try?`" +* ✅ "`Here’s how we can improve this together`" +* ✅ "`I see what you’re trying to do. Have you considered…?`" + +==== 3. *Celebrate Progress, Not Just Perfection* + +* Recognize improvements and effort +* Acknowledge learning curves +* Support experimentation +* Normalize debugging and iteration + +==== 4. *Assume Good Intent* + +* Give people the benefit of the doubt +* Ask for clarification before assuming malice +* Remember communication styles vary across cultures + +==== 5. *Right to Reversibility* + +* Everyone has the right to change their mind +* Previous statements can be updated with new understanding +* Growth and evolution are encouraged + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior they deem inappropriate, +threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an online or offline event +* Contributing code, documentation, or other materials to the project + +=== Reporting + +==== How to Report + +If you experience or witness unacceptable behavior, or have any other +concerns, please report it by contacting the project maintainers at: + +* *Email*: See MAINTAINERS.adoc for contact information +* *Anonymous Form*: [Coming soon] + +All reports will be handled with *discretion and confidentiality*. + +==== What to Include + +When reporting, please include: + +[arabic] +. Your contact information (if not anonymous) +. Names (usernames) of anyone involved +. Description of the incident +. Context (links to comments, issues, etc.) +. Any additional information that may be helpful + +==== Confidentiality + +All complaints will be reviewed and investigated promptly and fairly. +Project maintainers are obligated to respect the privacy and security of +the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of time +(typically 30 days). 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. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time +(typically 90 days). 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. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, 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. + +=== Appeals Process + +If you believe an enforcement action was made in error, you may appeal +by: + +[arabic] +. Contacting a different maintainer than the one who made the decision +. Providing additional context or information +. Requesting mediation from a neutral third party + +Appeals will be reviewed within 14 days. + +=== Mental Health Resources + +If contributing to this project affects your mental health: + +* *Take a break*: Your well-being comes first +* *Seek support*: Talk to trusted friends, family, or professionals +* *Communicate*: Let maintainers know if you need accommodation + +==== Resources + +* *Crisis Text Line*: Text HOME to 741741 (US) +* *International Association for Suicide Prevention*: +https://www.iasp.info/resources/Crisis_Centres/ +* *Your local mental health resources*: [Add region-specific resources] + +=== Positive Examples from Our Community + +We celebrate these real examples of compassionate contribution: + +____ +"`I noticed you’re trying to use pattern matching here. That’s great! +Pattern matching is powerful. One small thing - ReScript needs the +switch keyword. Here’s an example…`" +____ + +____ +"`I really like your approach to this problem. It reminds me of how I +used to solve it in JavaScript! Here’s how we can adapt it to ReScript’s +type system…`" +____ + +____ +"`Great question! I actually asked the same thing when I was learning. +Here’s what helped me understand…`" +____ + +=== Acknowledgment + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +and extended with the *Compassionate Code Contribution Pledge (CCCP)* +principles. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +=== Living Document + +This Code of Conduct is a *living document* and may be updated based on +community feedback and evolving best practices. Changes will be: + +* Announced to the community +* Open for discussion before finalization +* Versioned and tracked in CHANGELOG.adoc + +*Last Updated*: 2024-11-22 *Version*: 1.0 + +''''' + +=== Contact + +For questions about this Code of Conduct: + +* *Maintainers*: See MAINTAINERS.adoc +* *GitHub Discussions*: +https://github.com/Hyperpolymath/nextgen-languages-evangeliser/discussions[Community +forum] + +''''' + +*Remember*: You were close! We’re all learning together. 💙 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index adeb620..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,228 +0,0 @@ -# Code of Conduct - -## Compassionate Code Contribution Pledge (CCCP) - -### Our Philosophy: "Celebrate Good, Minimize Bad, Show Better" - -This Code of Conduct is based on the **Compassionate Code Contribution Pledge (CCCP)**, which extends beyond traditional codes of conduct to address **emotional safety** in software development. - -We recognize that: -- **Imposter syndrome** is real and affects many developers -- **Public shaming** for technical mistakes is harmful and counterproductive -- **Learning requires safety** to experiment, fail, and grow -- **Diversity in experience** makes our community stronger - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our community a **harassment-free, psychologically safe 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, religion -- Sexual identity and orientation -- Technical skill level or background - -We pledge to act and interact in ways that contribute to an **open, welcoming, diverse, inclusive, and healthy** community. - -## Our Standards - -### Positive Behaviors ✅ - -Examples of behavior that contributes to a positive environment: - -- **Celebrating knowledge**: Recognizing what others already know and can do -- **Encouraging learning**: Supporting others in their learning journey -- **Constructive feedback**: Providing feedback that builds up rather than tears down -- **Empathy**: Showing understanding and compassion towards others -- **Respect**: Being respectful of differing opinions, viewpoints, and experiences -- **Graciousness**: Accepting constructive criticism gracefully -- **Community focus**: Prioritizing what's best for the overall community -- **Accountability**: Taking responsibility for mistakes and learning from them -- **Patience**: Remembering everyone was a beginner once - -### Unacceptable Behaviors ❌ - -Examples of unacceptable behavior: - -- **Shaming**: Belittling or ridiculing someone for not knowing something -- **Harassment**: Trolling, insulting/derogatory comments, personal or political attacks -- **Privacy violations**: Publishing others' private information without permission -- **RTFM attitudes**: Hostile responses like "Read the manual" or "Google it" -- **Gatekeeping**: Implying someone isn't a "real" developer/programmer -- **Unwelcome advances**: Sexual attention or advances of any kind -- **Professional misconduct**: Other conduct inappropriate in a professional setting -- **Discrimination**: Any form of discrimination based on protected characteristics -- **Imposter syndrome exploitation**: Deliberately undermining someone's confidence - -## Emotional Safety Commitments - -Beyond traditional code of conduct elements, we specifically commit to: - -### 1. **No Shaming for Not Knowing** - -- ❌ "How do you not know this?" -- ❌ "This is basic stuff" -- ❌ "Everyone knows that" -- ✅ "Great question! Here's how it works..." -- ✅ "I learned this recently too! Let me share..." - -### 2. **Mistakes Are Learning Opportunities** - -- ❌ "Wow, this code is terrible" -- ❌ "Did you even try?" -- ✅ "Here's how we can improve this together" -- ✅ "I see what you're trying to do. Have you considered...?" - -### 3. **Celebrate Progress, Not Just Perfection** - -- Recognize improvements and effort -- Acknowledge learning curves -- Support experimentation -- Normalize debugging and iteration - -### 4. **Assume Good Intent** - -- Give people the benefit of the doubt -- Ask for clarification before assuming malice -- Remember communication styles vary across cultures - -### 5. **Right to Reversibility** - -- Everyone has the right to change their mind -- Previous statements can be updated with new understanding -- Growth and evolution are encouraged - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an online or offline event -- Contributing code, documentation, or other materials to the project - -## Reporting - -### How to Report - -If you experience or witness unacceptable behavior, or have any other concerns, please report it by contacting the project maintainers at: - -- **Email**: See [MAINTAINERS.adoc](MAINTAINERS.adoc) for contact information -- **Anonymous Form**: [Coming soon] - -All reports will be handled with **discretion and confidentiality**. - -### What to Include - -When reporting, please include: - -1. Your contact information (if not anonymous) -2. Names (usernames) of anyone involved -3. Description of the incident -4. Context (links to comments, issues, etc.) -5. Any additional information that may be helpful - -### Confidentiality - -All complaints will be reviewed and investigated promptly and fairly. Project maintainers are obligated to respect the privacy and security of the reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time (typically 30 days). 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. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time (typically 90 days). 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. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, 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. - -## Appeals Process - -If you believe an enforcement action was made in error, you may appeal by: - -1. Contacting a different maintainer than the one who made the decision -2. Providing additional context or information -3. Requesting mediation from a neutral third party - -Appeals will be reviewed within 14 days. - -## Mental Health Resources - -If contributing to this project affects your mental health: - -- **Take a break**: Your well-being comes first -- **Seek support**: Talk to trusted friends, family, or professionals -- **Communicate**: Let maintainers know if you need accommodation - -### Resources - -- **Crisis Text Line**: Text HOME to 741741 (US) -- **International Association for Suicide Prevention**: https://www.iasp.info/resources/Crisis_Centres/ -- **Your local mental health resources**: [Add region-specific resources] - -## Positive Examples from Our Community - -We celebrate these real examples of compassionate contribution: - -> "I noticed you're trying to use pattern matching here. That's great! Pattern matching is powerful. One small thing - ReScript needs the switch keyword. Here's an example..." - -> "I really like your approach to this problem. It reminds me of how I used to solve it in JavaScript! Here's how we can adapt it to ReScript's type system..." - -> "Great question! I actually asked the same thing when I was learning. Here's what helped me understand..." - -## Acknowledgment - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, and extended with the **Compassionate Code Contribution Pledge (CCCP)** principles. - -For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. - -[homepage]: https://www.contributor-covenant.org - -## Living Document - -This Code of Conduct is a **living document** and may be updated based on community feedback and evolving best practices. Changes will be: - -- Announced to the community -- Open for discussion before finalization -- Versioned and tracked in [CHANGELOG.adoc](CHANGELOG.adoc) - -**Last Updated**: 2024-11-22 -**Version**: 1.0 - ---- - -## Contact - -For questions about this Code of Conduct: - -- **Maintainers**: See [MAINTAINERS.adoc](MAINTAINERS.adoc) -- **GitHub Discussions**: [Community forum](https://github.com/Hyperpolymath/nextgen-languages-evangeliser/discussions) - ---- - -**Remember**: You were close! We're all learning together. 💙 diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..95c7ba7 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,242 @@ +== Security Policy + +=== 🛡️ Security Philosophy + +Security is a *first-class concern* in Nextgen Languages Evangeliser. We +follow a *10+ dimensional security model*: + +[arabic] +. *Input Validation* - All user input is validated and sanitized +. *Output Encoding* - Code transformations are safe from injection +. *Authentication* - VS Code workspace trust model +. *Authorization* - File system access controls +. *Session Management* - No network sessions required (offline-first) +. *Cryptography* - No cryptographic operations (not needed) +. *Error Handling* - No sensitive data in error messages +. *Logging* - No PII in logs +. *Privacy* - Zero telemetry by default +. *Supply Chain* - Minimal dependencies, lockfile verification + +=== 🚨 Reporting Vulnerabilities + +==== Responsible Disclosure + +If you discover a security vulnerability, please report it responsibly: + +*DO:* - ✅ Email security details to the maintainers (see +MAINTAINERS.adoc) - ✅ Use encrypted email if possible (PGP key in +.well-known/security.txt) - ✅ Wait for response before public +disclosure (max 90 days) - ✅ Provide detailed reproduction steps + +*DON’T:* - ❌ Open public GitHub issues for vulnerabilities - ❌ +Disclose before maintainers have responded - ❌ Exploit vulnerabilities +for malicious purposes + +==== What to Report + +Security issues include: - Code injection vulnerabilities - Path +traversal attacks - Arbitrary code execution - Information disclosure - +Denial of service - Supply chain attacks + +==== Response Timeline + +* *24 hours*: Initial acknowledgment +* *7 days*: Preliminary assessment +* *30 days*: Fix developed and tested +* *90 days*: Public disclosure (coordinated) + +=== 🔒 Security Architecture + +==== Threat Model + +*In Scope:* - Malicious JavaScript/TypeScript files opened in VS Code - +Crafted pattern definitions - File system traversal attempts - Resource +exhaustion (DoS) + +*Out of Scope:* - Physical access to developer machine - OS-level +vulnerabilities - VS Code API vulnerabilities - Network-based attacks +(extension is offline-first) + +==== Security Boundaries + +.... +┌─────────────────────────────────────────┐ +│ VS Code Workspace (Untrusted) │ +│ ├─ User JavaScript files │ +│ └─ Custom pattern definitions │ +└─────────────────────────────────────────┘ + ↓ (sandboxed parsing) +┌─────────────────────────────────────────┐ +│ Nextgen Languages Evangeliser Extension │ +│ ├─ AST Parser (Babel, sandboxed) │ +│ ├─ Pattern Matcher (validated) │ +│ ├─ Webview (Content Security Policy) │ +│ └─ File System (read-only by default) │ +└─────────────────────────────────────────┘ +.... + +==== Defense Mechanisms + +[arabic] +. *Input Sanitization* +* All JavaScript/TypeScript parsed via Babel AST (not eval) +* Pattern regexes validated for ReDoS attacks +* File paths validated against traversal +. *Content Security Policy* +* Webview UI runs with strict CSP +* No inline scripts or styles +* No external resource loading +. *Resource Limits* +* Maximum file size: 10MB +* Parser timeout: 5 seconds +* Memory limit: 100MB per analysis +. *Least Privilege* +* Read-only file access by default +* No network access (offline-first) +* No external process execution + +=== 🔐 Privacy Guarantees + +==== Zero Telemetry by Default + +* *NO* data sent to external servers +* *NO* user-identifying information collected +* *NO* code snippets transmitted +* *NO* analytics without explicit opt-in + +==== Optional Privacy-Preserving Telemetry + +If enabled (opt-in only): - Aggregated, anonymous usage counts - Pattern +category usage (no code snippets) - Performance metrics (timing only) - +Crash reports (no PII) + +All telemetry is: - Local-first (stored in VS Code settings) - +User-controlled (can be deleted anytime) - Transparent (see +docs/TELEMETRY.md) + +=== 🧪 Security Testing + +==== Automated Testing + +[source,bash] +---- +# Run security tests +npm run test:security + +# Check dependencies for vulnerabilities +npm audit + +# Run linter with security rules +npm run lint +---- + +==== Manual Security Reviews + +Before each release: - [ ] Dependency audit (npm audit) - [ ] Code +review for injection risks - [ ] CSP header validation - [ ] File path +sanitization check - [ ] Resource limit testing - [ ] Fuzz testing +(pattern matching) + +=== 📦 Supply Chain Security + +==== Dependency Management + +*Current Dependencies:* - `+@babel/parser+` - AST parsing +(well-maintained, widely used) - `+@babel/traverse+` - AST traversal - +`+@babel/types+` - AST type definitions + +*Security Measures:* - Package lock file committed (package-lock.json) - +Regular dependency updates - Automated vulnerability scanning - Minimal +dependency tree (<10 packages) + +==== Build Integrity + +* Reproducible builds via Nix flake +* Checksum verification +* Signed commits (when available) + +=== 🌐 Offline-First Security + +==== No Network Dependencies + +This extension: - *Never* makes network requests - *Never* loads +external resources - Works in air-gapped environments - No CDN +dependencies + +==== Benefits + +* Zero network-based attack surface +* No data exfiltration risks +* No man-in-the-middle vulnerabilities +* Works in high-security environments + +=== 🎯 VS Code Workspace Trust + +This extension respects VS Code’s workspace trust model: + +* *Untrusted Workspaces*: Limited functionality (read-only) +* *Trusted Workspaces*: Full pattern detection and transformation + +See: https://code.visualstudio.com/docs/editor/workspace-trust + +=== 📋 Security Checklist for Contributors + +When contributing code: + +* [ ] No `+eval()+` or `+Function()+` constructors +* [ ] All file paths sanitized +* [ ] Regex patterns checked for ReDoS +* [ ] No hardcoded secrets or credentials +* [ ] Error messages don’t leak sensitive info +* [ ] No external network requests +* [ ] Input validation for all user data +* [ ] Resource limits respected + +See CONTRIBUTING.adoc for full guidelines. + +=== 🏆 Security Compliance + +==== Standards Followed + +* *OWASP Top 10* - Protection against common web vulnerabilities +* *CWE Top 25* - Mitigation of common software weaknesses +* *RFC 9116* - security.txt for vulnerability disclosure +* *NIST Cybersecurity Framework* - Security best practices +* *Software-Defined Perimeter* - Zero trust architecture + +==== Certifications + +* RSR Bronze-level security requirements ✅ +* Offline-first architecture ✅ +* Privacy-preserving design ✅ + +=== 📚 Additional Resources + +* https://owasp.org/[OWASP VS Code Extension Security] +* https://code.visualstudio.com/api/references/extension-manifest[VS +Code Extension Security Best Practices] +* https://www.nist.gov/cyberframework[NIST Cybersecurity Framework] + +=== 🔄 Security Updates + +Security updates are released as soon as possible: + +* *Critical*: Within 24-48 hours +* *High*: Within 7 days +* *Medium*: Within 30 days +* *Low*: Next regular release + +Subscribe to releases to stay informed: +https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases + +=== 📞 Contact + +For security concerns: + +* *Email*: See MAINTAINERS.adoc +* *PGP Key*: See .well-known/security.txt +* *Security.txt*: RFC 9116 compliant file in .well-known/ + +''''' + +*Last Updated*: 2024-11-22 *Policy Version*: 1.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 25baac0..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,262 +0,0 @@ -# Security Policy - -## 🛡️ Security Philosophy - -Security is a **first-class concern** in Nextgen Languages Evangeliser. We follow a **10+ dimensional security model**: - -1. **Input Validation** - All user input is validated and sanitized -2. **Output Encoding** - Code transformations are safe from injection -3. **Authentication** - VS Code workspace trust model -4. **Authorization** - File system access controls -5. **Session Management** - No network sessions required (offline-first) -6. **Cryptography** - No cryptographic operations (not needed) -7. **Error Handling** - No sensitive data in error messages -8. **Logging** - No PII in logs -9. **Privacy** - Zero telemetry by default -10. **Supply Chain** - Minimal dependencies, lockfile verification - -## 🚨 Reporting Vulnerabilities - -### Responsible Disclosure - -If you discover a security vulnerability, please report it responsibly: - -**DO:** -- ✅ Email security details to the maintainers (see [MAINTAINERS.adoc](MAINTAINERS.adoc)) -- ✅ Use encrypted email if possible (PGP key in [.well-known/security.txt](.well-known/security.txt)) -- ✅ Wait for response before public disclosure (max 90 days) -- ✅ Provide detailed reproduction steps - -**DON'T:** -- ❌ Open public GitHub issues for vulnerabilities -- ❌ Disclose before maintainers have responded -- ❌ Exploit vulnerabilities for malicious purposes - -### What to Report - -Security issues include: -- Code injection vulnerabilities -- Path traversal attacks -- Arbitrary code execution -- Information disclosure -- Denial of service -- Supply chain attacks - -### Response Timeline - -- **24 hours**: Initial acknowledgment -- **7 days**: Preliminary assessment -- **30 days**: Fix developed and tested -- **90 days**: Public disclosure (coordinated) - -## 🔒 Security Architecture - -### Threat Model - -**In Scope:** -- Malicious JavaScript/TypeScript files opened in VS Code -- Crafted pattern definitions -- File system traversal attempts -- Resource exhaustion (DoS) - -**Out of Scope:** -- Physical access to developer machine -- OS-level vulnerabilities -- VS Code API vulnerabilities -- Network-based attacks (extension is offline-first) - -### Security Boundaries - -``` -┌─────────────────────────────────────────┐ -│ VS Code Workspace (Untrusted) │ -│ ├─ User JavaScript files │ -│ └─ Custom pattern definitions │ -└─────────────────────────────────────────┘ - ↓ (sandboxed parsing) -┌─────────────────────────────────────────┐ -│ Nextgen Languages Evangeliser Extension │ -│ ├─ AST Parser (Babel, sandboxed) │ -│ ├─ Pattern Matcher (validated) │ -│ ├─ Webview (Content Security Policy) │ -│ └─ File System (read-only by default) │ -└─────────────────────────────────────────┘ -``` - -### Defense Mechanisms - -1. **Input Sanitization** - - All JavaScript/TypeScript parsed via Babel AST (not eval) - - Pattern regexes validated for ReDoS attacks - - File paths validated against traversal - -2. **Content Security Policy** - - Webview UI runs with strict CSP - - No inline scripts or styles - - No external resource loading - -3. **Resource Limits** - - Maximum file size: 10MB - - Parser timeout: 5 seconds - - Memory limit: 100MB per analysis - -4. **Least Privilege** - - Read-only file access by default - - No network access (offline-first) - - No external process execution - -## 🔐 Privacy Guarantees - -### Zero Telemetry by Default - -- **NO** data sent to external servers -- **NO** user-identifying information collected -- **NO** code snippets transmitted -- **NO** analytics without explicit opt-in - -### Optional Privacy-Preserving Telemetry - -If enabled (opt-in only): -- Aggregated, anonymous usage counts -- Pattern category usage (no code snippets) -- Performance metrics (timing only) -- Crash reports (no PII) - -All telemetry is: -- Local-first (stored in VS Code settings) -- User-controlled (can be deleted anytime) -- Transparent (see [docs/TELEMETRY.md](docs/TELEMETRY.md)) - -## 🧪 Security Testing - -### Automated Testing - -```bash -# Run security tests -npm run test:security - -# Check dependencies for vulnerabilities -npm audit - -# Run linter with security rules -npm run lint -``` - -### Manual Security Reviews - -Before each release: -- [ ] Dependency audit (npm audit) -- [ ] Code review for injection risks -- [ ] CSP header validation -- [ ] File path sanitization check -- [ ] Resource limit testing -- [ ] Fuzz testing (pattern matching) - -## 📦 Supply Chain Security - -### Dependency Management - -**Current Dependencies:** -- `@babel/parser` - AST parsing (well-maintained, widely used) -- `@babel/traverse` - AST traversal -- `@babel/types` - AST type definitions - -**Security Measures:** -- Package lock file committed (package-lock.json) -- Regular dependency updates -- Automated vulnerability scanning -- Minimal dependency tree (<10 packages) - -### Build Integrity - -- Reproducible builds via Nix flake -- Checksum verification -- Signed commits (when available) - -## 🌐 Offline-First Security - -### No Network Dependencies - -This extension: -- **Never** makes network requests -- **Never** loads external resources -- Works in air-gapped environments -- No CDN dependencies - -### Benefits - -- Zero network-based attack surface -- No data exfiltration risks -- No man-in-the-middle vulnerabilities -- Works in high-security environments - -## 🎯 VS Code Workspace Trust - -This extension respects VS Code's workspace trust model: - -- **Untrusted Workspaces**: Limited functionality (read-only) -- **Trusted Workspaces**: Full pattern detection and transformation - -See: https://code.visualstudio.com/docs/editor/workspace-trust - -## 📋 Security Checklist for Contributors - -When contributing code: - -- [ ] No `eval()` or `Function()` constructors -- [ ] All file paths sanitized -- [ ] Regex patterns checked for ReDoS -- [ ] No hardcoded secrets or credentials -- [ ] Error messages don't leak sensitive info -- [ ] No external network requests -- [ ] Input validation for all user data -- [ ] Resource limits respected - -See [CONTRIBUTING.adoc](CONTRIBUTING.adoc) for full guidelines. - -## 🏆 Security Compliance - -### Standards Followed - -- **OWASP Top 10** - Protection against common web vulnerabilities -- **CWE Top 25** - Mitigation of common software weaknesses -- **RFC 9116** - security.txt for vulnerability disclosure -- **NIST Cybersecurity Framework** - Security best practices -- **Software-Defined Perimeter** - Zero trust architecture - -### Certifications - -- RSR Bronze-level security requirements ✅ -- Offline-first architecture ✅ -- Privacy-preserving design ✅ - -## 📚 Additional Resources - -- [OWASP VS Code Extension Security](https://owasp.org/) -- [VS Code Extension Security Best Practices](https://code.visualstudio.com/api/references/extension-manifest) -- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework) - -## 🔄 Security Updates - -Security updates are released as soon as possible: - -- **Critical**: Within 24-48 hours -- **High**: Within 7 days -- **Medium**: Within 30 days -- **Low**: Next regular release - -Subscribe to releases to stay informed: -https://github.com/Hyperpolymath/nextgen-languages-evangeliser/releases - -## 📞 Contact - -For security concerns: - -- **Email**: See [MAINTAINERS.adoc](MAINTAINERS.adoc) -- **PGP Key**: See [.well-known/security.txt](.well-known/security.txt) -- **Security.txt**: RFC 9116 compliant file in [.well-known/](.well-known/) - ---- - -**Last Updated**: 2024-11-22 -**Policy Version**: 1.0 diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..d4bdea8 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — nextgen-languages-evangeliser (Developer) + +=== What is nextgen-languages-evangeliser? + +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 07d30b1..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — nextgen-languages-evangeliser (Developer) - -## What is nextgen-languages-evangeliser? -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..921fa51 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — nextgen-languages-evangeliser (User) + +=== What is nextgen-languages-evangeliser? + +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 ddd93c2..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — nextgen-languages-evangeliser (User) - -## What is nextgen-languages-evangeliser? -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