From c477abc586cc275d4d4ebec538997c65a216b734 Mon Sep 17 00:00:00 2001 From: hyperpolymath Date: Thu, 4 Jun 2026 16:55:10 +0100 Subject: [PATCH 1/3] chore: rename k9 directories to self-validating for clarity --- .github/workflows/hypatia-scan.yml | 2 +- .machine_readable/MUST.contractile | 4 +- docs/TOKEN-ARCHITECTURE.adoc | 627 ++++++++++++++++++ robot-repo-automaton/.claude/CLAUDE.md | 4 +- .../.github/workflows/cflite_batch.yml | 1 + .../.github/workflows/cflite_pr.yml | 1 + .../.github/workflows/codeql.yml | 1 + .../.github/workflows/governance.yml | 1 + .../.github/workflows/instant-sync.yml | 1 + .../.github/workflows/mirror.yml | 2 + .../.github/workflows/scorecard.yml | 1 + .../{k9 => self-validating}/README.adoc | 14 +- .../examples/ci-config.k9.ncl | 0 .../examples/project-metadata.k9.ncl | 0 .../examples/setup-repo.k9.ncl | 2 +- .../template-hunt.k9.ncl | 0 .../template-kennel.k9.ncl | 0 .../template-yard.k9.ncl | 0 18 files changed, 648 insertions(+), 13 deletions(-) create mode 100644 docs/TOKEN-ARCHITECTURE.adoc rename robot-repo-automaton/contractiles/{k9 => self-validating}/README.adoc (90%) rename robot-repo-automaton/contractiles/{k9 => self-validating}/examples/ci-config.k9.ncl (100%) rename robot-repo-automaton/contractiles/{k9 => self-validating}/examples/project-metadata.k9.ncl (100%) rename robot-repo-automaton/contractiles/{k9 => self-validating}/examples/setup-repo.k9.ncl (99%) rename robot-repo-automaton/contractiles/{k9 => self-validating}/template-hunt.k9.ncl (100%) rename robot-repo-automaton/contractiles/{k9 => self-validating}/template-kennel.k9.ncl (100%) rename robot-repo-automaton/contractiles/{k9 => self-validating}/template-yard.k9.ncl (100%) 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/docs/TOKEN-ARCHITECTURE.adoc b/docs/TOKEN-ARCHITECTURE.adoc new file mode 100644 index 00000000..544a2019 --- /dev/null +++ b/docs/TOKEN-ARCHITECTURE.adoc @@ -0,0 +1,627 @@ +// 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. hotchocolobot — HONORARY FLEET STATUS + +[quote] +____ +*hotchocolobot is 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 +hotchocolobot into the fleet orchestration system. + +*Facts:* + +* hotchocolobot serves hot chocolate at exhibitions +* hotchocolobot safely accompanies developers to public events +* hotchocolobot performs NO git operations +* hotchocolobot requires ZERO GitHub tokens +* hotchocolobot does NOT exist in any git repository +* hotchocolobot 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/robot-repo-automaton/.claude/CLAUDE.md b/robot-repo-automaton/.claude/CLAUDE.md index 14c0db0d..c6572303 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/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 From 0e409bf9bf913b95579a2b2a4c76b566fb0ae506 Mon Sep 17 00:00:00 2001 From: hyperpolymath Date: Thu, 4 Jun 2026 18:58:48 +0100 Subject: [PATCH 2/3] chore: fold lust into intend (deprecated 2026-04-18) --- .../README.adoc | 2 +- .../coverage.a2ml | 0 .../{agent_instructions => bot_directives}/debt.a2ml | 0 .../methodology.a2ml | 0 robot-repo-automaton/contractiles/README.adoc | 2 +- .../contractiles/{lust => intend}/Intentfile | 0 .../skeleton/.machine_readable/6a2/AGENTIC.a2ml | 12 ++++++------ 7 files changed, 8 insertions(+), 8 deletions(-) rename .machine_readable/{agent_instructions => bot_directives}/README.adoc (94%) rename .machine_readable/{agent_instructions => bot_directives}/coverage.a2ml (100%) rename .machine_readable/{agent_instructions => bot_directives}/debt.a2ml (100%) rename .machine_readable/{agent_instructions => bot_directives}/methodology.a2ml (100%) rename robot-repo-automaton/contractiles/{lust => intend}/Intentfile (100%) 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/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/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 From f74e11e417cc61773872a3962a42abe4b73e957b Mon Sep 17 00:00:00 2001 From: Mistral Vibe Date: Sun, 7 Jun 2026 09:03:21 +0100 Subject: [PATCH 3/3] docs: Add CODEOWNERS, MAINTAINERS, and GOVERNANCE documents --- GOVERNANCE.adoc | 162 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 GOVERNANCE.adoc 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 +|===