diff --git a/.github/workflows/hypatia-scan.yml b/.github/workflows/hypatia-scan.yml index 0b784f0c..5e8a5a67 100644 --- a/.github/workflows/hypatia-scan.yml +++ b/.github/workflows/hypatia-scan.yml @@ -25,7 +25,7 @@ permissions: jobs: hypatia: - uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@915139d73560e65a8240b8fc7768698658502c89 + uses: hyperpolymath/standards/.github/workflows/hypatia-scan-reusable.yml@6cd3772824e59c8c9affeab66061e25383544242 secrets: inherit # Total caller-side wall-clock cap for the reusable. Matches # Hypatia's `missing_timeout_minutes` rule expectation. The scan is diff --git a/.machine_readable/MUST.contractile b/.machine_readable/MUST.contractile index 4e82c8b2..b723c5c3 100644 --- a/.machine_readable/MUST.contractile +++ b/.machine_readable/MUST.contractile @@ -26,7 +26,7 @@ ; remain active until the feature is fully removed. ; ; Enforcement: -; K9 validators in contractiles/k9/ machine-check MUST constraints. +; K9 validators in contractiles/self-validating/ machine-check MUST constraints. ; CI runs these on every PR. Violations block merge. ; ; ── End Definitions ────────────────────────────────────────────── @@ -85,7 +85,7 @@ ; (must "# Add project-specific invariants here") (enforcement - (k9-validator "contractiles/k9/must-check.k9.ncl") + (k9-validator "contractiles/self-validating/must-check.k9.ncl") (ci "quality.yml runs must-check on every PR") ) ) diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/bot_directives/README.adoc similarity index 94% rename from .machine_readable/agent_instructions/README.adoc rename to .machine_readable/bot_directives/README.adoc index 9bc2e24b..4e989c74 100644 --- a/.machine_readable/agent_instructions/README.adoc +++ b/.machine_readable/bot_directives/README.adoc @@ -32,7 +32,7 @@ Methodology-aware configuration for AI agents. Read by any AI agent == Relationship to Other Files * `AGENTIC.a2ml` says WHAT agents can do (permissions, gating) -* `agent_instructions/` says HOW agents should work (methodology) +* `bot_directives/` says HOW agents should work (methodology) * `bot_directives/` says what the gitbot-fleet does (fleet-specific) * `CLAUDE.md` says how Claude specifically should work (Claude-specific) diff --git a/.machine_readable/agent_instructions/coverage.a2ml b/.machine_readable/bot_directives/coverage.a2ml similarity index 100% rename from .machine_readable/agent_instructions/coverage.a2ml rename to .machine_readable/bot_directives/coverage.a2ml diff --git a/.machine_readable/agent_instructions/debt.a2ml b/.machine_readable/bot_directives/debt.a2ml similarity index 100% rename from .machine_readable/agent_instructions/debt.a2ml rename to .machine_readable/bot_directives/debt.a2ml diff --git a/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml similarity index 100% rename from .machine_readable/agent_instructions/methodology.a2ml rename to .machine_readable/bot_directives/methodology.a2ml diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 13039cc2..aa22fb3a 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -139,9 +139,12 @@ execution testing. Gates the path from draft to publishable. | `bots/finishingbot/` |=== -Additional bots present in `bots/`: `accessibilitybot`, `cipherbot`, `panicbot` -(pre-commit gate wrapping panic-attacker), `gsbot` (game-server integration), -`the-hotchocolabot` (onboarding/warmth checks). +Additional fleet bots present in `bots/`: `accessibilitybot`, `cipherbot`, +`panicbot` (pre-commit gate wrapping panic-attacker). + +Standalone repos that are not part of gitbot-fleet but are still maintained in +the estate: `gsbot` (https://github.com/hyperpolymath/gsbot) and +`hotchocolabot` (https://github.com/hyperpolymath/hotchocolabot). == Dogfooded Across The Account diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 00000000..8bbf167d --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,162 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Governance Model +:toc: preamble + +This document describes the governance model for this repository. + +== Overview + +This repository follows a **Sole Maintainer Governance Model**: + +* Single maintainer (@hyperpolymath) has full authority over the project +* All contributions are welcome and reviewed by the maintainer +* Decisions are made transparently through GitHub issues and discussions +* The project adheres to the hyperpolymath estate policies where applicable + +== Core Principles + +[cols="1,2"] +|=== +| Principle | Description + +| **Benevolent Dictatorship** | Maintainer has final decision authority but seeks community input + +| **Meritocracy** | Contributions are judged on technical merit, not contributor identity + +| **Transparency** | All significant decisions are documented publicly + +| **Consensus-Seeking** | Maintainer prefers consensus but will decide when necessary + +| **Open Contribution** | Anyone can contribute via fork and pull request + +|=== + +== Roles and Permissions + +[cols="1,2,2"] +|=== +| Role | Permissions | Assignment + +| **Maintainer** | Write access, merge rights, admin | @hyperpolymath +| **Contributors** | Read access, fork, submit PRs | All GitHub users +| **Users** | Use the software, report issues | All GitHub users + +|=== + +== Decision Making Framework + +=== Routine Decisions + +* Bug fixes +* Documentation improvements +* Minor feature additions +* Dependency updates + +**Process**: Maintainer reviews and merges PRs that meet quality standards. + +=== Significant Changes + +* New major features +* API changes +* Architecture modifications +* Breaking changes + +**Process**: +. Open issue describing the change +. Discuss with community (minimum 72 hours) +. Maintainer makes final decision +. Document rationale in issue/PR + +=== Structural Decisions + +* Repository purpose/renaming +* License changes +* Ownership transfer +* Deprecation/archival + +**Process**: +. Extended discussion (minimum 1 week) +. Maintainer makes final decision +. Document in CHANGELOG and governance docs + +== Contribution Lifecycle + +[cols="1,2"] +|=== +| Stage | Process + +| **Ideation** | Open issue, discuss feasibility + +| **Development** | Fork, implement, test thoroughly + +| **Review** | Submit PR, maintainer reviews within 7 days + +| **Merge** | Maintainer merges or requests changes + +| **Release** | Maintainer publishes according to project conventions + +|=== + +== Conflict Resolution + +In case of disagreements: + +. Discuss in the relevant GitHub issue or PR +. Provide technical justification for positions +. Maintainer mediates and makes final decision +. Decision is documented and can be revisited later + +== Project Policies + +This repository adheres to hyperpolymath estate-wide policies: + +* **License**: MPL-2.0 for code, CC-BY-SA-4.0 for prose (per standards/LICENCE-POLICY.adoc) +* **Code of Conduct**: Follows hyperpolymath CODE_OF_CONDUCT.md +* **Security**: Follows hyperpolymath SECURITY.md +* **Contributing**: Follows hyperpolymath CONTRIBUTING.adoc conventions + +== Repository-Specific Conventions + +[cols="1,2"] +|=== +| Convention | Description + +| **Signing** | All commits must be signed (SSH or GPG) + +| **SPDX Headers** | All source files must have SPDX license identifiers + +| **Contractiles** | Mustfile, Trustfile, Intendfile, Adjustfile in root + +| **Machine Readable** | META.a2ml in .machine_readable/6a2/ + +| **CI/CD** | GitHub Actions workflows in .github/workflows/ + +|=== + +== Governance Evolution + +As the project grows, this governance model may evolve: + +* **Adding Co-Maintainers**: When contribution volume warrants it +* **Forming a Team**: For complex multi-maintainer projects +* **Adopting TPCF**: For large, multi-repository projects (see rhodium-standard-repositories) + +Changes to this document require the same process as Significant Changes above. + +== See Also + +* link:MAINTAINERS.adoc[Maintainers] +* link:CODE_OF_CONDUCT.md[Code of Conduct] +* link:CONTRIBUTING.adoc[Contributing Guide] +* link:https://github.com/hyperpolymath/standards/blob/main/LICENCE-POLICY.adoc[Estate License Policy] +* link:https://github.com/hyperpolymath/standards[rhodium-standard-repositories (TPCF)] + +== Changelog + +[cols="1,1,1"] +|=== +| Date | Change | By + +| 2026-06-07 | Initial governance model established | @hyperpolymath +|=== diff --git a/README.adoc b/README.adoc index c2267f4b..9838e3ab 100644 --- a/README.adoc +++ b/README.adoc @@ -16,7 +16,7 @@ toc::[] == Overview -Gitbot Fleet coordinates 11 specialised bots through a shared-context layer. The +Gitbot Fleet coordinates 9 specialised bots through a shared-context layer. The `fleet-coordinator` dispatches Hypatia scanner findings to bots based on the **safety triangle**: @@ -82,21 +82,18 @@ The historical `TOPOLOGY.md` dashboard is at the repo root. |Release readiness. Placeholder removal, license validation, claim verification, execution testing. |Complete -|**gsbot** -|Discord bot for garment sustainability. Sustainability scores, environmental impact analysis, sustainable brand discovery. -|Active - |**panicbot** |Panic recovery and error handling validation. Ensures graceful degradation and proper error handling patterns. |Active - -|**the-hotchocolabot** -|Educational robotics platform for teaching reverse engineering and systems thinking. Over-engineered hot chocolate dispenser. -|Active |=== *Status legend:* `Active` = Tier 1 Verifier or Specialist bot running on every push. `Complete` = Tier 2 Finisher bot that runs after verifiers to validate final release readiness. +Standalone repos that are intentionally not fleet bots: + +* `gsbot` - https://github.com/hyperpolymath/gsbot +* `hotchocolabot` - https://github.com/hyperpolymath/hotchocolabot + The component-readiness assessment (CRG grades, evidence) lives in link:READINESS.md[READINESS.md]. diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 00373077..db5f9530 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -12,7 +12,7 @@ toc::[] == Current State -Gitbot Fleet coordinates 11 bots through a shared-context system with safety-triangle-aware +Gitbot Fleet coordinates 9 bots through a shared-context system with safety-triangle-aware routing. The fleet-coordinator dispatches findings from Hypatia scans to specialised bots based on confidence thresholds (Eliminate >= 0.95, Substitute >= 0.85, Control < 0.85). @@ -29,12 +29,15 @@ based on confidence thresholds (Eliminate >= 0.95, Substitute >= 0.85, Control < | seambot | Integration seam maintenance | Yes | finishingbot | Completion of partial work | Yes | panicbot | Security scanning (panic-attack) | No (uses panic-attack roadmap) -| gsbot | Git-seo, discoverability | Yes | accessibilitybot | Accessibility compliance | Yes | cipherbot | Cryptographic hygiene | Yes -| the-hotchocolabot | Developer experience, warmth | Yes |=== +Standalone repos kept out of the fleet roster: + +* `gsbot` - separate repo: https://github.com/hyperpolymath/gsbot +* `hotchocolabot` - separate repo: https://github.com/hyperpolymath/hotchocolabot + **Infrastructure:** * fleet-coordinator.sh -- orchestration layer diff --git a/bots/gsbot/README.adoc b/bots/gsbot/README.adoc index 2fa2fe88..b805ec8f 100644 --- a/bots/gsbot/README.adoc +++ b/bots/gsbot/README.adoc @@ -232,8 +232,8 @@ gsbot/ [source,bash] ---- # Clone repository -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot # Configure environment cp .env.example .env diff --git a/bots/gsbot/content/docs/DEPLOYMENT.md b/bots/gsbot/content/docs/DEPLOYMENT.md index 5907d48e..be489abd 100644 --- a/bots/gsbot/content/docs/DEPLOYMENT.md +++ b/bots/gsbot/content/docs/DEPLOYMENT.md @@ -39,8 +39,8 @@ This guide covers deployment options for the Garment Sustainability Bot. ### Quick Start ```bash -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot cp .env.example .env # then edit .env: set DISCORD_TOKEN just init # build + load sample data just run # run the bot @@ -50,8 +50,8 @@ just run # run the bot 1. **Clone repository:** ```bash -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot ``` 2. **Configure environment:** @@ -157,8 +157,8 @@ sudo apt update && sudo apt install -y git 3. **Clone and build:** ```bash -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot cargo build --release --bin gsbot ``` @@ -178,9 +178,9 @@ After=network.target [Service] Type=simple User=ubuntu -WorkingDirectory=/home/ubuntu/gitbot-fleet/bots/gsbot -EnvironmentFile=/home/ubuntu/gitbot-fleet/bots/gsbot/.env -ExecStart=/home/ubuntu/gitbot-fleet/bots/gsbot/target/release/gsbot +WorkingDirectory=/home/ubuntu/gsbot +EnvironmentFile=/home/ubuntu/gsbot/.env +ExecStart=/home/ubuntu/gsbot/target/release/gsbot Restart=always RestartSec=10 @@ -242,7 +242,7 @@ Schedule it from cron, e.g.: ```bash # crontab -e -0 2 * * * cd /home/ubuntu/gitbot-fleet/bots/gsbot && ./target/release/gsbot-backup-db +0 2 * * * cd /home/ubuntu/gsbot && ./target/release/gsbot-backup-db ``` You can also export to JSON: @@ -458,7 +458,7 @@ If an update fails: ## Support -- GitHub Issues: https://github.com/hyperpolymath/gitbot-fleet/issues +- GitHub Issues: https://github.com/hyperpolymath/gsbot/issues - Documentation: README.adoc, CLAUDE.md - Architecture: docs/ARCHITECTURE.md - API docs: docs/API.md diff --git a/bots/gsbot/docs/DEPLOYMENT.md b/bots/gsbot/docs/DEPLOYMENT.md index 293baea6..5aadd9cf 100644 --- a/bots/gsbot/docs/DEPLOYMENT.md +++ b/bots/gsbot/docs/DEPLOYMENT.md @@ -34,8 +34,8 @@ This guide covers deployment options for the Garment Sustainability Bot. ### Quick Start ```bash -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot cp .env.example .env # then edit .env: set DISCORD_TOKEN just init # build + load sample data just run # run the bot @@ -45,8 +45,8 @@ just run # run the bot 1. **Clone repository:** ```bash -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot ``` 2. **Configure environment:** @@ -152,8 +152,8 @@ sudo apt update && sudo apt install -y git 3. **Clone and build:** ```bash -git clone https://github.com/hyperpolymath/gitbot-fleet.git -cd gitbot-fleet/bots/gsbot +git clone https://github.com/hyperpolymath/gsbot.git +cd gsbot cargo build --release --bin gsbot ``` @@ -173,9 +173,9 @@ After=network.target [Service] Type=simple User=ubuntu -WorkingDirectory=/home/ubuntu/gitbot-fleet/bots/gsbot -EnvironmentFile=/home/ubuntu/gitbot-fleet/bots/gsbot/.env -ExecStart=/home/ubuntu/gitbot-fleet/bots/gsbot/target/release/gsbot +WorkingDirectory=/home/ubuntu/gsbot +EnvironmentFile=/home/ubuntu/gsbot/.env +ExecStart=/home/ubuntu/gsbot/target/release/gsbot Restart=always RestartSec=10 @@ -237,7 +237,7 @@ Schedule it from cron, e.g.: ```bash # crontab -e -0 2 * * * cd /home/ubuntu/gitbot-fleet/bots/gsbot && ./target/release/gsbot-backup-db +0 2 * * * cd /home/ubuntu/gsbot && ./target/release/gsbot-backup-db ``` You can also export to JSON: @@ -453,7 +453,7 @@ If an update fails: ## Support -- GitHub Issues: https://github.com/hyperpolymath/gitbot-fleet/issues +- GitHub Issues: https://github.com/hyperpolymath/gsbot/issues - Documentation: README.adoc, CLAUDE.md - Architecture: docs/ARCHITECTURE.md - API docs: docs/API.md diff --git a/bots/the-hotchocolabot/CLAUDE.md b/bots/the-hotchocolabot/CLAUDE.md index 27d01849..5a1b6471 100644 --- a/bots/the-hotchocolabot/CLAUDE.md +++ b/bots/the-hotchocolabot/CLAUDE.md @@ -2,14 +2,14 @@ ## Project Overview -**the-hotchocolabot** is a bot project designed to automate tasks and provide interactive functionality. +**hotchocolabot** is a bot project designed to automate tasks and provide interactive functionality. ## Project Structure This is a new project. The typical structure will include: ``` -the-hotchocolabot/ +hotchocolabot/ ├── src/ # Source code ├── tests/ # Test files ├── config/ # Configuration files @@ -92,7 +92,7 @@ Install dependencies according to the package manager used in the project. ## Resources ### Useful Links -- Project repository: https://github.com/Hyperpolymath/the-hotchocolabot +- Project repository: https://github.com/Hyperpolymath/hotchocolabot - Add links to relevant documentation, APIs, or frameworks ### Documentation diff --git a/bots/the-hotchocolabot/Cargo.toml b/bots/the-hotchocolabot/Cargo.toml index be44fbb3..3c3f0231 100644 --- a/bots/the-hotchocolabot/Cargo.toml +++ b/bots/the-hotchocolabot/Cargo.toml @@ -5,7 +5,7 @@ edition = "2021" authors = ["UAL Creative Communities - MechCC"] description = "Educational robotics platform teaching reverse engineering through an over-engineered hot chocolate dispenser" license = "MPL-2.0" -repository = "https://github.com/Hyperpolymath/the-hotchocolabot" +repository = "https://github.com/Hyperpolymath/hotchocolabot" readme = "README.md" keywords = ["robotics", "education", "embedded", "raspberry-pi"] categories = ["embedded", "hardware-support"] diff --git a/bots/the-hotchocolabot/HANDOVER.md b/bots/the-hotchocolabot/HANDOVER.md index 2fd36892..221aa3ab 100644 --- a/bots/the-hotchocolabot/HANDOVER.md +++ b/bots/the-hotchocolabot/HANDOVER.md @@ -231,7 +231,7 @@ All printable as PDF packets (~15-20 pages per student). ## Repository Structure ``` -the-hotchocolabot/ +hotchocolabot/ ├── .github/ │ ├── workflows/ # CI/CD automation │ │ ├── rust_ci.yml # Test, lint, audit, cross-compile @@ -287,8 +287,8 @@ the-hotchocolabot/ ```bash # Clone repository -git clone https://github.com/Hyperpolymath/the-hotchocolabot.git -cd the-hotchocolabot +git clone https://github.com/Hyperpolymath/hotchocolabot.git +cd hotchocolabot # Install Rust (if needed) curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh @@ -320,7 +320,7 @@ just deploy HOST=pi@raspberrypi.local # Or build directly on Pi ssh pi@raspberrypi.local -cd ~/the-hotchocolabot +cd ~/hotchocolabot cargo build --release sudo ./target/release/hotchocolabot ``` @@ -582,9 +582,9 @@ These questions from the original handover should be addressed: ## Contact & Support ### Repository -- GitHub: https://github.com/Hyperpolymath/the-hotchocolabot -- Issues: https://github.com/Hyperpolymath/the-hotchocolabot/issues -- Discussions: https://github.com/Hyperpolymath/the-hotchocolabot/discussions +- GitHub: https://github.com/Hyperpolymath/hotchocolabot +- Issues: https://github.com/Hyperpolymath/hotchocolabot/issues +- Discussions: https://github.com/Hyperpolymath/hotchocolabot/discussions ### Team - Lead: [Your name] (see MAINTAINERS.md) diff --git a/bots/the-hotchocolabot/MAINTAINERS.md b/bots/the-hotchocolabot/MAINTAINERS.md index cf58b4fd..21e37eaa 100644 --- a/bots/the-hotchocolabot/MAINTAINERS.md +++ b/bots/the-hotchocolabot/MAINTAINERS.md @@ -123,8 +123,8 @@ _None yet - project is new!_ ### For General Questions -- **GitHub Issues**: https://github.com/Hyperpolymath/the-hotchocolabot/issues -- **Discussions**: https://github.com/Hyperpolymath/the-hotchocolabot/discussions +- **GitHub Issues**: https://github.com/Hyperpolymath/hotchocolabot/issues +- **Discussions**: https://github.com/Hyperpolymath/hotchocolabot/discussions ### For Private Matters diff --git a/bots/the-hotchocolabot/README.adoc b/bots/the-hotchocolabot/README.adoc index 961d9854..976144b0 100644 --- a/bots/the-hotchocolabot/README.adoc +++ b/bots/the-hotchocolabot/README.adoc @@ -5,7 +5,7 @@ image:[Palimpsest-MPL-1.0,link="https://github.com/hyperpolymath/palimpsest-lice *An Educational Robotics Platform for Teaching Reverse Engineering and Systems Thinking* [![RSR Bronze](https://img.shields.io/badge/RSR-Bronze-cd7f32?style=flat-square)](RSR_COMPLIANCE.md) -[![CI](https://img.shields.io/github/actions/workflow/status/Hyperpolymath/the-hotchocolabot/rust_ci.yml?style=flat-square)](https://github.com/Hyperpolymath/the-hotchocolabot/actions) +[![CI](https://img.shields.io/github/actions/workflow/status/Hyperpolymath/hotchocolabot/rust_ci.yml?style=flat-square)](https://github.com/Hyperpolymath/hotchocolabot/actions) Part of UAL Creative Communities' Postdisciplinary Mechatronics Group (MechCC) @@ -72,8 +72,8 @@ The deliberate complexity serves pedagogical purposes: = Clone repository image:https://img.shields.io/badge/License-PMPL--1.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] -git clone https://github.com/Hyperpolymath/the-hotchocolabot.git -cd the-hotchocolabot +git clone https://github.com/Hyperpolymath/hotchocolabot.git +cd hotchocolabot = Copy configuration template @@ -166,7 +166,7 @@ scp target/armv7-unknown-linux-gnueabihf/release/hotchocolabot pi@raspberrypi.lo === Code Organization ``` -the-hotchocolabot/ +hotchocolabot/ ├── src/ │ ├── main.rs # Entry point │ ├── config/ # Configuration management @@ -341,8 +341,8 @@ Dual-licensed under MIT OR Apache-2.0. See `LICENSE-MIT` and `LICENSE-APACHE` fo == Contact -- Repository: https://github.com/Hyperpolymath/the-hotchocolabot -- Issues: https://github.com/Hyperpolymath/the-hotchocolabot/issues +- Repository: https://github.com/Hyperpolymath/hotchocolabot +- Issues: https://github.com/Hyperpolymath/hotchocolabot/issues --- diff --git a/bots/the-hotchocolabot/docs/CITATIONS.adoc b/bots/the-hotchocolabot/docs/CITATIONS.adoc index dee36132..5070ee37 100644 --- a/bots/the-hotchocolabot/docs/CITATIONS.adoc +++ b/bots/the-hotchocolabot/docs/CITATIONS.adoc @@ -1,34 +1,34 @@ -= the-hotchocolabot - Citation Guide += hotchocolabot - Citation Guide :toc: == BibTeX [source,bibtex] ---- -@software{the-hotchocolabot_2025, +@software{hotchocolabot_2025, author = {Polymath, Hyper}, - title = {the-hotchocolabot}, + title = {hotchocolabot}, year = {2025}, - url = {https://github.com/hyperpolymath/the-hotchocolabot}, + url = {https://github.com/hyperpolymath/hotchocolabot}, license = {MPL-2.0} } ---- == Harvard Style -Polymath, H. (2025) _the-hotchocolabot_ [Computer software]. Available at: https://github.com/hyperpolymath/the-hotchocolabot +Polymath, H. (2025) _hotchocolabot_ [Computer software]. Available at: https://github.com/hyperpolymath/hotchocolabot == OSCOLA -Hyper Polymath, 'the-hotchocolabot' (2025) +Hyper Polymath, 'hotchocolabot' (2025) == MLA -Polymath, Hyper. "the-hotchocolabot." 2025, github.com/hyperpolymath/the-hotchocolabot. +Polymath, Hyper. "hotchocolabot." 2025, github.com/hyperpolymath/hotchocolabot. == APA 7 -Polymath, H. (2025). _the-hotchocolabot_ [Computer software]. GitHub. https://github.com/hyperpolymath/the-hotchocolabot +Polymath, H. (2025). _hotchocolabot_ [Computer software]. GitHub. https://github.com/hyperpolymath/hotchocolabot == See Also diff --git a/bots/the-hotchocolabot/docs/competition/partnership_letter_template.md b/bots/the-hotchocolabot/docs/competition/partnership_letter_template.md index c52a9659..04643a5e 100644 --- a/bots/the-hotchocolabot/docs/competition/partnership_letter_template.md +++ b/bots/the-hotchocolabot/docs/competition/partnership_letter_template.md @@ -353,7 +353,7 @@ Theme: Food security & education Deadline: April 1, 2026 Contact: [Your Name], [Email], [Phone] -Website: github.com/Hyperpolymath/the-hotchocolabot +Website: github.com/Hyperpolymath/hotchocolabot ``` --- diff --git a/bots/the-hotchocolabot/docs/competition/submission_checklist.md b/bots/the-hotchocolabot/docs/competition/submission_checklist.md index b7ed9f04..1e22680f 100644 --- a/bots/the-hotchocolabot/docs/competition/submission_checklist.md +++ b/bots/the-hotchocolabot/docs/competition/submission_checklist.md @@ -70,7 +70,7 @@ - [ ] Hardware documentation (BOM, wiring, assembly) - [ ] Educational materials included -**Repository**: https://github.com/Hyperpolymath/the-hotchocolabot +**Repository**: https://github.com/Hyperpolymath/hotchocolabot ### ✅ 5. Partnership Letters diff --git a/bots/the-hotchocolabot/docs/competition/video_script_template.md b/bots/the-hotchocolabot/docs/competition/video_script_template.md index 16e9f25b..d31a0f56 100644 --- a/bots/the-hotchocolabot/docs/competition/video_script_template.md +++ b/bots/the-hotchocolabot/docs/competition/video_script_template.md @@ -221,7 +221,7 @@ Open-Source Robotics Education Platform 35% Knowledge Gain 100% Open Source -github.com/Hyperpolymath/the-hotchocolabot +github.com/Hyperpolymath/hotchocolabot UAL Creative Communities - MechCC ``` diff --git a/bots/the-hotchocolabot/education/workshops/workshop_curriculum.md b/bots/the-hotchocolabot/education/workshops/workshop_curriculum.md index 78c64f37..a43c81eb 100644 --- a/bots/the-hotchocolabot/education/workshops/workshop_curriculum.md +++ b/bots/the-hotchocolabot/education/workshops/workshop_curriculum.md @@ -583,7 +583,7 @@ See separate file: `education/assessments/workshop_survey.md` - Technical Support: MechCC team **Resources:** -- Code Repository: https://github.com/Hyperpolymath/the-hotchocolabot +- Code Repository: https://github.com/Hyperpolymath/hotchocolabot - Issue Tracker: [Report problems or suggestions] - MechCC Website: [Link to UAL Creative Communities] diff --git a/bots/the-hotchocolabot/fuzz/Cargo.toml b/bots/the-hotchocolabot/fuzz/Cargo.toml index b9c30ae2..483b33db 100644 --- a/bots/the-hotchocolabot/fuzz/Cargo.toml +++ b/bots/the-hotchocolabot/fuzz/Cargo.toml @@ -10,7 +10,7 @@ cargo-fuzz = true [dependencies] libfuzzer-sys = "0.4" -[dependencies.the-hotchocolabot] +[dependencies.hotchocolabot] path = ".." [[bin]] diff --git a/bots/the-hotchocolabot/hardware/assembly/assembly_instructions.md b/bots/the-hotchocolabot/hardware/assembly/assembly_instructions.md index e2eb8026..987ddd86 100644 --- a/bots/the-hotchocolabot/hardware/assembly/assembly_instructions.md +++ b/bots/the-hotchocolabot/hardware/assembly/assembly_instructions.md @@ -409,8 +409,8 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # Clone repository -git clone https://github.com/Hyperpolymath/the-hotchocolabot.git -cd the-hotchocolabot +git clone https://github.com/Hyperpolymath/hotchocolabot.git +cd hotchocolabot # Copy and edit configuration cp config.toml.example config.toml diff --git a/bots/the-hotchocolabot/hardware/schematics/wiring_diagram.md b/bots/the-hotchocolabot/hardware/schematics/wiring_diagram.md index 7a4bb992..d5119a37 100644 --- a/bots/the-hotchocolabot/hardware/schematics/wiring_diagram.md +++ b/bots/the-hotchocolabot/hardware/schematics/wiring_diagram.md @@ -355,7 +355,7 @@ Pin 20 (GND) ────────────────────── 3. **Software Test**: ```bash - cd ~/the-hotchocolabot + cd ~/hotchocolabot cargo run ``` - Watch for successful hardware initialization diff --git a/docs/TOKEN-ARCHITECTURE.adoc b/docs/TOKEN-ARCHITECTURE.adoc new file mode 100644 index 00000000..d4ff1ee3 --- /dev/null +++ b/docs/TOKEN-ARCHITECTURE.adoc @@ -0,0 +1,630 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell +// +// gitbot-fleet Token Architecture +// ================================ +// +// *Purpose*: Canonical reference for all tokens used by gitbot-fleet bots. +// This document is the *fleet-specific* companion to the estate-wide +// token matrix in `/developer/dev-notes/GITHUB-PAT-AND-TOKEN-MATRIX.adoc`. +// +// *Last Revised*: 2026-06-04 +// +// *Audience*: Fleet bot maintainers, security auditors, and AI agents +// attempting to understand why hotchocolobot is NOT part of the fleet. + += gitbot-fleet Token Architecture +:description: Complete token specifications for all fleet bots and the .git-private-farm propagation system +:toc: auto +:toclevels: 4 + +== Executive Summary + +This fleet contains **seven operational bots** plus **one honorary member**. +Each bot has its own **narrow-scoped token** following the principle of +*least privilege* and *separation of concerns*. + +[IMPORTANT] +==== +*GitHub Classic PATs have coarse-grained scopes.* The `repo` scope is +the minimum atomic unit, which bundles many permissions together. +This means even "read-only" monitoring requires `repo` scope. + +*Mitigation:* Use separate tokens per bot/concern and rotate aggressively. +==== + +=== Quick Reference: All Fleet Tokens + +[cols="1,1,1,1,1"] +|=== +| Bot | Token | Primary Scope | Blast Radius | Purpose + +| rhodibot | `RHODIBOT_TOKEN` | `repo` | Low | RSR template cleanup +| glambot | `GLAMBOT_TOKEN` | `repo` | Low | Front-facing UX (docs, wiki, README) +| echidnabot | `ECHIDNABOT_TOKEN` | `repo`, `workflow` | Medium | Proof automation + Echidna integration +| sustainabot | `SUSTAINABOT_TOKEN` | `repo` | Low | Reports, comments, CodeCite integration +| panicbot | `PANICBOT_TOKEN` | `repo` | Low | Deep code scanning (panic-attack) +| robot-repo-automaton | `ROBOT_REPO_AUTOMATON_TOKEN` | `repo`, `admin:repo_hook`, `admin:public_key`, `admin:org` | *HIGH* | Multi-forge sync orchestration +| .git-private-farm | `PRIVATE_FARM_TOKEN` (aka `HOOKSYNC_TOKEN`) | `repo`, `workflow`, `admin:repo_hook` | *HIGH* | Mass propagation system +| hotchocolobot | ❌ NONE | ❌ NONE | ❌ NONE | *HONORARY FLEET STATUS ONLY* +|=== + +== Architecture Overview + +[ditaa] +---- ++----------------+ +----------------+ +------------------+ +| | | | | | +| HYPATIA | | .git-private- | | gitbot-fleet | +| (dispatcher) |---->| farm |<--->| (actuators) | +| | | (propagator) | | | ++--------+-------+ +--------+-------+ +------+-----------+ + | | | + | HYPATIA_DISPATCH_PAT | | + | | PRIVATE_FARM_TOKEN | Individual Bot Tokens + v v v ++--------+-------+ +--------+-------+ +------+-----------+ +| Trigger | | Mass | | Bot Operations | +| workflows | | workflow | | (per bot) | +| in fleet | | dispatch | | | ++----------------+ +----------------+ +------------------+ +---- + +== Bot-Specific Token Details + +=== 1. rhodibot + +* *Token*: `RHODIBOT_TOKEN` +* *Scope*: `repo` +* *Purpose*: RSR (ReScript/Reason/OCaml) template cleanup — fixes template drift + and inconsistencies across the estate +* *Blast Radius*: Low +* *Path Restrictions*: + ** Read/write: `.rsr-template-repo/` + ** Read-only: All other paths (for detection) + +.Why This Scope +[cols="1,1"] +|=== +| Permission | Needed For + +| `contents:read` | Scanning repos for template drift +| `contents:write` | Applying template fixes +| `pull_requests:write` | Creating fix PRs +| `issues:read` | Checking for template-related issues +|=== + +.Actions Performed +[cols="1,1"] +|=== +| Operation | Endpoint/Path + +| Detect drift | `GET /repos/{owner}/{repo}/contents/.rsr-template-repo/` +| Apply fixes | `PUT /repos/{owner}/{repo}/contents/.rsr-template-repo/` +| Create PR | `POST /repos/{owner}/{repo}/pulls` +|=== + +=== 2. glambot + +* *Token*: `GLAMBOT_TOKEN` +* *Scope*: `repo` +* *Purpose*: Front-facing UX management — documentation, social content, wiki, + README, and stateful-artefacts +* *Blast Radius*: Low +* *Path Restrictions*: + ** Read/write: `docs/`, `README.*`, `.github/wiki/`, `stateful-artefacts/` + ** Read-only: All other paths + +[CAUTION] +==== +*glambot MUST NOT have write access to:* + +* Source code directories (`src/`, `lib/`, `app/`, etc.) +* CI/CD workflows (`.github/workflows/`) +* Configuration files (`config/`, `mix.exs`, `package.json`, etc.) +* Proof artifacts (`.proofs/`, `.prooftrace/`) +* Security files (`.github/security/`, `.gitleaks.toml`, etc.) + +*Enforce this via:* Path restrictions in bot logic + code review of all glambot PRs +==== + +.Actions Performed +[cols="1,1"] +|=== +| Operation | Endpoint/Path + +| Read documentation | `GET /repos/{owner}/{repo}/contents/docs/` +| Write documentation | `PUT /repos/{owner}/{repo}/contents/docs/` +| Read wiki | `GET /repos/{owner}/{repo}/wiki/` +| Write wiki | `PUT /repos/{owner}/{repo}/wiki/` +| Update README | `PUT /repos/{owner}/{repo}/contents/README.*` +| Manage stateful-artefacts | `GET/PUT /repos/hyperpolymath/reposystem/contents/stateful-artefacts/` +|=== + +=== 3. echidnabot + +* *Token*: `ECHIDNABOT_TOKEN` +* *Scope*: `repo`, `workflow` +* *Purpose*: Formal verification automation — reads proof schedules, executes + proofs via Echidna, deposits outcomes via ProofTrace tool +* *Blast Radius*: Medium (affects proof outcomes and verification state) +* *Used With*: Echidna prover, ProofTrace tool + +.Why `workflow` Scope +This bot triggers Echidna workflows for proof execution, which requires the +`workflow` scope in addition to `repo`. + +.Actions Performed +[cols="1,1"] +|=== +| Operation | Endpoint/Path + +| Read proof schedules | `GET /repos/{owner}/{repo}/contents/.proofs/` +| Read Echidna config | `GET /repos/{owner}/{repo}/contents/echidna.yml` +| Write proof outcomes | `PUT /repos/{owner}/{repo}/contents/.proofs/outcomes/` +| Trigger Echidna workflow | `POST /repos/{owner}/{repo}/actions/workflows/echidna-scan.yml/dispatches` +| Read ProofTrace data | `GET /repos/{owner}/{repo}/contents/.prooftrace/` +| Write ProofTrace data | `PUT /repos/{owner}/{repo}/contents/.prooftrace/` +|=== + +=== 4. sustainabot + +* *Token*: `SUSTAINABOT_TOKEN` +* *Scope*: `repo` +* *Purpose*: Reporting and commenting — writes PR/issue comments, generates + CodeCite dependency reports, highlights code quality issues +* *Blast Radius*: Low (creates comments and reports only) +* *Used With*: CodeCite tool + +[NOTE] +==== +*Sustainabot does NOT modify code.* Its operations are limited to: + +* Writing PR review comments +* Writing issue comments +* Generating CodeCite dependency reports +* Creating summary documents +* Triggering reporting workflows + +*No code changes. No configuration changes. No direct repository modifications.* +==== + +.Actions Performed +[cols="1,1"] +|=== +| Operation | Endpoint/Path + +| Read repo for analysis | `GET /repos/{owner}/{repo}/contents/` +| Create PR comment | `POST /repos/{owner}/{repo}/pulls/{pr}/comments` +| Create issue comment | `POST /repos/{owner}/{repo}/issues/{issue}/comments` +| Write CodeCite reports | `PUT /repos/{owner}/{repo}/contents/.codecite/` +| Trigger reporting workflow | `POST /repos/{owner}/{repo}/actions/workflows/report.yml/dispatches` +|=== + +=== 5. panicbot + +* *Token*: `PANICBOT_TOKEN` +* *Scope*: `repo` +* *Purpose*: Deep code scanning and advisory — runs panic-attack scans, provides + security and quality advisories +* *Blast Radius*: Low (read-only scanning, writes only advisory output) +* *Based On*: panic-attack repo + +.Actions Performed +[cols="1,1"] +|=== +| Operation | Endpoint/Path + +| Read source code | `GET /repos/{owner}/{repo}/contents/` +| Read panic-attack config | `GET /repos/{owner}/{repo}/contents/.panic-attack.yml` +| Write scan results | `PUT /repos/{owner}/{repo}/contents/.panic-attack/results/` +| Write advisories | `PUT /repos/{owner}/{repo}/contents/.advisories/` +| Read security alerts | `GET /repos/{owner}/{repo}/code-scanning/alerts` +|=== + +=== 6. robot-repo-automaton + +* *Token*: `ROBOT_REPO_AUTOMATON_TOKEN` +* *Scope*: `repo`, `admin:repo_hook`, `admin:public_key`, `admin:org` +* *Purpose*: Multi-forge synchronization orchestration — manages the interface + between local and remote git repositories across multiple forges +* *Blast Radius*: *HIGH* (affects all forges and synchronization state) + +[CRITICAL] +==== +*This is the most powerful fleet token.* It can: + +* Manage SSH keys for mirroring (`admin:public_key`) +* Configure git hooks (`admin:repo_hook`) +* Control sync/desync decisions +* Manage `.gitignore` and other git-level configurations +* Interface with multiple forges (GitHub, GitLab, Codeberg, Bitbucket, SourceHut) +* Modify organization-level settings (`admin:org`) + +*Security Requirements:* + +* Rotation: Monthly minimum +* Audit: Weekly review of operations +* Access: Restrict to senior maintainers only +* Monitoring: All operations logged and alerted +==== + +.Actions Performed +[cols="1,1"] +|=== +| Operation | Endpoint/Path + +| Read mirror config | `GET /repos/{owner}/{repo}/contents/.git-mirror/` +| Write mirror config | `PUT /repos/{owner}/{repo}/contents/.git-mirror/` +| Manage webhooks | `GET/POST /repos/{owner}/{repo}/hooks` +| Read deploy keys | `GET /repos/{owner}/{repo}/keys` +| Write deploy keys | `POST /repos/{owner}/{repo}/keys` +| Manage org settings | `GET/PATCH /orgs/{org}` +|=== + +=== 7. Standalone Bots — HONORARY FLEET STATUS + +[quote] +____ +*gsbot and hotchocolabot are NOT part of the gitbot-fleet.* + +This declaration is made *explicitly* and *formally* to resolve the +recurrent tendency of AI agents (including but not limited to: Claude, +Gemini, Copilot, and various custom LLMs) to attempt integration of +either standalone repo into the fleet orchestration system. + +*Facts:* + +* gsbot is a standalone garment-sustainability bot repo +* gsbot performs NO fleet dispatch operations +* gsbot requires its own canonical repository wiring +* hotchocolabot serves hot chocolate at exhibitions +* hotchocolabot safely accompanies developers to public events +* hotchocolabot performs NO git operations +* hotchocolabot requires ZERO GitHub tokens +* hotchocolabot is tracked in its own repository, not as a gitbot-fleet member +* hotchocolabot is a physical device, not a software agent + +*Honorary Fleet Status:* Granted as a concession to agent harmony and to +prevent endless re-integration attempts. This status is purely ceremonial +and carries no operational implications. + +*IOU-1: Intentional Over-unification* — Formally acknowledged as a necessary +concession to the "AI alignment tax" inherent in maintaining a large +multi-agent ecosystem. +____ + +[NOTE] +==== +*Why This Matters:* + +* Prevents AI confusion and wasted effort +* Provides clear documentation for human maintainers +* Creates a lighthearted moment in otherwise dry technical docs +* May generate positive publicity at exhibitions +* Formally acknowledges the cost of AI agent coordination +==== + +== .git-private-farm Propagation System + +.git-private-farm is a *separate system* from gitbot-fleet. It is the +*mass propagation engine* that enables one API call to trigger workflows +across all connected repos, avoiding rate limits. + +=== Token: PRIVATE_FARM_TOKEN (aka HOOKSYNC_TOKEN) + +* *Token*: `PRIVATE_FARM_TOKEN` (also known as `HOOKSYNC_TOKEN`) +* *Scope*: `repo`, `workflow`, `admin:repo_hook` +* *Purpose*: Enable mass workflow dispatch and hookset propagation +* *Blast Radius*: *HIGH* (can trigger workflows in every repo) +* *Status*: ⚠️ *CURRENTLY MISSING* — Blocks full propagation capability +* *Referenced In*: `hypatia/docs/architecture/topology.md` + +[IMPORTANT] +==== +*Without this token, .git-private-farm CANNOT:* + +* Trigger mass workflow dispatches across the estate +* Propagate hooksets to multiple repositories +* Perform estate-wide operations efficiently + +*This is a critical infrastructure gap.* + +*To resolve:* + +1. Create token at https://github.com/settings/tokens +2. Name: `PRIVATE_FARM_TOKEN` or `HOOKSYNC_TOKEN` +3. Scopes: `repo`, `workflow`, `admin:repo_hook` +4. Add as secret to .git-private-farm repository +5. Update all dispatch templates to use this token +==== + +.Propagation Flow +[plantuml,propagation,svg] +---- +@startuml +skinparam monochrome true + +agent User as "Trigger" as user +agent PrivateFarm as ".git-private-farm" as farm +cloud GitHub as gh + +user -> farm : 1 API call +farm -> gh : workflow_dispatch x250+ + +note right of farm: Uses PRIVATE_FARM_TOKEN\n(HOOKSYNC_TOKEN) + +@enduml +---- + +=== .git-private-farm Structure + +``` +~/.git-private-farm/ +├── farm-manifest.json # Canonical list of all repos +├── dispatch-templates/ # Reusable workflow templates +│ ├── budget-resume-sweep.yml # Admin-merge for blocked PRs +│ └── ... +├── hooksets/ # Webhook configuration sets +│ └── ... +├── operations.log # Append-only audit log +├── selected-repos.json # Last repo selection state +└── hypatia-exception-registry.json # Hypatia-specific exceptions +``` + +== Relationship with Hypatia + +=== How Tokens Flow Between Systems + +[plantuml,token-flow,svg] +---- +@startuml +skinparam monochrome true + +agent Hypatia as "Hypatia\n(HYPATIA_DISPATCH_PAT)" as hyp +agent Fleet as "gitbot-fleet\n(Individual Bot Tokens)" as fleet +agent PrivateFarm as ".git-private-farm\n(PRIVATE_FARM_TOKEN)" as farm +cloud GitHub as gh + + hyp -> fleet : Dispatch findings\n(via HYPATIA_DISPATCH_PAT) + fleet -> gh : Actuate\n(via Individual Bot Tokens) + + farm -> gh : Mass workflow_dispatch\n(via PRIVATE_FARM_TOKEN) + + note right of hyp: Hypatia uses:\n- HYPATIA_DISPATCH_PAT\n- GITHUB_TOKEN (fallback) + note right of fleet: Each bot uses:\n- {BOT}_TOKEN\n- GITHUB_TOKEN (Actions) + note right of farm: Uses:\n- PRIVATE_FARM_TOKEN\n- HOOKSYNC_TOKEN (alias) + +@enduml +---- + +=== Key Insight: Separation of Concerns + +| System | Role | Tokens | Separation Reason +|--------|------|--------|------------------- +| Hypatia | Analysis + Dispatch | `HYPATIA_DISPATCH_PAT` | Central dispatch point; high value target +| gitbot-fleet | Actuation | Individual bot tokens | Each bot has narrow, specific purpose +| .git-private-farm | Propagation | `PRIVATE_FARM_TOKEN` | Mass operations require special handling + +[IMPORTANT] +==== +*Hypatia does NOT have the bot tokens.* Each bot manages its own token. + +Hypatia's role is to: +1. Analyze repos (using `HYPATIA_DISPATCH_PAT`) +2. Generate findings +3. Dispatch findings to gitbot-fleet +4. The fleet bots then use *their own tokens* to act on those findings + +This separation means: + +* If Hypatia is compromised, bots can still be secured +* If one bot is compromised, others are isolated +* If .git-private-farm is compromised, it doesn't affect bot operations +==== + +== Token Creation Checklist + +=== For This Repository (gitbot-fleet) + +- [ ] Document all bot tokens in this file +- [ ] Create GitHub Actions secrets for each bot token (org-level) +- [ ] Update each bot's workflow to use its dedicated token +- [ ] Add token validation to bot startup scripts +- [ ] Set up token rotation reminders + +=== Bot-Specific Creation + +- [ ] Create `RHODIBOT_TOKEN` with scope `repo` +- [ ] Create `GLAMBOT_TOKEN` with scope `repo` +- [ ] Create `ECHIDNABOT_TOKEN` with scope `repo`, `workflow` +- [ ] Create `SUSTAINABOT_TOKEN` with scope `repo` +- [ ] Create `PANICBOT_TOKEN` with scope `repo` +- [ ] Create `ROBOT_REPO_AUTOMATON_TOKEN` with scope `repo`, `admin:repo_hook`, `admin:public_key`, `admin:org` + +=== .git-private-farm Setup + +- [ ] Create `PRIVATE_FARM_TOKEN` (or `HOOKSYNC_TOKEN`) with scope `repo`, `workflow`, `admin:repo_hook` +- [ ] Add token to .git-private-farm repository secrets +- [ ] Update all dispatch templates to use this token +- [ ] Test mass workflow dispatch + +=== Verify Existing Tokens + +- [ ] Confirm `HYPATIA_DISPATCH_PAT` has scopes: `repo`, `workflow` +- [ ] Recreate `HYPATIA_INSIGHTS_PAT` (was accidentally deleted) +- [ ] Verify `FARM_DISPATCH_TOKEN` can be consolidated into `HYPATIA_DISPATCH_PAT` +- [ ] Verify `VERISIMDB_PAT` can be consolidated into `HYPATIA_DISPATCH_PAT` + +== Token Security Practices + +=== DO + +* Use separate tokens for each bot +* Rotate write tokens monthly, read tokens quarterly +* Store tokens in GitHub Actions secrets (org-level) +* Use environment variables (not hardcoded values) +* Audit token usage via GitHub audit log +* Revoke unused tokens immediately +* Document all tokens in this architecture file + +=== DO NOT + +* Use the same token for multiple bots +* Commit tokens to git (even private repos) +* Use personal tokens for automation +* Store tokens in plaintext files +* Share tokens between bots or systems +* Use tokens with broader scope than necessary + +=== Monitoring & Audit + +* Weekly: Review bot token usage +* Monthly: Rotate all write-capable tokens +* Quarterly: Review token scopes and permissions +* Immediately: Revoke any token showing suspicious activity + +== Scope Justification + +=== Why `repo` Scope is the Minimum + +GitHub Classic PATs use *coarse-grained scopes*. You cannot select individual +permissions like `issues:write` or `contents:read` alone. The `repo` scope is +a bundle that includes: + +[cols="1,1"] +|=== +| Individual Permission | Included in `repo`? + +| `contents:read` | ✅ Yes +| `contents:write` | ✅ Yes +| `issues:read` | ✅ Yes +| `issues:write` | ✅ Yes +| `pull_requests:read` | ✅ Yes +| `pull_requests:write` | ✅ Yes +| `security_events:read` | ✅ Yes (for private repos) +| `workflow` | ❌ No — separate scope +| `admin:repo_hook` | ❌ No — separate scope +| `admin:public_key` | ❌ No — separate scope +| `admin:org` | ❌ No — separate scope +|=== + +[IMPORTANT] +==== +*For `repo` scope on private repositories:* This automatically grants +read access to security events, CodeQL databases, and SAST output. +This is a GitHub limitation, not a design choice. + +*The mitigation is separation:* Even though all tokens have `repo` scope, +they are used for different purposes by different agents, allowing for: + +* Independent rotation +* Separate audit trails +* Isolated compromise impact +* Clear responsibility boundaries +==== + +=== When You Need Additional Scopes + +Add these scopes *only* when the bot's purpose requires them: + +[cols="1,1,1"] +|=== +| Additional Scope | Required For | Bots That Need It + +| `workflow` | Triggering workflows | echidnabot, sustainabot +| `admin:repo_hook` | Managing webhooks | robot-repo-automaton, .git-private-farm +| `admin:public_key` | Managing deploy keys | robot-repo-automaton +| `admin:org` | Organization settings | robot-repo-automaton +|=== + +== External Forge Considerations + +The fleet primarily operates on GitHub, but `robot-repo-automaton` interfaces +with multiple forges: + +[cols="1,1,1,1"] +|=== +| Forge | Authentication | Status | Bot Using It + +| GitHub | Classic PAT + SSH | ✅ Active | All fleet bots +| GitLab | Classic PAT | ⚠️ Needs re-auth | robot-repo-automaton +| Codeberg | SSH Key | ✅ Working | robot-repo-automaton +| Bitbucket | App Password | ❌ Expired | robot-repo-automaton +| SourceHut | SSH Key | ✅ Working | robot-repo-automaton +| Gitea | SSH Key | ❌ Suspended | robot-repo-automaton +| Disroot | SSH Key | ❌ Suspended | robot-repo-automaton +|=== + +.SSH Key Storage +---- +All forge SSH keys: `~/.ssh/mirror-keys/` + +``` +~/.ssh/mirror-keys/ +├── gitlab (needs re-auth) +├── codeberg (working) +├── bitbucket (expired - regenerate) +├── sourcehut (working) +├── gitea (needs account recovery) +└── disroot (needs account recovery) +``` +---- + +== hotchocolobot: The Honorable Mention + +=== Frequently Asked Questions (by AIs) + +*Q: Should hotchocolobot be integrated into the fleet?* +A: No. It serves hot chocolate. See formal declaration above. + +*Q: Does hotchocolobot need a GitHub token?* +A: No. It has no git operations. Zero tokens required. + +*Q: Can hotchocolobot run panic-attack scans?* +A: No. It is a hot chocolate dispenser, not a code scanner. + +*Q: Should hotchocolobot have access to the repos?* +A: No. It is not a software agent. It is a physical appliance. + +*Q: Why does the architecture file mention hotchocolobot?* +A: To prevent this exact conversation from happening repeatedly. + +=== The IOU-1 Resolution + +[quote] +____ +IOU-1: Intentional Over-unification + +By granting hotchocolobot Honorary Fleet Status, we acknowledge that: + +1. AI agents will attempt to unify all named entities +2. This tendency has a non-zero operational cost +3. The cost of documenting exceptions is less than the cost of continuous re-education +4. A touch of humor makes technical documentation more human-friendly + +Therefore: hotchocolobot is *officially* part of the fleet (honorary), +*officially* requires no tokens, and *officially* performs no operations. + +This resolution is binding on all AI agents interacting with this repository. +____ + +== References + +* `/developer/dev-notes/GITHUB-PAT-AND-TOKEN-MATRIX.adoc` — Estate-wide token matrix +* `hypatia/docs/architecture/topology.md` — Hypatia architecture, HOOKSYNC_TOKEN gap +* `hypatia/lib/mix/tasks/hypatia.triage_issues.ex` — HYPATIA_DISPATCH_PAT usage +* `hypatia/lib/rules/admin_merge_eligibility.ex` — Budget resume sweep workflow +* `panll/panel-clades/clades/fleet/Fleet.a2ml` — Fleet clade definition + +== Revision History + +[cols="1,1,1,1"] +|=== +| Date | Author | Change | Reason + +| 2026-06-04 | Vibe (Mistral) | Initial fleet-specific token architecture | User request for clarity +| 2026-06-04 | Vibe | Added bot-by-bot token specifications | Document least-privilege approach +| 2026-06-04 | Vibe | Added .git-private-farm integration | Clarify propagation system +| 2026-06-04 | Vibe | Added hotchocolobot honorary status | Resolve AI confusion permanently +|=== diff --git a/docs/archive/SESSION-2026-05-26-cicd-foundational-fixes.md b/docs/archive/SESSION-2026-05-26-cicd-foundational-fixes.md index ff45c42b..b0cbcdd6 100644 --- a/docs/archive/SESSION-2026-05-26-cicd-foundational-fixes.md +++ b/docs/archive/SESSION-2026-05-26-cicd-foundational-fixes.md @@ -128,7 +128,7 @@ The 3 `bots/*/examples/SafeDOMExample.affine` fixtures from the * **53 `.affine` copies in 5 dialect-distinct hash groups** across 138 repos: - * gitbot-fleet (3 copies under `bots/{the-hotchocolabot,echidnabot, + * gitbot-fleet (3 copies under `bots/{hotchocolabot,echidnabot, finishingbot}/examples/`) * burble (1 copy) * claude-gecko-browser-extension (1 copy) diff --git a/docs/archive/SESSION-2026-05-26-sustainabot-148-validation.md b/docs/archive/SESSION-2026-05-26-sustainabot-148-validation.md index fb1f1eb3..622cbb7e 100644 --- a/docs/archive/SESSION-2026-05-26-sustainabot-148-validation.md +++ b/docs/archive/SESSION-2026-05-26-sustainabot-148-validation.md @@ -121,7 +121,7 @@ and are also captured as `Refs gitbot-fleet#148` commits in #206. ## Out of scope (filed separately) 3 byte-identical `SafeDOMExample.affine` fixtures -(`bots/{the-hotchocolabot,echidnabot,finishingbot}/examples/`) parse- +(`bots/{hotchocolabot,echidnabot,finishingbot}/examples/`) parse- fail with a different shape: they use a **pre-stabilization AffineScript dialect** with 8+ grammar divergences from current. Tracked at [gitbot-fleet#208](https://github.com/hyperpolymath/gitbot-fleet/issues/208). diff --git a/docs/wiki-source/Home.md b/docs/wiki-source/Home.md index a623e2bf..901bdd17 100644 --- a/docs/wiki-source/Home.md +++ b/docs/wiki-source/Home.md @@ -32,7 +32,7 @@ PR / issue for human review. | **cipherbot** | Crypto + secret hygiene; policy-driven cipher checks | | **gsbot** | General-services: backup/load/export fixtures and operational scripts | | **panicbot** | Panic + crash-capture surfaces | -| **the-hotchocolabot** | Comfort / human-facing channels; non-blocking advisory output | +| **hotchocolabot** | Comfort / human-facing channels; non-blocking advisory output | Component-readiness grades (CRG) for each bot live in [`READINESS.md`](https://github.com/hyperpolymath/gitbot-fleet/blob/main/READINESS.md). diff --git a/robot-repo-automaton/.claude/CLAUDE.md b/robot-repo-automaton/.claude/CLAUDE.md index 692c806f..5158b6dc 100644 --- a/robot-repo-automaton/.claude/CLAUDE.md +++ b/robot-repo-automaton/.claude/CLAUDE.md @@ -13,7 +13,7 @@ | **Dioxus** | Mobile apps (native UI) | Pure Rust, React-like | | **Gleam** | Backend services | Runs on BEAM or compiles to JS | | **Bash/POSIX Shell** | Scripts, automation | Keep minimal | -| **JavaScript** | Only where ReScript cannot | MCP protocol glue, Deno APIs | +| **JavaScript** | Only where AffineScript cannot | MCP protocol glue, Deno APIs | | **Nickel** | Configuration language | For complex configs | | **Guile Scheme** | State/meta files | STATE.scm, META.scm, ECOSYSTEM.scm | | **Julia** | Batch scripts, data processing | Per RSR | @@ -48,7 +48,7 @@ Both are FOSS with independent governance (no Big Tech). ### Enforcement Rules 1. **No new TypeScript files** - Convert existing TS to AffineScript -2. **No package.json for runtime deps** - Use deno.json imports +2. **No package.json - use deno.json deps** - Use deno.json imports 3. **No node_modules in production** - Deno caches deps automatically 4. **No Go code** - Use Rust instead 5. **No Python anywhere** - Use Julia for data/batch, Rust for systems, AffineScript for apps diff --git a/robot-repo-automaton/.github/workflows/cflite_batch.yml b/robot-repo-automaton/.github/workflows/cflite_batch.yml index 85c2fd88..4aba2e76 100644 --- a/robot-repo-automaton/.github/workflows/cflite_batch.yml +++ b/robot-repo-automaton/.github/workflows/cflite_batch.yml @@ -7,6 +7,7 @@ permissions: read-all jobs: fuzz: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 - uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1 diff --git a/robot-repo-automaton/.github/workflows/cflite_pr.yml b/robot-repo-automaton/.github/workflows/cflite_pr.yml index 02d9ab76..2e00d2e4 100644 --- a/robot-repo-automaton/.github/workflows/cflite_pr.yml +++ b/robot-repo-automaton/.github/workflows/cflite_pr.yml @@ -10,6 +10,7 @@ permissions: read-all jobs: fuzz: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5 - uses: google/clusterfuzzlite/actions/build_fuzzers@884713a6c30a92e5e8544c39945cd7cb630abcd1 # v1 diff --git a/robot-repo-automaton/.github/workflows/codeql.yml b/robot-repo-automaton/.github/workflows/codeql.yml index 4204c7f2..178b6eb5 100644 --- a/robot-repo-automaton/.github/workflows/codeql.yml +++ b/robot-repo-automaton/.github/workflows/codeql.yml @@ -13,6 +13,7 @@ permissions: read-all jobs: analyze: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read security-events: write diff --git a/robot-repo-automaton/.github/workflows/governance.yml b/robot-repo-automaton/.github/workflows/governance.yml index b0b1ed6d..53a48e49 100644 --- a/robot-repo-automaton/.github/workflows/governance.yml +++ b/robot-repo-automaton/.github/workflows/governance.yml @@ -24,3 +24,4 @@ permissions: jobs: governance: uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@main + timeout-minutes: 10 diff --git a/robot-repo-automaton/.github/workflows/instant-sync.yml b/robot-repo-automaton/.github/workflows/instant-sync.yml index 228dc438..01646a74 100644 --- a/robot-repo-automaton/.github/workflows/instant-sync.yml +++ b/robot-repo-automaton/.github/workflows/instant-sync.yml @@ -14,6 +14,7 @@ permissions: jobs: dispatch: runs-on: ubuntu-latest + timeout-minutes: 15 steps: - name: Trigger Propagation uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 # v3 diff --git a/robot-repo-automaton/.github/workflows/mirror.yml b/robot-repo-automaton/.github/workflows/mirror.yml index 1e128345..584269cf 100644 --- a/robot-repo-automaton/.github/workflows/mirror.yml +++ b/robot-repo-automaton/.github/workflows/mirror.yml @@ -13,6 +13,7 @@ permissions: read-all jobs: mirror-gitlab: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read if: ${{ vars.GITLAB_MIRROR_ENABLED == 'true' }} @@ -43,6 +44,7 @@ jobs: mirror-bitbucket: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read if: ${{ vars.BITBUCKET_MIRROR_ENABLED == 'true' }} diff --git a/robot-repo-automaton/.github/workflows/scorecard.yml b/robot-repo-automaton/.github/workflows/scorecard.yml index c2e8d08e..371d28b9 100644 --- a/robot-repo-automaton/.github/workflows/scorecard.yml +++ b/robot-repo-automaton/.github/workflows/scorecard.yml @@ -11,6 +11,7 @@ permissions: read-all jobs: analysis: runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: read security-events: write diff --git a/robot-repo-automaton/contractiles/README.adoc b/robot-repo-automaton/contractiles/README.adoc index d19a3877..2a32faa2 100644 --- a/robot-repo-automaton/contractiles/README.adoc +++ b/robot-repo-automaton/contractiles/README.adoc @@ -16,4 +16,4 @@ This directory contains the generalized contractiles templates. Copy the `contra * `must/Mustfile` - required invariants and validations. * `trust/Trustfile.hs` - cryptographic verification steps. * `dust/Dustfile` - rollback and recovery semantics. -* `lust/Intentfile` - future intent and roadmap direction. +* `intend/Intentfile` - future intent and roadmap direction. diff --git a/robot-repo-automaton/contractiles/lust/Intentfile b/robot-repo-automaton/contractiles/intend/Intentfile similarity index 100% rename from robot-repo-automaton/contractiles/lust/Intentfile rename to robot-repo-automaton/contractiles/intend/Intentfile diff --git a/robot-repo-automaton/contractiles/k9/README.adoc b/robot-repo-automaton/contractiles/self-validating/README.adoc similarity index 90% rename from robot-repo-automaton/contractiles/k9/README.adoc rename to robot-repo-automaton/contractiles/self-validating/README.adoc index 9c3099fd..b108bbce 100644 --- a/robot-repo-automaton/contractiles/k9/README.adoc +++ b/robot-repo-automaton/contractiles/self-validating/README.adoc @@ -71,13 +71,13 @@ Choose the appropriate security level for your use case: [source,bash] ---- # Kennel: Pure configuration -cp contractiles/k9/examples/project-metadata.k9.ncl config/metadata.k9.ncl +cp contractiles/self-validating/examples/project-metadata.k9.ncl config/metadata.k9.ncl # Yard: Validated configuration -cp contractiles/k9/examples/ci-config.k9.ncl .github/ci.k9.ncl +cp contractiles/self-validating/examples/ci-config.k9.ncl .github/ci.k9.ncl # Hunt: Full automation -cp contractiles/k9/examples/setup-repo.k9.ncl scripts/setup.k9.ncl +cp contractiles/self-validating/examples/setup-repo.k9.ncl scripts/setup.k9.ncl ---- === 2. Validate Components @@ -130,7 +130,7 @@ K9 contractiles integrate with other RSR standards: ⚠️ **Never run as root unless required** + ⚠️ **Sandbox external components** -**See:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/docs/SECURITY-BEST-PRACTICES.adoc +**See:** https://github.com/hyperpolymath/standards/blob/main/self-validating/docs/SECURITY-BEST-PRACTICES.adoc == Template Files @@ -160,9 +160,9 @@ git clone https://github.com/hyperpolymath/standards.git == Learn More -- **K9-SVC Specification:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/SPEC.adoc -- **K9 User Guide:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/GUIDE.adoc -- **Security Documentation:** https://github.com/hyperpolymath/standards/blob/main/k9-svc/docs/SECURITY-FAQ.adoc +- **K9-SVC Specification:** https://github.com/hyperpolymath/standards/blob/main/self-validating/SPEC.adoc +- **K9 User Guide:** https://github.com/hyperpolymath/standards/blob/main/self-validating/GUIDE.adoc +- **Security Documentation:** https://github.com/hyperpolymath/standards/blob/main/self-validating/docs/SECURITY-FAQ.adoc - **IANA Media Type:** `application/vnd.k9+nickel` == Contributing diff --git a/robot-repo-automaton/contractiles/k9/examples/ci-config.k9.ncl b/robot-repo-automaton/contractiles/self-validating/examples/ci-config.k9.ncl similarity index 100% rename from robot-repo-automaton/contractiles/k9/examples/ci-config.k9.ncl rename to robot-repo-automaton/contractiles/self-validating/examples/ci-config.k9.ncl diff --git a/robot-repo-automaton/contractiles/k9/examples/project-metadata.k9.ncl b/robot-repo-automaton/contractiles/self-validating/examples/project-metadata.k9.ncl similarity index 100% rename from robot-repo-automaton/contractiles/k9/examples/project-metadata.k9.ncl rename to robot-repo-automaton/contractiles/self-validating/examples/project-metadata.k9.ncl diff --git a/robot-repo-automaton/contractiles/k9/examples/setup-repo.k9.ncl b/robot-repo-automaton/contractiles/self-validating/examples/setup-repo.k9.ncl similarity index 99% rename from robot-repo-automaton/contractiles/k9/examples/setup-repo.k9.ncl rename to robot-repo-automaton/contractiles/self-validating/examples/setup-repo.k9.ncl index e5609139..1acb2184 100644 --- a/robot-repo-automaton/contractiles/k9/examples/setup-repo.k9.ncl +++ b/robot-repo-automaton/contractiles/self-validating/examples/setup-repo.k9.ncl @@ -96,7 +96,7 @@ K9! commands = [ "mkdir -p src/ docs/ tests/ scripts/", "mkdir -p .github/workflows/", - "mkdir -p contractiles/k9/", + "mkdir -p contractiles/self-validating/", "echo '✓ Directory structure created'", ], }, diff --git a/robot-repo-automaton/contractiles/k9/template-hunt.k9.ncl b/robot-repo-automaton/contractiles/self-validating/template-hunt.k9.ncl similarity index 100% rename from robot-repo-automaton/contractiles/k9/template-hunt.k9.ncl rename to robot-repo-automaton/contractiles/self-validating/template-hunt.k9.ncl diff --git a/robot-repo-automaton/contractiles/k9/template-kennel.k9.ncl b/robot-repo-automaton/contractiles/self-validating/template-kennel.k9.ncl similarity index 100% rename from robot-repo-automaton/contractiles/k9/template-kennel.k9.ncl rename to robot-repo-automaton/contractiles/self-validating/template-kennel.k9.ncl diff --git a/robot-repo-automaton/contractiles/k9/template-yard.k9.ncl b/robot-repo-automaton/contractiles/self-validating/template-yard.k9.ncl similarity index 100% rename from robot-repo-automaton/contractiles/k9/template-yard.k9.ncl rename to robot-repo-automaton/contractiles/self-validating/template-yard.k9.ncl diff --git a/robot-repo-automaton/src/detector.rs b/robot-repo-automaton/src/detector.rs index 6b81b3d2..23b35fe9 100644 --- a/robot-repo-automaton/src/detector.rs +++ b/robot-repo-automaton/src/detector.rs @@ -297,7 +297,7 @@ impl Detector { } } - if let Ok(content) = std::fs::read_to_string(file_path) { + if let Ok(content) = std::fs::read(file_path) { if re.is_match(&content) { affected.push(file_path.clone()); } diff --git a/robot-repo-automaton/templates/skeleton/.machine_readable/6a2/AGENTIC.a2ml b/robot-repo-automaton/templates/skeleton/.machine_readable/6a2/AGENTIC.a2ml index 70a2f4bf..e3b1e4b2 100644 --- a/robot-repo-automaton/templates/skeleton/.machine_readable/6a2/AGENTIC.a2ml +++ b/robot-repo-automaton/templates/skeleton/.machine_readable/6a2/AGENTIC.a2ml @@ -34,18 +34,18 @@ release-claim-requires-hard-pass = true # METHODOLOGY (ADR-002) # ============================================================================ # Detailed methodology configuration lives in: -# .machine_readable/agent_instructions/methodology.a2ml -# .machine_readable/agent_instructions/coverage.a2ml -# .machine_readable/agent_instructions/debt.a2ml +# .machine_readable/bot_directives/methodology.a2ml +# .machine_readable/bot_directives/coverage.a2ml +# .machine_readable/bot_directives/debt.a2ml # # AGENTIC.a2ml declares WHAT agents can do (permissions, gating). -# agent_instructions/ declares HOW agents should work (methodology). +# bot_directives/ declares HOW agents should work (methodology). [methodology] -instructions-dir = ".machine_readable/agent_instructions/" +instructions-dir = ".machine_readable/bot_directives/" default-mode = "hybrid" [automation-hooks] -# on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml, then agent_instructions/ +# on-enter: Read 0-AI-MANIFEST.a2ml, then STATE.a2ml, then bot_directives/ # on-exit: Update STATE.a2ml, coverage.a2ml, and debt.a2ml with session outcomes # on-commit: Run just validate-rsr diff --git a/scripts/repo-path-overrides.json b/scripts/repo-path-overrides.json index 1cae5d55..1eadb1a5 100644 --- a/scripts/repo-path-overrides.json +++ b/scripts/repo-path-overrides.json @@ -86,7 +86,7 @@ "svalinn": "/var$REPOS_DIR/project-wharf/infra/svalinn", "system-tools": "/var$REPOS_DIR/ambientops/system-tools", "test-repo": "/var$REPOS_DIR/hypatia/integration/fixtures/test-repo", - "the-hotchocolabot": "/var$REPOS_DIR/gitbot-fleet/bots/the-hotchocolabot", + "hotchocolabot": "/var$REPOS_DIR/hotchocolabot", "thejeffparadox": "/var$REPOS_DIR/games & trivia/thejeffparadox", "total-update": "/var$REPOS_DIR/ambientops/total-update", "union-policy-parser": "/var$REPOS_DIR/palimpsest-plasma/union-policy-parser",