diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 00000000..1c0a7a69 --- /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 607e3d8c..00000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 00000000..5cbd7962 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,78 @@ +== Changelog + +All notable changes to `+gitbot-fleet+` will be documented in this file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Added + +* feat(sustainabot): migrate bot-integration from AffineScript to +AffineScr… (#199) +* feat(scripts): add fix-tracked-package-lock.sh for standards#67 +enforcement (#170) +* feat(robot-repo-automaton): canonical RSR skeleton generator +(rsr-template-repo#48) (#160) +* feat(rhodibot): add offline `+check+` CLI subcommand for CI gating +(#150) +* feat(gsbot)!: faithful Rust/SPARK port — eliminate Python from the +fleet (#145) + +==== Fixed + +* fix(examples): migrate SafeDOMExample.affine to current AffineScript +grammar (closes #208) (#210) +* fix(sustainabot): parse-blocking OCaml-isms and HANDLE-keyword name +(Refs #148) (#206) +* fix(licence): clear scaffold-placeholder leak (isolated; dirty repo) +(#167) +* fix(ci): pin upload-artifact to valid SHA in fix-unpinned-actions.sh +generator (Refs standards#48) (#163) +* fix(ci): bump a2ml/k9-validate-action pins to canonical (standards#85) +(#162) +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#161) +* fix: resolve gitbot-fleet legacy hypatia findings at source; +de-baseline (#152) +* fix(ci): adopt canonical hypatia-scan.yml (env.HOME/scanner-layout + +Comment-step gate) (#151) +* fix(shared-context): clear pre-existing clippy -D warnings debt (item +B) (#149) +* fix: stagger estate push to stop CI thundering-herd (#147) + +==== Documentation + +* docs(archive): session record for sustainabot #148 hand-port +validation (#209) +* docs: promote stub .adoc to faithful AsciiDoc from canonical .md (Item +11 Group A) (#159) + +==== CI + +* ci: redistribute concurrency-cancel guard to read-only check workflows +(#165) +* ci(hypatia-scan): restore hardened workflow (supersedes #129) (#142) +* ci(workflow): adopt hardened hypatia-scan from +hyperpolymath/hypatia#237 (#126) +* ci: bump actions/upload-artifact SHA to current v4 (#123) +* ci(hypatia-scan): wire FLEET_DISPATCH_TOKEN to its own secret + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 00000000..96ccf97b --- /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 +Gitbot Fleet a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |\{\{CONDUCT_EMAIL}} |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *\{\{RESPONSE_TIME}}* +. The \{\{CONDUCT_TEAM}} will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a \{\{CONDUCT_TEAM}} member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The \{\{CONDUCT_TEAM}} will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* \{\{CONDUCT_EMAIL}} with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different \{\{CONDUCT_TEAM}} member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/gitbot-fleet/discussions[Discussion] +(for general questions) +* Email \{\{CONDUCT_EMAIL}} (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index d6c4d20b..00000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Gitbot Fleet a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **{{RESPONSE_TIME}}** -2. The {{CONDUCT_TEAM}} will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a {{CONDUCT_TEAM}} member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The {{CONDUCT_TEAM}} will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different {{CONDUCT_TEAM}} member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/gitbot-fleet/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 00000000..8b752933 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,109 @@ +== Clone the repository + +git clone https://github.com/hyperpolymath/gitbot-fleet.git cd +gitbot-fleet + +== Using Guix (recommended for reproducibility) + +guix shell -D -f guix.scm + +== Or using toolbox/distrobox + +toolbox create gitbot-fleet-dev toolbox enter gitbot-fleet-dev # Install +dependencies manually + +== Verify setup + +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +gitbot-fleet/ ├── 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 ├── guix.scm # Guix +manifest (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/gitbot-fleet/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/gitbot-fleet/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/gitbot-fleet/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/gitbot-fleet/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 8259fa5d..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet - -# Using Guix (recommended for reproducibility) -guix shell -D -f guix.scm - -# Or using toolbox/distrobox -toolbox create gitbot-fleet-dev -toolbox enter gitbot-fleet-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -gitbot-fleet/ -├── 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 -├── guix.scm # Guix manifest (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/gitbot-fleet/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/gitbot-fleet/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/gitbot-fleet/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/gitbot-fleet/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 00000000..9b836fb2 --- /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 e27364c7..00000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 00000000..99b67ce8 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,40 @@ +== Proof Requirements + +=== Current state + +* ABI directory exists (template-level) +* No dangerous patterns found +* 100K lines; bot fleet for repository quality enforcement +* Claims: "`formal mathematical/statistical verification`" + +=== What needs proving + +* *Bot action safety*: Prove that automated bot actions (PRs, issues, +fixes) are reversible and do not destroy repository state +* *Confidence threshold correctness*: Prove that the +robot-repo-automaton confidence thresholds correctly gate automated +merges (no auto-merge below threshold) +* *Rule conflict resolution*: Prove that when multiple bots (rhodibot, +echidnabot, sustainabot, etc.) produce conflicting recommendations, the +resolution is deterministic and documented +* *Rate limiting*: Prove bots respect GitHub API rate limits and do not +cause cascading failures across the fleet + +=== Recommended prover + +* *Idris2* — For bot action safety and confidence threshold properties +* *Lean4* — For algebraic properties of confidence scoring if modeled as +an ordered semiring + +=== Priority + +* *MEDIUM* — The fleet manages automated repository changes. Incorrect +bot behavior at scale could damage many repos. The "`formal +verification`" claim should be substantiated. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +\{\{PROJECT}}/\{\{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 2c21dc2f..00000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,26 +0,0 @@ -# Proof Requirements - -## Current state -- ABI directory exists (template-level) -- No dangerous patterns found -- 100K lines; bot fleet for repository quality enforcement -- Claims: "formal mathematical/statistical verification" - -## What needs proving -- **Bot action safety**: Prove that automated bot actions (PRs, issues, fixes) are reversible and do not destroy repository state -- **Confidence threshold correctness**: Prove that the robot-repo-automaton confidence thresholds correctly gate automated merges (no auto-merge below threshold) -- **Rule conflict resolution**: Prove that when multiple bots (rhodibot, echidnabot, sustainabot, etc.) produce conflicting recommendations, the resolution is deterministic and documented -- **Rate limiting**: Prove bots respect GitHub API rate limits and do not cause cascading failures across the fleet - -## Recommended prover -- **Idris2** — For bot action safety and confidence threshold properties -- **Lean4** — For algebraic properties of confidence scoring if modeled as an ordered semiring - -## Priority -- **MEDIUM** — The fleet manages automated repository changes. Incorrect bot behavior at scale could damage many repos. The "formal verification" claim should be substantiated. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved {{PROJECT}}/{{AUTHOR}} placeholders and no domain-specific proofs. diff --git a/READINESS.adoc b/READINESS.adoc new file mode 100644 index 00000000..0013b22a --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,99 @@ +== gitbot-fleet Component Readiness Assessment + +*Standard:* +https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades[Component +Readiness Grades (CRG) v2.2] *Current Grade:* B *Assessed:* 2026-04-04 +*Assessor:* Jonathan D.A. Jewell + Claude Sonnet 4.6 + +''''' + +=== Summary + +[width="100%",cols="19%,5%,12%,64%",options="header",] +|=== +|Component |Grade |Release Stage |Evidence Summary +|`+rhodibot+` |B |Beta |RSR compliance PRs created on 50+ repos, 9/9 +dispatch flows confirmed + +|`+echidnabot+` |B |Beta |Proof verification dispatched to 18+ repos, +echidna rules confirmed + +|`+sustainabot+` |B |Beta |Advisory reports on 283+ repos via hypatia +pipeline + +|`+glambot+` |C |Alpha-stable |Aesthetic/style suggestions wired; +limited external validation + +|`+seambot+` |C |Alpha-stable |Integration seam detection wired; limited +external validation + +|`+finishbot+` |C |Alpha-stable |Completion analysis wired; limited +external validation + +|Fleet coordinator |B |Beta |Dispatched to 283+ repos via hypatia → +dispatch-manifest → runner chain +|=== + +*Overall:* Grade B for the core three bots and dispatch chain. Grade C +for aesthetic/completion bots. + +''''' + +=== Grade B Evidence — External Targets + +gitbot-fleet dispatch chain has operated on the full hyperpolymath +estate: + +[arabic] +. *Rust repos* (iseriser, a2ml-rs, conflow, panic-attacker) — RSR +compliance PRs, proof checks +. *Elixir/OTP repos* (hypatia, burble, oblibeny) — quality checks, +advisory reports +. *Gleam repos* (k9_gleam, a2ml_gleam, polyglot-formalisms-gleam) — +language policy enforcement +. *Multi-language monorepos* (developer-ecosystem, standards, +nextgen-languages) — fleet dispatch +. *Game repos* (idaptik, airborne-submarine-squadron) — security + +advisory scope +. *Formal verification repos* (ephapax, stapeln) — proof-regression +checks via echidnabot + +Dispatch statistics: - 1635 dispatched actions (600 auto-execute, 667 +review, 368 report-only) - 16671 outcomes recorded (99% success rate) - +Bayesian confidence updating (prior_strength=10, floor=0.10, cap=0.99) + +Issues found and addressed: - Dispatch rate limiting added (50/min per +bot, 200/min global) - Bot quarantine on repeated failures (5+ failures +or >30% FP rate) - Batch rollback capability for auto_execute tier + +''''' + +=== Grade C Evidence — `+glambot+`, `+seambot+`, `+finishbot+` + +These bots are wired in the OTP supervision tree but have limited +external validation: - `+glambot+`: aesthetic suggestions generated but +not yet systematically applied - `+seambot+`: integration seam detection +algorithm complete but limited cross-repo data - `+finishbot+`: +completion analysis logic present but calibration needed + +*Promotion path to B:* Validate each on 6+ diverse repos with documented +improvement outcomes. + +''''' + +=== Concerns and Maintenance Notes + +[arabic] +. *PAT token*: Automated cross-repo dispatch requires a PAT with +`+repo+` scope — currently missing +. *Fix scripts*: 310/600 auto-execute entries have null fix_script — +recipes exist but no executable +. *False positive rate*: ~8% on some pattern categories; kanren +context-facts would reduce to ~2-3% +. *VCL federation*: Local-only; multi-store federation not implemented +. *Neural state persistence*: State dir exists but coordinator hasn’t +persisted to disk + +''''' + +=== Run `+just crg-badge+` to generate the shields.io badge for your README. diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index 28222d74..00000000 --- a/READINESS.md +++ /dev/null @@ -1,73 +0,0 @@ - - - -# gitbot-fleet Component Readiness Assessment - -**Standard:** [Component Readiness Grades (CRG) v2.2](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) -**Current Grade:** B -**Assessed:** 2026-04-04 -**Assessor:** Jonathan D.A. Jewell + Claude Sonnet 4.6 - ---- - -## Summary - -| Component | Grade | Release Stage | Evidence Summary | -|--------------------|-------|---------------|---------------------------------------------------------------------------| -| `rhodibot` | B | Beta | RSR compliance PRs created on 50+ repos, 9/9 dispatch flows confirmed | -| `echidnabot` | B | Beta | Proof verification dispatched to 18+ repos, echidna rules confirmed | -| `sustainabot` | B | Beta | Advisory reports on 283+ repos via hypatia pipeline | -| `glambot` | C | Alpha-stable | Aesthetic/style suggestions wired; limited external validation | -| `seambot` | C | Alpha-stable | Integration seam detection wired; limited external validation | -| `finishbot` | C | Alpha-stable | Completion analysis wired; limited external validation | -| Fleet coordinator | B | Beta | Dispatched to 283+ repos via hypatia → dispatch-manifest → runner chain | - -**Overall:** Grade B for the core three bots and dispatch chain. Grade C for aesthetic/completion bots. - ---- - -## Grade B Evidence — External Targets - -gitbot-fleet dispatch chain has operated on the full hyperpolymath estate: - -1. **Rust repos** (iseriser, a2ml-rs, conflow, panic-attacker) — RSR compliance PRs, proof checks -2. **Elixir/OTP repos** (hypatia, burble, oblibeny) — quality checks, advisory reports -3. **Gleam repos** (k9_gleam, a2ml_gleam, polyglot-formalisms-gleam) — language policy enforcement -4. **Multi-language monorepos** (developer-ecosystem, standards, nextgen-languages) — fleet dispatch -5. **Game repos** (idaptik, airborne-submarine-squadron) — security + advisory scope -6. **Formal verification repos** (ephapax, stapeln) — proof-regression checks via echidnabot - -Dispatch statistics: -- 1635 dispatched actions (600 auto-execute, 667 review, 368 report-only) -- 16671 outcomes recorded (99% success rate) -- Bayesian confidence updating (prior_strength=10, floor=0.10, cap=0.99) - -Issues found and addressed: -- Dispatch rate limiting added (50/min per bot, 200/min global) -- Bot quarantine on repeated failures (5+ failures or >30% FP rate) -- Batch rollback capability for auto_execute tier - ---- - -## Grade C Evidence — `glambot`, `seambot`, `finishbot` - -These bots are wired in the OTP supervision tree but have limited external validation: -- `glambot`: aesthetic suggestions generated but not yet systematically applied -- `seambot`: integration seam detection algorithm complete but limited cross-repo data -- `finishbot`: completion analysis logic present but calibration needed - -**Promotion path to B:** Validate each on 6+ diverse repos with documented improvement outcomes. - ---- - -## Concerns and Maintenance Notes - -1. **PAT token**: Automated cross-repo dispatch requires a PAT with `repo` scope — currently missing -2. **Fix scripts**: 310/600 auto-execute entries have null fix_script — recipes exist but no executable -3. **False positive rate**: ~8% on some pattern categories; kanren context-facts would reduce to ~2-3% -4. **VCL federation**: Local-only; multi-store federation not implemented -5. **Neural state persistence**: State dir exists but coordinator hasn't persisted to disk - ---- - -## Run `just crg-badge` to generate the shields.io badge for your README. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 00000000..d999c5c5 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,41 @@ +== Security Policy + +=== Supported Versions + +[cols=",",options="header",] +|=== +|Version |Supported +|main |:white_check_mark: +|=== + +=== Reporting a Vulnerability + +To report a security vulnerability, please use GitHub’s private +vulnerability reporting feature: + +[arabic] +. Go to the Security tab of this repository +. Click "`Report a vulnerability`" +. Provide details about the vulnerability + +*Do not* open public issues for security vulnerabilities. + +=== Security Measures + +This project follows the Hyperpolymath security standards: + +* SPDX license headers on all files +* SHA-pinned GitHub Actions +* CodeQL analysis enabled +* OpenSSF Scorecard monitoring +* Branch protection enabled + +=== Cryptographic Standards + +This project adheres to `+CRYPTO-STANDARD.scm+`: + +* Password hashing: Argon2id +* General hashing: BLAKE3 +* Post-quantum signatures: Dilithium5 (ML-DSA-87) +* Post-quantum key exchange: Kyber-1024 (ML-KEM-1024) +* Classical signatures: Ed448 (Ed25519 acceptable for SSH) diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 8d077497..00000000 --- a/SECURITY.md +++ /dev/null @@ -1,40 +0,0 @@ - - - -# Security Policy - -## Supported Versions - -| Version | Supported | -| ------- | ------------------ | -| main | :white_check_mark: | - -## Reporting a Vulnerability - -To report a security vulnerability, please use GitHub's private vulnerability reporting feature: - -1. Go to the Security tab of this repository -2. Click "Report a vulnerability" -3. Provide details about the vulnerability - -**Do not** open public issues for security vulnerabilities. - -## Security Measures - -This project follows the Hyperpolymath security standards: - -- SPDX license headers on all files -- SHA-pinned GitHub Actions -- CodeQL analysis enabled -- OpenSSF Scorecard monitoring -- Branch protection enabled - -## Cryptographic Standards - -This project adheres to `CRYPTO-STANDARD.scm`: - -- Password hashing: Argon2id -- General hashing: BLAKE3 -- Post-quantum signatures: Dilithium5 (ML-DSA-87) -- Post-quantum key exchange: Kyber-1024 (ML-KEM-1024) -- Classical signatures: Ed448 (Ed25519 acceptable for SSH) diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 00000000..26a21494 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,136 @@ +== Test & Benchmark Requirements + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +=== Current State (updated 2026-04-04) + +==== What Was Added (this session — CRG C blitz) + +[width="100%",cols="22%,44%,34%",options="header",] +|=== +|Area |Tests Added |Location +|`+robot-repo-automaton+` fixer idempotency |3 tests +(delete/create/modify × apply-twice) +|`+robot-repo-automaton/tests/fixer_tests.rs+` + +|`+robot-repo-automaton+` path traversal security |4 tests +(delete/create/modify traversal + safe path) +|`+robot-repo-automaton/tests/fixer_tests.rs+` + +|`+robot-repo-automaton+` confidence numeric thresholds |5 tests +(0.95/0.7 boundaries, Delete thresholds, decide outputs) +|`+robot-repo-automaton/src/confidence.rs+` (in-module) + +|Shared-context E2E fleet coordination |6 scenarios (single-bot, +multi-bot, failure isolation, persistence, reporting, severity gate) +|`+shared-context/tests/e2e_fleet_coordination_test.rs+` + +|Shared-context P2P property tests |11 property tests (bot subsets, +confidence bounds, dispatch determinism) +|`+shared-context/tests/property_tests.rs+` + +|Shared-context `+context_tests.rs+` fixes |Fixed stale API calls, tokio +missing features |`+shared-context/tests/context_tests.rs+` + +|`+echidnabot+` benchmark (stub → real) |assess_confidence × 3 variants, +all ProverKinds, file extension lookups +|`+bots/echidnabot/benches/echidnabot_bench.rs+` + +|Path traversal guard in fixer |`+normalise_path()+` + security check in +`+Fixer::apply()+` |`+robot-repo-automaton/src/fixer.rs+` + +|Shell script syntax validation |85 scripts validated with `+bash -n+` +(0 errors) |All `+*.sh+` in repo +|=== + +==== Test Counts After This Session + +[width="100%",cols="28%,42%,30%",options="header",] +|=== +|Crate |Test Count |Status +|`+shared-context+` (all test files) |67 tests |All passing + +|`+robot-repo-automaton+` (lib + 3 test files + doctest) |79 tests |All +passing + +|`+panicbot+` |76 tests |All passing + +|`+seambot+` |68 tests |All passing + +|`+glambot+` |47 tests |All passing +|=== + +''''' + +=== Remaining Gaps + +==== High Priority + +* *Unit tests for `+Detector::detect_all+` with numeric confidence +thresholds*: The task-level thresholds (>0.9 auto-apply, 0.7-0.9 +suggest, <0.7 skip) are documented in tests but only exercised via +`+FixAction::Delete+`. Tests for other action types (Modify, Create) +should be added. +* *robot-repo-automaton: `+detector.rs+` confidence score verification*: +Content-match detection returns 0.95, file-existence returns 1.0, +language mismatch returns 0.90 — these specific values should be +regression-tested. +* *sustainabot*: Has minimal test coverage (only `+test_sample.rs+`). +The 6-crate workspace needs test coverage per crate. +* *finishingbot*: `+analyzer_tests.rs+` exists but coverage vs source +count is unclear. + +==== Medium Priority + +* *Fleet E2E at script level*: `+fleet-coordinator.sh+` + +`+dispatch-runner.sh+` integration — currently untested end-to-end. Bash +integration tests via `+bats+` or similar. +* *Dashboard*: No tests found. +* *367 JavaScript files*: Bot action scripts (campaigns/, hooks/) are +completely untested. +* *34 Julia files*: No tests. + +==== Low Priority + +* *Fuzz testing*: `+tests/fuzz/placeholder.txt+` is still a scorecard +placeholder from rsr-template-repo — does NOT provide real fuzz +coverage. Replace with a real libFuzzer harness targeting +`+robot-repo-automaton+` catalog parsing. +* *self-test / fleet health check*: No self-diagnostic for the fleet as +a whole. +* *echidnabot benchmark*: The real benchmark was added but not verified +to compile (compilation takes >2 minutes). Verify on next visit. + +=== Shell Script Validation (2026-04-04) + +.... +$ find . -name "*.sh" -not -path "*/target/*" | xargs bash -n +(no output — all 85 scripts pass syntax check) +.... + +*Result: 85/85 scripts pass `+bash -n+` with zero syntax errors.* + +=== Session 9 additions (2026-04-04) + +==== What Was Added + +[width="100%",cols="22%,44%,34%",options="header",] +|=== +|Area |Tests Added |Location +|Fleet E2E |6 sections: repo structure, fleet member inventory (9 bots), +bash syntax checks on all `+.sh+` scripts, fleet-coordinator help +output, workflow YAML validity, bot Cargo.toml integrity +|`+tests/e2e.sh+` + +|CI runner |GitHub Actions workflow for E2E suite +|`+.github/workflows/e2e.yml+` +|=== + +==== Updated Test Counts + +[cols=",,",options="header",] +|=== +|Suite |Count |Status +|E2E (shell-based) |6 test sections |All passing +|CI workflows |21 |Running tests on GitHub Actions +|=== diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 7ea711c5..00000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,98 +0,0 @@ -# Test & Benchmark Requirements - -## CRG Grade: C — ACHIEVED 2026-04-04 - -## Current State (updated 2026-04-04) - -### What Was Added (this session — CRG C blitz) - -| Area | Tests Added | Location | -|------|-------------|----------| -| `robot-repo-automaton` fixer idempotency | 3 tests (delete/create/modify × apply-twice) | `robot-repo-automaton/tests/fixer_tests.rs` | -| `robot-repo-automaton` path traversal security | 4 tests (delete/create/modify traversal + safe path) | `robot-repo-automaton/tests/fixer_tests.rs` | -| `robot-repo-automaton` confidence numeric thresholds | 5 tests (0.95/0.7 boundaries, Delete thresholds, decide outputs) | `robot-repo-automaton/src/confidence.rs` (in-module) | -| Shared-context E2E fleet coordination | 6 scenarios (single-bot, multi-bot, failure isolation, persistence, reporting, severity gate) | `shared-context/tests/e2e_fleet_coordination_test.rs` | -| Shared-context P2P property tests | 11 property tests (bot subsets, confidence bounds, dispatch determinism) | `shared-context/tests/property_tests.rs` | -| Shared-context `context_tests.rs` fixes | Fixed stale API calls, tokio missing features | `shared-context/tests/context_tests.rs` | -| `echidnabot` benchmark (stub → real) | assess_confidence × 3 variants, all ProverKinds, file extension lookups | `bots/echidnabot/benches/echidnabot_bench.rs` | -| Path traversal guard in fixer | `normalise_path()` + security check in `Fixer::apply()` | `robot-repo-automaton/src/fixer.rs` | -| Shell script syntax validation | 85 scripts validated with `bash -n` (0 errors) | All `*.sh` in repo | - -### Test Counts After This Session - -| Crate | Test Count | Status | -|-------|-----------|--------| -| `shared-context` (all test files) | 67 tests | All passing | -| `robot-repo-automaton` (lib + 3 test files + doctest) | 79 tests | All passing | -| `panicbot` | 76 tests | All passing | -| `seambot` | 68 tests | All passing | -| `glambot` | 47 tests | All passing | - ---- - -## Remaining Gaps - -### High Priority - -- **Unit tests for `Detector::detect_all` with numeric confidence thresholds**: - The task-level thresholds (>0.9 auto-apply, 0.7-0.9 suggest, <0.7 skip) are - documented in tests but only exercised via `FixAction::Delete`. Tests for other - action types (Modify, Create) should be added. - -- **robot-repo-automaton: `detector.rs` confidence score verification**: - Content-match detection returns 0.95, file-existence returns 1.0, language - mismatch returns 0.90 — these specific values should be regression-tested. - -- **sustainabot**: Has minimal test coverage (only `test_sample.rs`). The 6-crate - workspace needs test coverage per crate. - -- **finishingbot**: `analyzer_tests.rs` exists but coverage vs source count is unclear. - -### Medium Priority - -- **Fleet E2E at script level**: `fleet-coordinator.sh` + `dispatch-runner.sh` - integration — currently untested end-to-end. Bash integration tests via - `bats` or similar. - -- **Dashboard**: No tests found. - -- **367 JavaScript files**: Bot action scripts (campaigns/, hooks/) are completely - untested. - -- **34 Julia files**: No tests. - -### Low Priority - -- **Fuzz testing**: `tests/fuzz/placeholder.txt` is still a scorecard placeholder - from rsr-template-repo — does NOT provide real fuzz coverage. Replace with a - real libFuzzer harness targeting `robot-repo-automaton` catalog parsing. - -- **self-test / fleet health check**: No self-diagnostic for the fleet as a whole. - -- **echidnabot benchmark**: The real benchmark was added but not verified to - compile (compilation takes >2 minutes). Verify on next visit. - -## Shell Script Validation (2026-04-04) - -``` -$ find . -name "*.sh" -not -path "*/target/*" | xargs bash -n -(no output — all 85 scripts pass syntax check) -``` - -**Result: 85/85 scripts pass `bash -n` with zero syntax errors.** - -## Session 9 additions (2026-04-04) - -### What Was Added - -| Area | Tests Added | Location | -|------|-------------|----------| -| Fleet E2E | 6 sections: repo structure, fleet member inventory (9 bots), bash syntax checks on all `.sh` scripts, fleet-coordinator help output, workflow YAML validity, bot Cargo.toml integrity | `tests/e2e.sh` | -| CI runner | GitHub Actions workflow for E2E suite | `.github/workflows/e2e.yml` | - -### Updated Test Counts - -| Suite | Count | Status | -|-------|-------|--------| -| E2E (shell-based) | 6 test sections | All passing | -| CI workflows | 21 | Running tests on GitHub Actions | diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 89% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 41ac7ccd..8f9ae2aa 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,12 +1,8 @@ - - - +== Gitbot Fleet — Project Topology -# Gitbot Fleet — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ OPERATOR / ADMIN │ │ (Fleet Coordinator, Dashy) │ @@ -47,11 +43,11 @@ │ Justfile / Docker .machine_readable/ │ │ OPSM Integration 0-AI-MANIFEST.a2ml │ └─────────────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE FLEET @@ -72,25 +68,26 @@ INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: ██████████ 100% Full quality fleet active -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Shared Context ───► rhodibot ───────► sustainabot ──────► finishbot │ │ │ │ ▼ ▼ ▼ ▼ echidnabot ─────► glambot ────────► seambot ────────► Release Ready -``` +.... -## 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/bots/accessibilitybot/SONNET-TASKS.adoc b/bots/accessibilitybot/SONNET-TASKS.adoc new file mode 100644 index 00000000..582c6a61 --- /dev/null +++ b/bots/accessibilitybot/SONNET-TASKS.adoc @@ -0,0 +1,330 @@ +== Accessibilitybot — Sonnet Task Plan (NEW BOT) + +=== Context + +Accessibilitybot is a NEW Tier 2 (Finisher) bot in the gitbot-fleet +ecosystem. It enforces WCAG 2.3 AAA compliance, ARIA correctness, +semantic HTML/XML integrity, and accessibility best practices across +repositories. + +*This bot does not yet exist.* This plan describes creating it from +scratch using the RSR template. + +*Philosophy*: Accessibility is not optional. CSS-first, HTML-second. +Full WCAG 2.3 AAA compliance. Semantic XML with ARIA. This aligns with +the user’s explicit security/accessibility requirements. + +''''' + +=== Task 0: Scaffold the Repository + +==== 0.1 Clone from RSR template + +[source,bash] +---- +cd ~/Documents/hyperpolymath-repos +git clone https://github.com/hyperpolymath/rsr-template-repo accessibilitybot +cd accessibilitybot +rm -rf .git && git init -b main +---- + +==== 0.2 Set up Rust workspace + +[source,bash] +---- +cargo init --name accessibilitybot +---- + +==== 0.3 Cargo.toml + +[source,toml] +---- +[package] +name = "accessibilitybot" +version = "0.1.0" +edition = "2021" +license = "MPL-2.0" +authors = ["Jonathan D.A. Jewell "] +description = "WCAG 2.3 AAA Accessibility Compliance Bot for gitbot-fleet" + +[dependencies] +gitbot-shared-context = { path = "../gitbot-fleet/shared-context" } +clap = { version = "4", features = ["derive"] } +serde = { version = "1", features = ["derive"] } +serde_json = "1" +anyhow = "1" +tracing = "0.1" +tracing-subscriber = "0.3" +walkdir = "2" +regex = "1" +scraper = "0.20" # HTML parsing + CSS selectors +---- + +==== 0.4 Standard RSR files + +* All 6 SCM files in `+.machine_readable/+` +* Bot directives in `+.bot_directives/+` +* Contractiles in `+contractiles/+` +* 16+ standard workflows in `+.github/workflows/+` +* SPDX headers on all files + +''''' + +=== Task 1: Core WCAG Analyzers + +==== 1.1 Image Alt Text Analyzer (`+src/analyzers/alt_text.rs+`) + +* Scan HTML/JSX/TSX files for `++` tags +* Check: every `++` has a non-empty `+alt+` attribute +* Check: alt text is descriptive (not just "`image`", "`photo`", +"`icon`") +* Check: decorative images use `+alt=""+` (empty, not missing) +* Severity: Error for missing alt, Warning for generic alt text +* WCAG criterion: 1.1.1 Non-text Content (Level A) + +==== 1.2 Color Contrast Analyzer (`+src/analyzers/contrast.rs+`) + +* Parse CSS files for color/background-color pairs +* Calculate contrast ratio using WCAG 2.3 algorithm +* AAA requirements: 7:1 for normal text, 4.5:1 for large text +* Check: inline styles in HTML also comply +* Severity: Error for below AA (4.5:1), Warning for below AAA (7:1) +* WCAG criterion: 1.4.6 Contrast (Enhanced) (Level AAA) + +==== 1.3 Semantic HTML Analyzer (`+src/analyzers/semantic.rs+`) + +* Check: pages use semantic elements (`+
+`, `+