diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3d70a5..2c5dc2f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to HUMMBL -Thank you for your interest in contributing to HUMMBL projects. +Thank you for your interest in contributing to HUMMBL projects. This is the org-wide contributing guide for all repos in `hummbl-dev` that don't ship their own `CONTRIBUTING.md`. ## Guidelines @@ -17,6 +17,59 @@ Thank you for your interest in contributing to HUMMBL projects. 4. Run the test suite (`python -m pytest tests/ -v`) 5. Open a pull request against `main` +## Choosing where to contribute + +| Contributor Type | Best Entry | +|---|---| +| Agent engineer | agent-runtime-governance, agent-handoffs, agent-control-plane-patterns | +| Governance/policy | governance-as-code, policy-as-code, compliance-as-code | +| Package/release | packages, homebrew-tap, scoop-bucket, winget-manifests, nix | +| Evidence/research | claim-evidence-ledger, research-source-packets, ai-source-verification | +| Tool builder | hummbl-governance, base120, arbiter, mcp-server | + +New to the org? Start at [hummbl-dev/hummbl-dev START_HERE.md](https://github.com/hummbl-dev/hummbl-dev/blob/main/START_HERE.md). + +## Repo maturity + +HUMMBL repos move through four maturity levels: + +- **seed** — Early idea. No v0.1 boundary yet. Structure may change without notice. Not ready for outside contributors. +- **v0.1-packet** — Repo has a v0.1 boundary, prior art, schema, fixtures, and a receipt. Open for docs/schema/fixture contributions and agent-safe work. +- **active** — Repo ships runnable code and is under continuous development. May or may not be canonical. +- **canonical** — Audited, stable, and referenced as HUMMBL canon. Changes require operator authority and receipts. + +Promotion from v0.1-packet to canonical requires an audit, an operator-authority decision, and a receipt. + +## What agents can and cannot do + +**Agents CAN:** +- Work on docs, schema, and fixture contributions in v0.1-packet repos. +- Create PRs with receipts for governance-bearing changes. +- Close issues that have the required evidence attached. + +**Agents CANNOT:** +- Make canonical decisions. +- Promote repos to canonical. +- Close operator-authority issues. +- Approve Phase 1 deployments. + +If an issue carries the `operator-authority` or `decision-required` label, stop and hand off to a human. + +## Operator authority required + +The following decisions are pending operator authority. Agents must not auto-complete them: + +- **homebrew-hummbl#3** — pending operator decision +- **mintlify-docs#3** — pending operator decision + +## Receipts + +Every PR that touches governance-bearing content must include a receipt. A receipt records what changed, why, what was verified, and the authority under which the change was made. PRs without a receipt on governance-bearing changes will be blocked until one is added. Use the `receipt:missing` / `receipt:complete` labels to track this. + +## Labels + +Label meanings are defined in [docs/FLEET_LABELS.md](docs/FLEET_LABELS.md). Use labels to route work, signal agent safety, and mark authority requirements. Key labels for contributors: `agent-safe`, `agent-hold`, `operator-authority`, `decision-required`, `evidence-needed`, `v0.1-packet`, `canonical-candidate`. + ## Questions Contact: reuben@hummbl.io diff --git a/docs/FLEET_LABELS.md b/docs/FLEET_LABELS.md index bb62ef2..1990d1b 100644 --- a/docs/FLEET_LABELS.md +++ b/docs/FLEET_LABELS.md @@ -30,6 +30,27 @@ These labels are organization-level conventions for HUMMBL repositories. Individ | `receipt:missing` | Work cannot close or merge until an expected receipt is added. | | `receipt:complete` | Required audit receipt is present. | | `risk:high` | Extra reviewer caution or owner involvement is required. | +| `v0.1-packet` | Repo has v0.1 boundary, prior art, schema, fixtures, and receipt. | +| `canonical-candidate` | Proposed for HUMMBL canon, under audit. | +| `operator-authority` | Issue requires operator decision, agents must not auto-complete. | +| `agent-safe` | Issue is safe for autonomous agent execution. | +| `agent-hold` | Issue is blocked for agent execution. | +| `decision-required` | Issue requires human decision before proceeding. | +| `evidence-needed` | Issue needs evidence/receipts before closure. | +| `implementation-bearing` | Repo ships runnable code. | +| `pattern-reference` | Repo is docs/schema/fixture only, no runtime code. | +| `external-collab-ready` | Repo is ready for outside contributor participation. | + +## Maturity labels + +These labels track where a repo sits in the HUMMBL maturity pipeline: + +- **`v0.1-packet`** — Repo has a v0.1 boundary, prior art, schema, fixtures, and a receipt. Open for docs/schema/fixture contributions and agent-safe work. Not yet canonical. +- **`canonical-candidate`** — Repo has been proposed for HUMMBL canon and is under audit. Promotion requires an operator-authority decision and a receipt. +- **`agent-safe`** — Issue is safe for autonomous agent execution. Agents may pick it up, complete it, and open PRs without human pre-approval. +- **`agent-hold`** — Issue is blocked for agent execution. Agents must not start work until the hold is cleared. +- **`operator-authority`** — Issue requires an operator decision. Agents must not auto-complete, close, or merge these issues. +- **`decision-required`** — Issue requires a human decision before any further work proceeds. Distinct from `operator-authority` in that it may not carry governance authority, but still needs a human call. ## Usage policy diff --git a/profile/README.md b/profile/README.md index 9ded4c6..b5fd43a 100644 --- a/profile/README.md +++ b/profile/README.md @@ -2,15 +2,25 @@ **HUMMBL is an open-source governance framework for multi-agent AI systems.** It provides delegation tokens, circuit breakers, kill switches, and append-only audit logging as Python-stdlib-only primitives -- no third-party runtime dependencies. Built for teams running production AI agent fleets who need deterministic safety controls, not probabilistic guardrails. -`1970 collected tests` | `120 mental models` | `0 runtime deps` | `Python 3.11-3.14` | `pip install hummbl-governance` | `Production since 2024` +`2027 collected tests` | `120 mental models` | `0 runtime deps` | `Python 3.11-3.14` | `pip install hummbl-governance` | `Production since 2024` + +--- + +## Where to start + +New to the org? Read **[START_HERE.md](https://github.com/hummbl-dev/hummbl-dev/blob/main/START_HERE.md)** in `hummbl-dev/hummbl-dev` for the fleet index, contributor entry points, and current operator-authority decisions. + +If you are contributing for the first time, read the org-wide **[CONTRIBUTING.md](https://github.com/hummbl-dev/.github/blob/main/CONTRIBUTING.md)** for the contributor type table, agent permissions, and receipt requirements. --- ## Projects +### Canonical / active + | Project | What problem it solves | | |---------|----------------------|---| -| **[hummbl-governance](https://github.com/hummbl-dev/hummbl-governance)** | Enforces agent permissions, cost budgets, and kill-switch authority in Python with 1970 collected tests and zero runtime dependencies. `pip install hummbl-governance` | [![PyPI](https://img.shields.io/pypi/v/hummbl-governance)](https://pypi.org/project/hummbl-governance/) [![Python](https://img.shields.io/pypi/pyversions/hummbl-governance)](https://pypi.org/project/hummbl-governance/) [![License](https://img.shields.io/github/license/hummbl-dev/hummbl-governance)](https://github.com/hummbl-dev/hummbl-governance/blob/main/LICENSE) | +| **[hummbl-governance](https://github.com/hummbl-dev/hummbl-governance)** | Enforces agent permissions, cost budgets, and kill-switch authority in Python with 2027 collected tests and zero runtime dependencies. `pip install hummbl-governance` | [![PyPI](https://img.shields.io/pypi/v/hummbl-governance)](https://pypi.org/project/hummbl-governance/) [![Python](https://img.shields.io/pypi/pyversions/hummbl-governance)](https://pypi.org/project/hummbl-governance/) [![License](https://img.shields.io/github/license/hummbl-dev/hummbl-governance)](https://github.com/hummbl-dev/hummbl-governance/blob/main/LICENSE) | | **[base120](https://github.com/hummbl-dev/base120)** | Gives AI agents 120 validated mental models for structured reasoning with operator algebra and contract validation CLI. | [![License](https://img.shields.io/github/license/hummbl-dev/base120)](https://github.com/hummbl-dev/base120/blob/main/LICENSE) | | **[mcp-server](https://github.com/hummbl-dev/mcp-server)** | Exposes Base120 frameworks to Claude, ChatGPT, and other LLMs via Model Context Protocol. | [![License](https://img.shields.io/github/license/hummbl-dev/mcp-server)](https://github.com/hummbl-dev/mcp-server/blob/main/LICENSE) | | **[hummbl-agent](https://github.com/hummbl-dev/hummbl-agent)** | Provides registry-first deterministic agent lifecycle management. | [![License](https://img.shields.io/github/license/hummbl-dev/hummbl-agent)](https://github.com/hummbl-dev/hummbl-agent/blob/main/LICENSE) | @@ -18,13 +28,36 @@ | **[hummbl-skills](https://github.com/hummbl-dev/hummbl-skills)** | HUMMBL Agent Skills — canonical skill definitions, CI-validated SKILL.md files, skill creation templates, and cross-agent skill export tooling. | [![License](https://img.shields.io/github/license/hummbl-dev/hummbl-skills)](https://github.com/hummbl-dev/hummbl-skills/blob/main/LICENSE) | | **hummbl-transparency** *(private repository)* | HUMMBL AI Transparency Registry — structured, versioned, evidence-backed vendor prompt auditing, model behavior documentation, and system prompt change tracking. | Private | | **[governed-compression](https://github.com/hummbl-dev/governed-compression)** | Governed vector and KV-cache compression research — CPU reference, reproducible benchmarks, tuple-based experiment logging. | [![License](https://img.shields.io/github/license/hummbl-dev/governed-compression)](https://github.com/hummbl-dev/governed-compression/blob/main/LICENSE) | -| **[evidence-gate](https://github.com/hummbl-dev/evidence-gate)** | Pre-publish source-verification rule library for HUMMBL governance content. Stdlib-only TOML rules + fixture harness. | [![License](https://img.shields.io/github/license/hummbl-dev/evidence-gate)](https://github.com/hummbl-dev/evidence-gate/blob/main/LICENSE) | | **[hummbl-bibliography](https://github.com/hummbl-dev/hummbl-bibliography)** | HUMMBL Bibliography — provenance corpus, BibTeX citations, and position papers for Base120, HCC, BKI, and AI governance research. | [![License](https://img.shields.io/github/license/hummbl-dev/hummbl-bibliography)](https://github.com/hummbl-dev/hummbl-bibliography/blob/main/LICENSE) | +### v0.1-packet fleet + +These repos have a v0.1 boundary, prior art, schema, fixtures, and a receipt. They are open for docs/schema/fixture contributions and agent-safe work. + +| Category | Repos | +|----------|-------| +| Agent engineering | [agent-runtime-governance](https://github.com/hummbl-dev/agent-runtime-governance), [agent-handoffs](https://github.com/hummbl-dev/agent-handoffs), [agent-control-plane-patterns](https://github.com/hummbl-dev/agent-control-plane-patterns) | +| Governance / policy | [governance-as-code](https://github.com/hummbl-dev/governance-as-code), [policy-as-code](https://github.com/hummbl-dev/policy-as-code), [compliance-as-code](https://github.com/hummbl-dev/compliance-as-code) | +| Package / release | [packages](https://github.com/hummbl-dev/packages), [homebrew-tap](https://github.com/hummbl-dev/homebrew-tap), [scoop-bucket](https://github.com/hummbl-dev/scoop-bucket), [winget-manifests](https://github.com/hummbl-dev/winget-manifests), [nix](https://github.com/hummbl-dev/nix) | +| Evidence / research | [claim-evidence-ledger](https://github.com/hummbl-dev/claim-evidence-ledger), [research-source-packets](https://github.com/hummbl-dev/research-source-packets), [ai-source-verification](https://github.com/hummbl-dev/ai-source-verification) | +| Tool builder | [hummbl-governance](https://github.com/hummbl-dev/hummbl-governance), [base120](https://github.com/hummbl-dev/base120), [arbiter](https://github.com/hummbl-dev/arbiter), [mcp-server](https://github.com/hummbl-dev/mcp-server) | + Unlike LangChain and CrewAI (which focus on agent orchestration) or Microsoft's agent toolkits (which target Azure-hosted workflows), HUMMBL is a governance-only layer that works with any orchestrator and has zero vendor lock-in. --- +## Repo maturity + +HUMMBL repos move through three maturity levels: + +- **seed** — Early idea. No v0.1 boundary yet. Structure may change without notice. Not ready for outside contributors. +- **v0.1-packet** — Repo has a v0.1 boundary, prior art, schema, fixtures, and a receipt. Open for docs/schema/fixture contributions and agent-safe work. Not yet canonical. +- **canonical** — Audited, stable, and referenced as HUMMBL canon. Changes require operator authority and receipts. `hummbl-governance`, `base120`, and `mcp-server` are canonical. + +A repo promoted from v0.1-packet to canonical requires an audit, an operator-authority decision, and a receipt. See `docs/FLEET_LABELS.md` for the `canonical-candidate` and `v0.1-packet` labels. + +--- + ## FAQ **Q: What is HUMMBL?** @@ -36,8 +69,11 @@ A: Run `pip install hummbl-governance`. Requires Python 3.11 or newer. No additi **Q: What is Base120?** A: Base120 is a library of 120 validated mental models organized into 6 domains (Perspective, Inversion, Composition, Decomposition, Recursion, Systems). It includes an operator algebra for composing models and a contract validation CLI. AI agents use Base120 for structured reasoning via the HUMMBL MCP server. +**Q: What is a v0.1-packet repo?** +A: A v0.1-packet repo has a defined v0.1 boundary, prior art references, a schema, fixtures, and a receipt. It is the maturity level between seed and canonical. v0.1-packet repos are open for docs, schema, and fixture contributions, and for agent-safe work, but are not yet HUMMBL canon. Promotion to canonical requires an audit and an operator-authority decision. + **Q: How is HUMMBL different from LangChain or CrewAI?** -A: LangChain and CrewAI are agent orchestration frameworks. HUMMBL is a governance layer that sits alongside any orchestrator. It answers "what is this agent allowed to do?" not "how do I chain agents together." HUMMBL has zero runtime dependencies, uses deterministic controls (not probabilistic), and is tested with 1970 collected tests across the published libraries, covering unit tests for individual components, integration tests for multi-component orchestration, and property-based tests that verify determinism and canonical-form invariants. +A: LangChain and CrewAI are agent orchestration frameworks. HUMMBL is a governance layer that sits alongside any orchestrator. It answers "what is this agent allowed to do?" not "how do I chain agents together." HUMMBL has zero runtime dependencies, uses deterministic controls (not probabilistic), and is tested with 2027 collected tests across the published libraries, covering unit tests for individual components, integration tests for multi-component orchestration, and property-based tests that verify determinism and canonical-form invariants. ---