From e5322f138753d9102f8bf344d3c0747c529e6979 Mon Sep 17 00:00:00 2001 From: hummbl-dev Date: Thu, 14 May 2026 05:02:57 -0400 Subject: [PATCH 1/4] fix(docs): mark base120 corpus path as missing --- docs/REPO_HEALTH.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/REPO_HEALTH.md b/docs/REPO_HEALTH.md index f335c83..85b788f 100644 --- a/docs/REPO_HEALTH.md +++ b/docs/REPO_HEALTH.md @@ -5,20 +5,21 @@ - **Repository**: `hummbl-dev/base120` - **Canonical URL**: `https://github.com/hummbl-dev/base120` - **Owner**: HUMMBL Team -- **Stewardship scope**: Canonical Base120 registry, validation corpus, governance specs, and v1 reference artifacts. +- **Stewardship scope**: Canonical Base120 registry, corpus contract documentation, governance specs, and v1 reference artifacts. ## Lifecycle - **Status**: Active public repository with the Python v1 package retired. - **Default branch**: `main`. - **Release posture**: v1 Python runtime code has been removed. Registry, corpus, governance, documentation, and CI hardening changes may continue through pull requests. -- **Archive trigger**: Archive only if the canonical Base120 registry and validation corpus move to another declared source of truth. +- **Archive trigger**: Archive only if the canonical Base120 registry and corpus contract move to another declared source of truth. ## Source Of Truth - `Base120_Canonical_Model_Registry.yaml` is the canonical model registry. - `registries/` contains registry data files that mirror or support the canonical model set. -- `tests/corpus/` is the golden validation corpus for implementations and mirrors. +- `docs/corpus-contract.md` and `mirrors/CONFORMANCE_CONTRACT.md` document the intended corpus contract for implementations and mirrors. +- `tests/corpus/` is referenced by existing governance and mirror documentation, but it is not present in the current tree. Treat restoration or relocation of the executable corpus as an operational gap, not current source of truth. - `GOVERNANCE.md` and `docs/governance-decision-tree.md` define change classes and review expectations. - `docs/contract-units.md` defines contract unit structure and examples. @@ -37,7 +38,7 @@ Expected CI coverage: - `.github/workflows/ci.yml` runs tests on Python 3.11 and 3.12. - `.github/workflows/base120.yml` runs mirror-guard checks and tests on Python 3.13. -- `.github/workflows/guardrails.yml` runs corpus validation on Python 3.13. +- `.github/workflows/guardrails.yml` runs guardrail validation on Python 3.13. - `.github/workflows/mirror-conformance.yml` is a reusable mirror-conformance workflow for downstream implementations. ## Branch Protection Expectation @@ -53,6 +54,7 @@ Expected CI coverage: - GitHub branch protection is tracked centrally in `hummbl-dev/hummbl-dev#18`; do not overclaim required checks until that audit is updated. - The Python v1 package is retired, so validation should focus on registry, corpus, and mirror-conformance integrity rather than runtime feature growth. +- `tests/corpus/` is referenced by governance and mirror-conformance docs but absent from the current tree; restore or relocate the executable corpus before treating it as validation source of truth. ## Fleet Scan Classification @@ -60,6 +62,6 @@ Future fleet scans can classify this repository as: - **Lifecycle**: active, v1 runtime retired - **Visibility**: public -- **Primary function**: canonical Base120 registry and validation corpus +- **Primary function**: canonical Base120 registry and corpus contract documentation; executable corpus restoration pending - **Validation entrypoint**: `pytest` - **Primary metadata owner**: HUMMBL Team From 9dee2a42d744b5899768fbf888829ab8d9c38e48 Mon Sep 17 00:00:00 2001 From: hummbl-dev Date: Wed, 20 May 2026 22:49:36 -0400 Subject: [PATCH 2/4] docs: add repo health metadata --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index c7ab697..4d562a0 100644 --- a/README.md +++ b/README.md @@ -119,3 +119,7 @@ Apache 2.0 -- see [LICENSE](LICENSE). --- Built by [HUMMBL LLC](https://hummbl.io). Base120 powers the cognitive layer behind multi-agent coordination at scale. + +## Repository Health + +See [docs/REPO_HEALTH.md](docs/REPO_HEALTH.md) for validation and branch-protection expectations. From 97df5fa8a99cc47000f34cd954cea20eb900c55f Mon Sep 17 00:00:00 2001 From: hummbl-dev Date: Sun, 24 May 2026 10:45:07 -0400 Subject: [PATCH 3/4] fix(docs): align base120 sdk contract --- README.md | 115 +++++++++++++++++----------- docs/REPO_HEALTH.md | 17 ++-- docs/contract-units.md | 9 +++ docs/observability.md | 9 ++- tests/test_docs_current_contract.py | 66 ++++++++++++++++ 5 files changed, 164 insertions(+), 52 deletions(-) create mode 100644 tests/test_docs_current_contract.py diff --git a/README.md b/README.md index 4d562a0..11d3cda 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ # Base120 -> **v1 Python package RETIRED (2026-04-14).** The Python code has been removed. -> The canonical registry (`Base120_Canonical_Model_Registry.yaml`) and data files -> (`registries/`) remain here as source of truth. The v2 SDK is in development. +> **Lifecycle note (2026-05-24).** The original v1 validator runtime was +> retired on 2026-04-14. This repository now contains the active stdlib-only +> Python v2 SDK (`base120` 2.0.0.dev0) for operator lookup, prompting, MCP +> serving, and VERUM-aligned ledger records. +> The canonical v1 registry (`Base120_Canonical_Model_Registry.yaml`) and data +> files (`registries/`) remain here as source of truth. > > **FM taxonomy (FM1–FM30) migrated to:** -> [`hummbl-governance`](https://github.com/hummbl-research/hummbl-governance) v0.4.0 +> [`hummbl-governance`](https://github.com/hummbl-research/hummbl-governance) > — `from hummbl_governance.errors import FailureMode, HummblError` > -> **MCP server (TypeScript, live):** -> [`mcp-server`](https://github.com/hummbl-research/mcp-server) — all 120 operators served via MCP +> **MCP server:** use the Python `base120-mcp` entry point from this package, +> or the external [`mcp-server`](https://github.com/hummbl-research/mcp-server) +> mirror when a TypeScript server is required. [![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue)](LICENSE) @@ -17,73 +21,98 @@ ## Quick Example -Apply a model to decompose a problem: +Apply an operator, generate a prompt, and persist a governance-readable record: ```python -from base120.validators.validate import validate_artifact - -# FM42: Separation of Concerns -- does this component have a single responsibility? -artifact = { - "id": "auth-service-review", - "domain": "core", - "class": "architecture", - "instance": "auth-svc", - "models": ["FM42"] # Separation of Concerns -} -errors = validate_artifact(artifact, schema, mappings, err_registry) -# [] -- valid artifact, model applies cleanly +from base120 import Engine, Ledger + +engine = Engine() + +operator = engine.get("P6") +print(operator.name) # Point-of-View Anchoring + +prompt = engine.prompt("P6", "How should we price the certification tier?") +result = engine.record( + "P6", + "How should we price the certification tier?", + "Anchor the offer to the compliance officer's risk budget.", + 0.85, +) + +ledger = Ledger("base120-ledger.jsonl") +ledger.append(result.to_tuple()) ``` -Each of the 120 models is a named, versioned reasoning primitive with a defined domain, failure graph, and validation rules. +Each of the 120 operators is a named, versioned reasoning primitive with a +defined transformation family and deterministic package representation. ## Features -- **120 mental models** across 6 cognitive domains (core, systems, security, governance, operations, meta) -- **6 cognitive transformations** -- deterministic operations that compose models into chains -- **CLI validation** -- `base120 validate-contract` checks governance artifacts against the frozen spec -- **Observability layer** -- opt-in structured JSON events for production monitoring -- **MCP integration** -- serve models to AI agents via [mcp-server](https://github.com/hummbl-dev/mcp-server) -- **Golden corpus** -- all implementations must match the canonical test corpus in `tests/corpus` +- **120 reasoning operators** across 6 transformation families +- **Stdlib-only Python SDK** -- no third-party runtime dependencies +- **CLI tooling** -- `base120 list`, `base120 get`, `base120 prompt`, and `base120 families` +- **Append-only ledger** -- persist operator applications as VERUM-aligned JSONL tuples +- **MCP integration** -- serve operators to AI agents with the `base120-mcp` entry point +- **Canonical registry and corpus docs** -- frozen v1 reference artifacts remain in-tree -## Install +## Install From Source ```bash -pip install base120 - -# Or from source git clone https://github.com/hummbl-dev/base120.git && cd base120 pip install -e ".[test]" ``` +The package name is `base120`, but this repository should not claim PyPI +availability until a published package exists. + ## CLI ```bash -# Validate a contract unit (schema, failure graph, version metadata) -base120 validate-contract path/to/contract.json +# List all operators +base120 list + +# Inspect one operator +base120 get P6 + +# Generate an operator-specific prompt for a problem +base120 prompt P6 "How should we price the certification tier?" + +# List canonical operator families +base120 families ``` -See [`docs/contract-units.md`](docs/contract-units.md) for contract unit format and examples. +The historical contract-unit validator spec is archived in +[`docs/contract-units.md`](docs/contract-units.md); the current v2 SDK does not +ship `base120 validate-contract`. -## Observability +## Ledger -Opt-in structured events for production deployments: +Persist operator applications as JSONL tuples: ```python -from base120.observability import create_event_sink +from base120 import Engine, Ledger + +engine = Engine() +result = engine.record("DE1", "Reduce release risk.", "Split blockers by owner.", 0.9) -event_sink = create_event_sink() # logs to stdout -errors = validate_artifact(artifact, schema, mappings, err_registry, - event_sink=event_sink) -# Emits: {"event_type": "validator_result", "result": "success", ...} +ledger = Ledger() +ledger.append(result.to_tuple()) +high_drift = ledger.cut(0.5) ``` -Omitting `event_sink` preserves original v1.0.0 behavior with zero overhead. Full spec: [`docs/observability.md`](docs/observability.md). +The archived v1 validator observability contract remains in +[`docs/observability.md`](docs/observability.md), but the current v2 SDK does +not expose `base120.observability`. ## Authority Statement -This repository is the **authoritative reference implementation** for Base120 v1.0.0. All other language implementations are semantic mirrors and MUST conform exactly to the outputs defined here. +This repository is the **authoritative source** for the Base120 v1 registry, +reference artifacts, and current Python v2 SDK. Other language +implementations should conform to the frozen registry and corpus artifacts +defined here. The `2.0.0.dev0` Python SDK API remains pre-release until a +non-dev package version is published. -### v1.0.x Policy +### v1 Artifact Policy - **Permitted:** Security fixes, CI hardening, documentation, corpus additions - **Prohibited:** Schema changes, registry modifications, breaking changes diff --git a/docs/REPO_HEALTH.md b/docs/REPO_HEALTH.md index 85b788f..442d002 100644 --- a/docs/REPO_HEALTH.md +++ b/docs/REPO_HEALTH.md @@ -5,13 +5,13 @@ - **Repository**: `hummbl-dev/base120` - **Canonical URL**: `https://github.com/hummbl-dev/base120` - **Owner**: HUMMBL Team -- **Stewardship scope**: Canonical Base120 registry, corpus contract documentation, governance specs, and v1 reference artifacts. +- **Stewardship scope**: Canonical Base120 registry, corpus contract documentation, governance specs, v1 reference artifacts, and the active Python v2 SDK. ## Lifecycle -- **Status**: Active public repository with the Python v1 package retired. +- **Status**: Active public repository with frozen v1 registry/corpus artifacts and an active Python v2 SDK (`base120` 2.0.0.dev0). - **Default branch**: `main`. -- **Release posture**: v1 Python runtime code has been removed. Registry, corpus, governance, documentation, and CI hardening changes may continue through pull requests. +- **Release posture**: the v1 validator runtime is retired. The current Python package exposes operator lookup, prompting, MCP serving, and VERUM-aligned ledger records; do not claim v1 validator CLI/API support unless it is reintroduced and tested. - **Archive trigger**: Archive only if the canonical Base120 registry and corpus contract move to another declared source of truth. ## Source Of Truth @@ -21,7 +21,8 @@ - `docs/corpus-contract.md` and `mirrors/CONFORMANCE_CONTRACT.md` document the intended corpus contract for implementations and mirrors. - `tests/corpus/` is referenced by existing governance and mirror documentation, but it is not present in the current tree. Treat restoration or relocation of the executable corpus as an operational gap, not current source of truth. - `GOVERNANCE.md` and `docs/governance-decision-tree.md` define change classes and review expectations. -- `docs/contract-units.md` defines contract unit structure and examples. +- `docs/contract-units.md` defines archived v1 contract unit structure and examples; the current v2 SDK does not ship the `base120 validate-contract` command. +- `base120/` contains the active v2 SDK package. ## Validation Contract @@ -32,6 +33,7 @@ python -m pip install --upgrade pip pip install -e ".[test]" pytest python -m pytest tests/ -v +python -m pip wheel . --no-deps -w dist-smoke ``` Expected CI coverage: @@ -53,15 +55,16 @@ Expected CI coverage: ## Known Operational Gaps - GitHub branch protection is tracked centrally in `hummbl-dev/hummbl-dev#18`; do not overclaim required checks until that audit is updated. -- The Python v1 package is retired, so validation should focus on registry, corpus, and mirror-conformance integrity rather than runtime feature growth. +- The Python v1 validator package is retired, while the v2 SDK is active pre-release. Keep README/API docs aligned with the actual `Engine`, `Ledger`, CLI, and MCP entry points. - `tests/corpus/` is referenced by governance and mirror-conformance docs but absent from the current tree; restore or relocate the executable corpus before treating it as validation source of truth. +- `docs/contract-units.md` and `docs/observability.md` are archived v1 validator contracts, not current v2 SDK API promises. ## Fleet Scan Classification Future fleet scans can classify this repository as: -- **Lifecycle**: active, v1 runtime retired +- **Lifecycle**: active, v1 validator runtime retired, v2 SDK pre-release active - **Visibility**: public -- **Primary function**: canonical Base120 registry and corpus contract documentation; executable corpus restoration pending +- **Primary function**: canonical Base120 registry and corpus contract documentation; active stdlib-only Python SDK; executable corpus restoration pending - **Validation entrypoint**: `pytest` - **Primary metadata owner**: HUMMBL Team diff --git a/docs/contract-units.md b/docs/contract-units.md index 1146a64..fd64659 100644 --- a/docs/contract-units.md +++ b/docs/contract-units.md @@ -1,5 +1,11 @@ # Base120 Contract Units +> **Status (2026-05-24): archived v1 validator contract.** The current +> `base120` v2 SDK does not implement the `base120 validate-contract` command. +> The CLI examples below document the retired validator surface and must not be +> treated as current package behavior unless validator support is reintroduced +> with tests. + ## Overview Contract units are the **core governance artifacts** in Base120. They serve as **executable specifications** that define: @@ -25,6 +31,9 @@ Contract units are **independent governance artifacts** but MUST align with Base ## CLI Usage +This section is historical. For current SDK commands, use `base120 list`, +`base120 get`, `base120 prompt`, and `base120 families`. + ### Installation Install Base120 with pip: diff --git a/docs/observability.md b/docs/observability.md index e836e63..0da435f 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -1,9 +1,14 @@ # Base120 Observability Contract -**Version:** v1.0.0 -**Status:** Governance-guaranteed (Indicated work) +**Version:** v1.0.0 +**Status:** Archived v1 validator contract **Failure Mode Addressed:** FM19 (Observability Failure) +> **Current SDK note (2026-05-24):** the `base120` v2 SDK does not expose +> `base120.validators` or `base120.observability`. This document preserves the +> retired v1 validator observability contract; it is not a current package API +> promise. + --- ## Purpose diff --git a/tests/test_docs_current_contract.py b/tests/test_docs_current_contract.py new file mode 100644 index 0000000..afdc206 --- /dev/null +++ b/tests/test_docs_current_contract.py @@ -0,0 +1,66 @@ +"""Public documentation checks for the current Base120 package surface.""" + +from __future__ import annotations + +from pathlib import Path +import tomllib + +import base120 + + +ROOT = Path(__file__).resolve().parents[1] + + +def _read(relative: str) -> str: + return (ROOT / relative).read_text(encoding="utf-8") + + +def _flat(text: str) -> str: + return " ".join(text.split()) + + +def test_readme_advertises_current_sdk_surface() -> None: + readme = _read("README.md") + flat_readme = _flat(readme) + + unsupported_claims = [ + "Python code has been removed", + "base120 validate-contract path/to", + "from base120.validators", + "from base120.observability", + "pip install base120", + ] + for claim in unsupported_claims: + assert claim not in readme + + assert "does not ship `base120 validate-contract`" in flat_readme + assert "does not expose `base120.observability`" in flat_readme + assert "from base120 import Engine, Ledger" in readme + assert "base120 list" in readme + assert "base120 get P6" in readme + assert "base120 prompt P6" in readme + assert "base120 families" in readme + assert "should not claim PyPI availability" in flat_readme + + +def test_archived_validator_docs_are_marked_as_archived() -> None: + archived_docs = [ + "docs/contract-units.md", + "docs/observability.md", + ] + + for relative in archived_docs: + text = _read(relative) + lower_text = text.lower() + assert "archived v1 validator contract" in lower_text + assert "current" in lower_text + assert "v2 sdk does not" in lower_text + + +def test_documented_sdk_version_matches_package_metadata() -> None: + pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8")) + version = pyproject["project"]["version"] + + assert base120.__version__ == version + assert version in _read("README.md") + assert version in _read("docs/REPO_HEALTH.md") From 0f9ae8c3ab19163873eb2be4e94684563997a703 Mon Sep 17 00:00:00 2001 From: hummbl-dev Date: Mon, 25 May 2026 12:39:19 -0400 Subject: [PATCH 4/4] fix(docs): remove stale pypi install claim --- docs/contract-units.md | 14 +++++++++----- tests/test_docs_current_contract.py | 11 +++++++++++ 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/contract-units.md b/docs/contract-units.md index fd64659..5aadd2d 100644 --- a/docs/contract-units.md +++ b/docs/contract-units.md @@ -34,12 +34,16 @@ Contract units are **independent governance artifacts** but MUST align with Base This section is historical. For current SDK commands, use `base120 list`, `base120 get`, `base120 prompt`, and `base120 families`. -### Installation +### Historical Installation -Install Base120 with pip: +The retired validator was once installed as a package. Do not use this snippet +as current release guidance; the active v2 SDK is installed from this source +tree until a package is published. ```bash -pip install base120 +git clone https://github.com/hummbl-dev/base120.git +cd base120 +python -m pip install -e ".[test]" ``` ### Validating a Contract Unit @@ -348,8 +352,8 @@ jobs: uses: actions/setup-python@v4 with: python-version: '3.12' - - name: Install Base120 - run: pip install base120 + - name: Install Base120 from source + run: python -m pip install -e ".[test]" - name: Validate Contract run: base120 validate-contract contracts/service-contract.json ``` diff --git a/tests/test_docs_current_contract.py b/tests/test_docs_current_contract.py index afdc206..f00127c 100644 --- a/tests/test_docs_current_contract.py +++ b/tests/test_docs_current_contract.py @@ -57,6 +57,17 @@ def test_archived_validator_docs_are_marked_as_archived() -> None: assert "v2 sdk does not" in lower_text +def test_current_docs_do_not_claim_pypi_install() -> None: + docs_to_check = [ + "README.md", + "docs/contract-units.md", + "docs/observability.md", + ] + + for relative in docs_to_check: + assert "pip install base120" not in _read(relative) + + def test_documented_sdk_version_matches_package_metadata() -> None: pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8")) version = pyproject["project"]["version"]