measuring-autonomy 1.1.0__tar.gz

measuring_autonomy-1.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, emmanuel-a-otchere
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

measuring_autonomy-1.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: measuring-autonomy
+Version: 1.1.0
+Summary: Measure and manage autonomy: safe-level scoring, Autonomy Ledger health checks, and framework tooling.
+Author: Emmanuel A. Otchere
+License: MIT
+Project-URL: Homepage, https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy
+Project-URL: Changelog, https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy/blob/main/CHANGELOG.md
+Keywords: autonomy,governance,maturity-model,management,org-design
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=5.4
+Dynamic: license-file
+
+# Measuring and Managing Autonomy
+
+Autonomy from a business and systems point of view can be challenging to
+manage. This project defines a framework by which managing and measuring
+autonomy can be designed and implemented.
+
+Most organizations manage autonomy implicitly — it emerges from trust, tenure,
+and accidents of structure, and is therefore felt but not measured, expanded
+but never designed, and revoked arbitrarily. This framework makes autonomy an
+**explicit, designed, measurable property** of the organization.
+
+## The framework in one diagram
+
+```mermaid
+flowchart LR
+    A[Design<br>decision + blast radius] --> B[Grant<br>autonomy contract]
+    B --> C[Measure<br>ledger + telemetry]
+    C --> D[Manage<br>expand / contract / re-shape]
+    D -->|re-grant, next horizon| B
+```
+
+## What's here
+
+| Document | Purpose |
+|---|---|
+| [Framework](docs/framework.md) | Definitions, the three axes, the five levels (L0–L4), autonomy contracts |
+| [Maturity model](docs/maturity-model.md) | Six dimensions × five levels grid, scoring rules, the Autonomy Ledger |
+| [Assessment](docs/assessment.md) | The questionnaire and scoring procedure — the practical instrument |
+| [Governance loop](docs/governance-loop.md) | Grant → Instrument → Observe → Review, with cadence and anti-patterns |
+| [Positioning](docs/positioning.md) | Related work, lineage, open questions, BibTeX |
+| [Worked example](examples/README.md) | One team, scored end to end, producing a governance move |
+| [AI agents as units](docs/agents-as-units.md) | First-pass extension: scoring agent units with the same instrument |
+| [Ledger format](docs/ledger-format.md) | Machine-readable Autonomy Ledger (YAML v1) + health checks |
+| [Contract template](docs/contract-template.md) | Autonomy contract + review agenda, ready to copy |
+| [Versioning](docs/versioning.md) | Ruleset/ledger versioning policy — how assessments stay comparable |
+| [Changelog](CHANGELOG.md) | Every change, classified by comparability impact |
+
+## Install
+
+**No Python needed** — standalone binaries for macOS, Linux, and Windows are
+attached to each [GitHub Release](https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy/releases):
+download `autonomy-score-<os>-<arch>` and `ledger-health-<os>-<arch>`, mark
+them executable, run.
+
+**With Python 3.9+** (installs the `autonomy-score` and `ledger-health`
+commands):
+
+```bash
+pipx install measuring-autonomy    # or: pip install measuring-autonomy
+```
+
+**From a clone**, the zero-install form keeps working with no packaging step:
+`python3 tools/autonomy_score.py ...` (the `tools/` scripts are shims over
+`src/measuring_autonomy/`).
+
+## Quick start: score a team
+
+```bash
+python3 tools/autonomy_score.py 1 3 2 2 1 1 --current 1
+```
+
+Scores are D1 clarity, D2 capability, D3 guardrails, D4 telemetry,
+D5 transparency, D6 accountability (0–4 each). The tool applies the
+weakest-link rule — `min(guardrails, telemetry, accountability)` — and
+outputs the safe grant level and recommended move.
+
+```bash
+python3 tools/autonomy_score.py --self-test   # verify the scoring rules
+```
+
+Track granted autonomy in a machine-readable **Autonomy Ledger** (v1 YAML
+format, [`examples/ledger.yaml`](examples/ledger.yaml)) and check its health:
+
+```bash
+python3 tools/ledger_health.py examples/ledger.yaml   # requires PyYAML (pip install pyyaml)
+```
+
+## Try it without a terminal
+
+A dependency-free web version of the assessment lives in [`site/`](site/)
+(and is published to GitHub Pages when enabled — repo **Settings → Pages →
+Source: GitHub Actions**). Open `site/index.html` locally, tick the items
+with evidence, and print the scorecard.
+
+## The three questions
+
+1. **Design** — What autonomy should this unit have, and why? →
+   [contracts](docs/framework.md#5-autonomy-contracts)
+2. **Measurement** — How much autonomy exists, and how well is it used? →
+   [maturity model](docs/maturity-model.md) + [assessment](docs/assessment.md)
+3. **Management** — When should autonomy expand, contract, or re-shape? →
+   [governance loop](docs/governance-loop.md)
+
+## Roadmap
+
+See [docs/roadmap.md](docs/roadmap.md). Current status: **v0.1 draft** — the
+written framework, maturity model, and assessment instrument are complete;
+next up are validation against real teams and optional tooling.
+
+## Contributing
+
+Feedback, corrections, and real-world applications are very welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). Use the issue templates to report
+framework feedback or submit a case study.
+
+## License
+
+[MIT](LICENSE)

measuring_autonomy-1.1.0/README.md

@@ -0,0 +1,108 @@
+# Measuring and Managing Autonomy
+
+Autonomy from a business and systems point of view can be challenging to
+manage. This project defines a framework by which managing and measuring
+autonomy can be designed and implemented.
+
+Most organizations manage autonomy implicitly — it emerges from trust, tenure,
+and accidents of structure, and is therefore felt but not measured, expanded
+but never designed, and revoked arbitrarily. This framework makes autonomy an
+**explicit, designed, measurable property** of the organization.
+
+## The framework in one diagram
+
+```mermaid
+flowchart LR
+    A[Design<br>decision + blast radius] --> B[Grant<br>autonomy contract]
+    B --> C[Measure<br>ledger + telemetry]
+    C --> D[Manage<br>expand / contract / re-shape]
+    D -->|re-grant, next horizon| B
+```
+
+## What's here
+
+| Document | Purpose |
+|---|---|
+| [Framework](docs/framework.md) | Definitions, the three axes, the five levels (L0–L4), autonomy contracts |
+| [Maturity model](docs/maturity-model.md) | Six dimensions × five levels grid, scoring rules, the Autonomy Ledger |
+| [Assessment](docs/assessment.md) | The questionnaire and scoring procedure — the practical instrument |
+| [Governance loop](docs/governance-loop.md) | Grant → Instrument → Observe → Review, with cadence and anti-patterns |
+| [Positioning](docs/positioning.md) | Related work, lineage, open questions, BibTeX |
+| [Worked example](examples/README.md) | One team, scored end to end, producing a governance move |
+| [AI agents as units](docs/agents-as-units.md) | First-pass extension: scoring agent units with the same instrument |
+| [Ledger format](docs/ledger-format.md) | Machine-readable Autonomy Ledger (YAML v1) + health checks |
+| [Contract template](docs/contract-template.md) | Autonomy contract + review agenda, ready to copy |
+| [Versioning](docs/versioning.md) | Ruleset/ledger versioning policy — how assessments stay comparable |
+| [Changelog](CHANGELOG.md) | Every change, classified by comparability impact |
+
+## Install
+
+**No Python needed** — standalone binaries for macOS, Linux, and Windows are
+attached to each [GitHub Release](https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy/releases):
+download `autonomy-score-<os>-<arch>` and `ledger-health-<os>-<arch>`, mark
+them executable, run.
+
+**With Python 3.9+** (installs the `autonomy-score` and `ledger-health`
+commands):
+
+```bash
+pipx install measuring-autonomy    # or: pip install measuring-autonomy
+```
+
+**From a clone**, the zero-install form keeps working with no packaging step:
+`python3 tools/autonomy_score.py ...` (the `tools/` scripts are shims over
+`src/measuring_autonomy/`).
+
+## Quick start: score a team
+
+```bash
+python3 tools/autonomy_score.py 1 3 2 2 1 1 --current 1
+```
+
+Scores are D1 clarity, D2 capability, D3 guardrails, D4 telemetry,
+D5 transparency, D6 accountability (0–4 each). The tool applies the
+weakest-link rule — `min(guardrails, telemetry, accountability)` — and
+outputs the safe grant level and recommended move.
+
+```bash
+python3 tools/autonomy_score.py --self-test   # verify the scoring rules
+```
+
+Track granted autonomy in a machine-readable **Autonomy Ledger** (v1 YAML
+format, [`examples/ledger.yaml`](examples/ledger.yaml)) and check its health:
+
+```bash
+python3 tools/ledger_health.py examples/ledger.yaml   # requires PyYAML (pip install pyyaml)
+```
+
+## Try it without a terminal
+
+A dependency-free web version of the assessment lives in [`site/`](site/)
+(and is published to GitHub Pages when enabled — repo **Settings → Pages →
+Source: GitHub Actions**). Open `site/index.html` locally, tick the items
+with evidence, and print the scorecard.
+
+## The three questions
+
+1. **Design** — What autonomy should this unit have, and why? →
+   [contracts](docs/framework.md#5-autonomy-contracts)
+2. **Measurement** — How much autonomy exists, and how well is it used? →
+   [maturity model](docs/maturity-model.md) + [assessment](docs/assessment.md)
+3. **Management** — When should autonomy expand, contract, or re-shape? →
+   [governance loop](docs/governance-loop.md)
+
+## Roadmap
+
+See [docs/roadmap.md](docs/roadmap.md). Current status: **v0.1 draft** — the
+written framework, maturity model, and assessment instrument are complete;
+next up are validation against real teams and optional tooling.
+
+## Contributing
+
+Feedback, corrections, and real-world applications are very welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). Use the issue templates to report
+framework feedback or submit a case study.
+
+## License
+
+[MIT](LICENSE)

measuring_autonomy-1.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "measuring-autonomy"
+version = "1.1.0"
+description = "Measure and manage autonomy: safe-level scoring, Autonomy Ledger health checks, and framework tooling."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Emmanuel A. Otchere" }]
+keywords = ["autonomy", "governance", "maturity-model", "management", "org-design"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = ["pyyaml>=5.4"]
+
+[project.urls]
+Homepage = "https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy"
+Changelog = "https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy/blob/main/CHANGELOG.md"
+
+[project.scripts]
+autonomy-score = "measuring_autonomy.score:main"
+ledger-health = "measuring_autonomy.ledger:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

measuring_autonomy-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

measuring_autonomy-1.1.0/src/measuring_autonomy/__init__.py

@@ -0,0 +1,33 @@
+"""Measuring & Managing Autonomy toolkit.
+
+Scoring engine and Autonomy Ledger health checker for the framework
+(https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy).
+
+The ledger module is imported lazily by its console command only, so
+`import measuring_autonomy` stays dependency-free; PyYAML is required
+solely by `ledger-health`.
+"""
+from .score import (
+    DIMENSIONS,
+    WEAKEST_LINK,
+    RULESET_VERSION,
+    assess,
+    gap_analysis,
+    parse_scores,
+    recommended_move,
+    safe_level,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "__version__",
+    "DIMENSIONS",
+    "RULESET_VERSION",
+    "WEAKEST_LINK",
+    "assess",
+    "gap_analysis",
+    "parse_scores",
+    "recommended_move",
+    "safe_level",
+]

measuring_autonomy-1.1.0/src/measuring_autonomy/ledger.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Autonomy Ledger health checker for the Measuring & Managing Autonomy framework.
+
+Validates a ledger (YAML, format described in docs/ledger-format.md) against
+the framework's rules and prints an org-level health report:
+
+  - validity:   schema errors (bad level, missing fields, date inconsistencies)
+  - coverage:   fraction of contracts with all required fields
+  - staleness:  contracts whose last_review is older than their cadence
+  - expiry:     active contracts past their horizon (autonomy with no live review)
+  - guardrails: contracts with empty guardrail/telemetry/trigger lists
+
+Exit code 0 = healthy ledger; 1 = findings; 2 = unreadable/invalid file.
+
+Usage:
+    ledger-health examples/ledger.yaml
+    ledger-health ledger.yaml --today 2025-12-31
+    ledger-health --self-test
+    python3 tools/ledger_health.py ...   # zero-install form from a checkout
+
+Requires PyYAML (a declared dependency of this package; the zero-install
+form needs `pip install pyyaml`).
+License: MIT (see LICENSE).
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover
+    yaml = None
+
+REQUIRED_LISTS = ("guardrails", "telemetry", "revocation_triggers")
+REQUIRED_FIELDS = (
+    "id",
+    "unit",
+    "domain",
+    "level",
+    "scope",
+    "guardrails",
+    "telemetry",
+    "revocation_triggers",
+    "grantor",
+    "horizon",
+    "last_review",
+)
+STATUSES = ("active", "expired", "revoked", "draft")
+DEFAULT_CADENCE_DAYS = 90
+
+# Ledger format version handled by this tool (docs/versioning.md, docs/ledger-format.md).
+# Ledgers without a top-level `schema:` field are treated as schema 1
+# (backward compatibility with pre-versioning files). A newer schema than
+# supported is a warning, not an error: report on what is understood.
+SUPPORTED_SCHEMA_VERSION = 1
+
+
+def parse_date(value) -> dt.date | None:
+    if isinstance(value, dt.date):
+        return value
+    try:
+        return dt.date.fromisoformat(str(value))
+    except ValueError:
+        return None
+
+
+def check_contract(c: dict, today: dt.date, idx: int) -> tuple[list[str], dict]:
+    """Return (errors, metrics) for one contract. Errors are fatal findings;
+    metrics feed the health report."""
+    errors: list[str] = []
+    label = c.get("id") or f"contract[{idx}]"
+    status = c.get("status", "active")
+
+    # required fields
+    for field in REQUIRED_FIELDS:
+        if field not in c or c[field] in (None, ""):
+            errors.append(f"{label}: missing required field '{field}'")
+    # non-empty lists
+    for field in REQUIRED_LISTS:
+        value = c.get(field)
+        if value is not None and not (isinstance(value, list) and len(value) > 0):
+            errors.append(f"{label}: '{field}' must be a non-empty list")
+    # level
+    if "level" in c and (not isinstance(c["level"], int) or not 0 <= c["level"] <= 4):
+        errors.append(f"{label}: level must be an integer 0..4")
+    # status
+    if status not in STATUSES:
+        errors.append(f"{label}: status must be one of {STATUSES}")
+    # dates
+    horizon = parse_date(c.get("horizon")) if "horizon" in c else None
+    last_review = parse_date(c.get("last_review")) if "last_review" in c else None
+    if "horizon" in c and horizon is None:
+        errors.append(f"{label}: horizon is not an ISO date")
+    if "last_review" in c and last_review is None:
+        errors.append(f"{label}: last_review is not an ISO date")
+    if horizon and last_review and last_review > horizon:
+        errors.append(f"{label}: last_review is after horizon")
+
+    # health metrics (only meaningful for live contracts)
+    cadence = c.get("review_cadence_days", DEFAULT_CADENCE_DAYS)
+    stale = expired = False
+    if status == "active":
+        if last_review and (today - last_review).days > cadence:
+            stale = True
+        if horizon and today > horizon:
+            expired = True
+    metrics = {
+        "id": c.get("id"),
+        "unit": c.get("unit"),
+        "domain": c.get("domain"),
+        "level": c.get("level"),
+        "status": status,
+        "stale": stale,
+        "expired": expired,
+    }
+    return errors, metrics
+
+
+def health_report(ledger: dict, today: dt.date) -> dict:
+    schema = ledger.get("schema", SUPPORTED_SCHEMA_VERSION)
+    if not isinstance(schema, int) or schema < 1:
+        raise ValueError(f"ledger 'schema' must be a positive integer, got {schema!r}")
+    warnings: list[str] = []
+    if schema > SUPPORTED_SCHEMA_VERSION:
+        warnings.append(
+            f"ledger declares schema v{schema}; this tool supports v{SUPPORTED_SCHEMA_VERSION} — "
+            "validating the v1 fields it understands; upgrade the tool for full support"
+        )
+
+    contracts = ledger.get("contracts")
+    if not isinstance(contracts, list):
+        raise ValueError("ledger must contain a 'contracts' list")
+
+    errors: list[str] = []
+    metrics: list[dict] = []
+    ids: set[str] = set()
+    for idx, c in enumerate(contracts):
+        if not isinstance(c, dict):
+            errors.append(f"contract[{idx}]: must be a mapping")
+            continue
+        c_errors, c_metrics = check_contract(c, today, idx)
+        errors += c_errors
+        if c_metrics["id"]:
+            if c_metrics["id"] in ids:
+                errors.append(f"{c_metrics['id']}: duplicate id")
+            ids.add(c_metrics["id"])
+        metrics.append(c_metrics)
+
+    active = [m for m in metrics if m["status"] == "active"]
+    valid = [m for m in metrics if m["id"] and m["status"] in ("active", "draft")]
+    report = {
+        "schema_version": schema,
+        "schema_warnings": warnings,
+        "total_contracts": len(metrics),
+        "active": len(active),
+        "valid": len(valid),
+        "validity_errors": errors,
+        "coverage": round(len(valid) / len(metrics), 2) if metrics else 1.0,
+        "stale_reviews": [m["id"] for m in active if m["stale"]],
+        "expired_horizons": [m["id"] for m in active if m["expired"]],
+        "unhygienic": len(errors),
+        "today": today.isoformat(),
+    }
+    return report
+
+
+def render(report: dict) -> str:
+    lines = ["Autonomy Ledger health", "=" * 40]
+    lines.append(
+        f"Contracts: {report['total_contracts']} total, {report['active']} active"
+    )
+    lines.append(f"Coverage: {int(report['coverage'] * 100)}% valid contracts")
+    lines.append(f"Ledger schema: v{report['schema_version']}")
+    for w in report.get("schema_warnings", []):
+        lines.append(f"warning: {w}")
+    if report["stale_reviews"]:
+        lines.append(f"STALE reviews (past cadence): {', '.join(report['stale_reviews'])}")
+    else:
+        lines.append("Stale reviews: none")
+    if report["expired_horizons"]:
+        lines.append(
+            f"EXPIRED horizons (active past horizon): {', '.join(report['expired_horizons'])}"
+        )
+    else:
+        lines.append("Expired horizons: none")
+    for err in report["validity_errors"]:
+        lines.append(f"error: {err}")
+    verdict = "HEALTHY" if not (report["validity_errors"] or report["stale_reviews"] or report["expired_horizons"]) else "NEEDS ATTENTION"
+    lines.append(f"Verdict: {verdict}")
+    return "\n".join(lines)
+
+
+def _self_test() -> None:
+    good = {
+        "contracts": [
+            {
+                "id": "c1", "unit": "u", "domain": "d", "level": 2, "scope": "s",
+                "guardrails": ["g"], "telemetry": ["t"],
+                "revocation_triggers": ["r"], "grantor": "G",
+                "horizon": "2025-12-31", "last_review": "2025-09-30",
+                "status": "active",
+            }
+        ]
+    }
+    today = dt.date(2025, 10, 1)
+    r = health_report(good, today)
+    assert not r["validity_errors"] and not r["stale_reviews"], r
+    assert r["coverage"] == 1.0
+
+    # staleness: review 200 days ago, cadence 90
+    stale = {"contracts": [dict(good["contracts"][0], last_review="2025-01-01")]}
+    r = health_report(stale, today)
+    assert r["stale_reviews"] == ["c1"], r
+
+    # expiry: active contract past horizon
+    expired = {"contracts": [dict(good["contracts"][0], horizon="2025-09-30", last_review="2025-09-01")]}
+    r = health_report(expired, dt.date(2025, 10, 2))
+    assert r["expired_horizons"] == ["c1"], r
+
+    # schema violations
+    bad = {"contracts": [{"id": "c", "level": 7, "guardrails": [], "status": "weird"}]}
+    r = health_report(bad, today)
+    errs = " ".join(r["validity_errors"])
+    assert "level" in errs and "status" in errs and "guardrails" in errs, r["validity_errors"]
+
+    # duplicate ids
+    dup = {"contracts": [good["contracts"][0], dict(good["contracts"][0])]}
+    r = health_report(dup, today)
+    assert any("duplicate" in e for e in r["validity_errors"]), r["validity_errors"]
+
+    # last_review after horizon
+    inv = {"contracts": [dict(good["contracts"][0], horizon="2025-06-30", last_review="2025-09-30")]}
+    r = health_report(inv, today)
+    assert any("after horizon" in e for e in r["validity_errors"]), r["validity_errors"]
+
+    # schema handling: missing field = schema 1 (backward compatible)
+    r = health_report({"contracts": [good["contracts"][0]]}, today)
+    assert r["schema_version"] == 1 and not r["schema_warnings"], r
+
+    # explicit schema 1 is accepted
+    r = health_report({"schema": 1, "contracts": [good["contracts"][0]]}, today)
+    assert r["schema_version"] == 1 and not r["schema_warnings"], r
+
+    # future schema: warns but still validates (forward compatibility)
+    r = health_report({"schema": 2, "contracts": [good["contracts"][0]]}, today)
+    assert r["schema_version"] == 2 and r["schema_warnings"], r
+    assert not r["validity_errors"], r
+
+    # invalid schema value
+    try:
+        health_report({"schema": "one", "contracts": []}, today)
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("expected ValueError for non-integer schema")
+
+    # not a contracts list
+    for bad_ledger in ({}, {"contracts": "nope"}):
+        try:
+            health_report(bad_ledger, today)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError("expected ValueError for malformed ledger")
+
+    print("self-test: OK")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Check Autonomy Ledger health (v1 format).")
+    parser.add_argument("ledger", nargs="?", help="path to ledger.yaml")
+    parser.add_argument("--today", help="override today's date (ISO) for testing")
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    parser.add_argument("--self-test", action="store_true", help="run built-in tests and exit")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        _self_test()
+        return 0
+
+    if not args.ledger:
+        parser.error("a ledger file is required (or --self-test)")
+
+    if yaml is None:
+        print("error: PyYAML is required (pip install pyyaml)", file=sys.stderr)
+        return 2
+
+    try:
+        with open(args.ledger, encoding="utf-8") as fh:
+            ledger = yaml.safe_load(fh)
+    except (OSError, yaml.YAMLError) as exc:
+        print(f"error: cannot read ledger: {exc}", file=sys.stderr)
+        return 2
+
+    today = parse_date(args.today) if args.today else dt.date.today()
+    if today is None:
+        print("error: --today must be an ISO date", file=sys.stderr)
+        return 2
+
+    try:
+        report = health_report(ledger or {}, today)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    print(json.dumps(report, indent=2) if args.json else render(report))
+    bad = report["validity_errors"] or report["stale_reviews"] or report["expired_horizons"]
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

measuring_autonomy-1.1.0/src/measuring_autonomy/score.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""Autonomy score calculator for the Measuring & Managing Autonomy framework.
+
+Implements the scoring rules from docs/maturity-model.md and
+docs/assessment.md:
+
+  - Each dimension (D1..D6) is scored 0..4 (autonomy levels L0..L4).
+  - Safe grant level per domain = min(D3, D4, D6)  ("weakest-link rule").
+  - D1/D2 are coaching signals; they cap expansion pace, not current grants.
+  - Recommended move comes from the decision table in the maturity model.
+
+Usage:
+    autonomy-score 3 3 2 2 1 1        # scores for D1..D6
+    autonomy-score --current 1 3 3 2 2 1
+    autonomy-score --self-test       # run the built-in tests
+    python3 tools/autonomy_score.py ...   # zero-install form from a checkout
+
+Scores are given in order: D1_clarity D2_capability D3_guardrails
+D4_telemetry D5_transparency D6_accountability.
+
+License: MIT (see LICENSE).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+DIMENSIONS = [
+    ("D1", "decision_clarity"),
+    ("D2", "capability"),
+    ("D3", "guardrails"),
+    ("D4", "telemetry"),
+    ("D5", "transparency"),
+    ("D6", "accountability"),
+]
+
+WEAKEST_LINK = ("D3", "D4", "D6")  # guardrails, telemetry, accountability
+CLEAN_CYCLES_TO_EXPAND = 2  # consecutive clean reviews required to expand
+
+# Semantic version of the scoring ruleset. See docs/versioning.md.
+# MAJOR = re-scoring (scores not comparable); MINOR = additive/clarification;
+# PATCH = no change to scored outputs. Kept identical to site/scoring.js;
+# parity is asserted by tools/site_selftest.js.
+RULESET_VERSION = "1.0.0"
+
+
+def parse_scores(values: list[str]) -> dict[str, int]:
+    """Parse and validate six dimension scores (ints 0..4)."""
+    if len(values) != 6:
+        raise SystemExit(
+            f"error: expected exactly 6 scores (D1..D6), got {len(values)}\n"
+            "usage: autonomy-score D1 D2 D3 D4 D5 D6"
+        )
+    scores: dict[str, int] = {}
+    for (code, _name), raw in zip(DIMENSIONS, values):
+        try:
+            score = int(raw)
+        except ValueError:
+            raise SystemExit(f"error: score for {code} must be an integer, got {raw!r}")
+        if not 0 <= score <= 4:
+            raise SystemExit(f"error: score for {code} must be in 0..4, got {score}")
+        scores[code] = score
+    return scores
+
+
+def safe_level(scores: dict[str, int]) -> int:
+    """Weakest-link rule: min over D3, D4, D6."""
+    return min(scores[d] for d in WEAKEST_LINK)
+
+
+def gap_analysis(scores: dict[str, int], current: int | None) -> list[str]:
+    """Notes on granted-vs-exercised and coaching signals."""
+    notes: list[str] = []
+    weakest = min(scores[d] for d in WEAKEST_LINK)
+    coaching = [d for d in ("D1", "D2") if scores[d] < weakest]
+    if coaching:
+        notes.append(
+            f"coaching signal: {', '.join(coaching)} below the safety floor — "
+            "invest in clarity/capability; do not revoke for this"
+        )
+    if current is not None:
+        headroom = safe_level(scores) - current
+        if headroom > 0:
+            notes.append(
+                f"headroom: safe level exceeds granted level by {headroom}; "
+                f"expand after {CLEAN_CYCLES_TO_EXPAND} clean review cycles"
+            )
+        elif headroom < 0:
+            notes.append(
+                f"over-grant: granted level exceeds safe level by {-headroom}; "
+                "fix guardrails/telemetry/accountability or step down"
+            )
+        else:
+            notes.append("granted level matches safe level: hold and review")
+    return notes
+
+
+def recommended_move(scores: dict[str, int], current: int | None) -> str:
+    """Map a score vector to the management move (maturity model §4)."""
+    weakest = safe_level(scores)
+    if current is None:
+        return "formalize: write a contract at the safe level before any change"
+    if weakest < current:
+        return "contract or re-shape: safety dimensions lag the grant"
+    if weakest > current:
+        return (
+            f"expand (after {CLEAN_CYCLES_TO_EXPAND} clean cycles): "
+            "raise one level or widen scope in the strongest dimension"
+        )
+    if min(scores["D1"], scores["D2"]) < weakest:
+        return "hold and coach: capability/clarity lag; keep the grant"
+    return "hold: stable at the current level; re-review next horizon"
+
+
+def assess(scores: dict[str, int], current: int | None) -> dict:
+    return {
+        "ruleset_version": RULESET_VERSION,
+        "scores": {code: scores[code] for code, _ in DIMENSIONS},
+        "safe_grant_level": safe_level(scores),
+        "granted_level": current,
+        "notes": gap_analysis(scores, current),
+        "recommended_move": recommended_move(scores, current),
+    }
+
+
+def render(result: dict) -> str:
+    lines = ["Autonomy assessment", "=" * 40]
+    lines.append(f"Ruleset version: {RULESET_VERSION}")
+    for (code, name) in DIMENSIONS:
+        lines.append(f"{code} ({name}): {result['scores'][code]}")
+    lines += ["", f"Safe grant level (min D3,D4,D6): L{result['safe_grant_level']}"]
+    if result["granted_level"] is not None:
+        lines.append(f"Currently granted level:       L{result['granted_level']}")
+    lines.append(f"Recommended move: {result['recommended_move']}")
+    for note in result["notes"]:
+        lines.append(f"note: {note}")
+    return "\n".join(lines)
+
+
+def _self_test() -> None:
+    # Version stamp present in outputs, and identical to the JS engine
+    # (parity: docs/versioning.md makes cross-implementation drift a blocker).
+    # Enforced when the JS engine sits next to this package (repository
+    # checkout, CI); skipped for installed wheels and standalone binaries,
+    # which do not ship site/scoring.js — CI keeps enforcing it on push.
+    assert RULESET_VERSION == "1.0.0"
+    assert assess({d: 1 for d, _ in DIMENSIONS}, None)["ruleset_version"] == RULESET_VERSION
+    _repo_root = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), os.pardir, os.pardir
+    )
+    _js_path = os.path.join(_repo_root, "site", "scoring.js")
+    if os.path.exists(_js_path):
+        with open(_js_path, encoding="utf-8") as _fh:
+            _js = _fh.read()
+        _m = re.search(r'RULESET_VERSION\s*=\s*"([^"]+)"', _js)
+        assert _m and _m.group(1) == RULESET_VERSION, (
+            f"version drift: py={RULESET_VERSION} js={_m and _m.group(1)}"
+        )
+    else:
+        print("note: JS parity check skipped (site/scoring.js not present; standalone install)")
+    # Weakest-link rule
+    assert safe_level({d: 4 for d, _ in DIMENSIONS}) == 4
+    assert safe_level({"D3": 2, "D4": 3, "D6": 1, "D1": 4, "D2": 4, "D5": 4}) == 1
+    # Weakest link ignores D1/D2/D5
+    assert safe_level({"D3": 3, "D4": 3, "D6": 3, "D1": 0, "D2": 0, "D5": 0}) == 3
+    # Worked example from examples/README.md: scores 1 3 2 2 1 1, no formal grant
+    ex = assess({"D1": 1, "D2": 3, "D3": 2, "D4": 2, "D5": 1, "D6": 1}, current=None)
+    assert ex["safe_grant_level"] == 1
+    assert ex["recommended_move"].startswith("formalize")
+    # Coaching signal fires when D1/D2 lag the safety floor
+    coach = assess({"D1": 0, "D2": 1, "D3": 3, "D4": 3, "D6": 3, "D5": 3}, current=3)
+    assert any("coaching" in n for n in coach["notes"])
+    assert coach["recommended_move"].startswith("hold and coach")
+    # Over-grant detection
+    over = assess({"D1": 4, "D2": 4, "D3": 1, "D4": 4, "D5": 4, "D6": 4}, current=3)
+    assert any("over-grant" in n for n in over["notes"])
+    assert over["recommended_move"].startswith("contract")
+    # Validation errors
+    for bad in (["1", "2", "3", "4", "5"], ["1", "2", "3", "4", "5", "x"], ["9"] * 6):
+        try:
+            parse_scores(bad)
+        except SystemExit:
+            pass
+        else:
+            raise AssertionError(f"expected validation failure for {bad}")
+    print("self-test: OK")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Compute safe autonomy level and recommended move from six dimension scores."
+    )
+    parser.add_argument("scores", nargs="*", help="six scores 0..4 for D1..D6")
+    parser.add_argument("--current", type=int, metavar="L", help="currently granted level 0..4")
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    parser.add_argument("--self-test", action="store_true", help="run built-in tests and exit")
+    args = parser.parse_args(argv)
+
+    if args.self_test:
+        _self_test()
+        return 0
+
+    if args.current is not None and not 0 <= args.current <= 4:
+        raise SystemExit("error: --current must be in 0..4")
+
+    scores = parse_scores(args.scores)
+    result = assess(scores, args.current)
+    print(json.dumps(result, indent=2) if args.json else render(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

measuring_autonomy-1.1.0/src/measuring_autonomy.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: measuring-autonomy
+Version: 1.1.0
+Summary: Measure and manage autonomy: safe-level scoring, Autonomy Ledger health checks, and framework tooling.
+Author: Emmanuel A. Otchere
+License: MIT
+Project-URL: Homepage, https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy
+Project-URL: Changelog, https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy/blob/main/CHANGELOG.md
+Keywords: autonomy,governance,maturity-model,management,org-design
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=5.4
+Dynamic: license-file
+
+# Measuring and Managing Autonomy
+
+Autonomy from a business and systems point of view can be challenging to
+manage. This project defines a framework by which managing and measuring
+autonomy can be designed and implemented.
+
+Most organizations manage autonomy implicitly — it emerges from trust, tenure,
+and accidents of structure, and is therefore felt but not measured, expanded
+but never designed, and revoked arbitrarily. This framework makes autonomy an
+**explicit, designed, measurable property** of the organization.
+
+## The framework in one diagram
+
+```mermaid
+flowchart LR
+    A[Design<br>decision + blast radius] --> B[Grant<br>autonomy contract]
+    B --> C[Measure<br>ledger + telemetry]
+    C --> D[Manage<br>expand / contract / re-shape]
+    D -->|re-grant, next horizon| B
+```
+
+## What's here
+
+| Document | Purpose |
+|---|---|
+| [Framework](docs/framework.md) | Definitions, the three axes, the five levels (L0–L4), autonomy contracts |
+| [Maturity model](docs/maturity-model.md) | Six dimensions × five levels grid, scoring rules, the Autonomy Ledger |
+| [Assessment](docs/assessment.md) | The questionnaire and scoring procedure — the practical instrument |
+| [Governance loop](docs/governance-loop.md) | Grant → Instrument → Observe → Review, with cadence and anti-patterns |
+| [Positioning](docs/positioning.md) | Related work, lineage, open questions, BibTeX |
+| [Worked example](examples/README.md) | One team, scored end to end, producing a governance move |
+| [AI agents as units](docs/agents-as-units.md) | First-pass extension: scoring agent units with the same instrument |
+| [Ledger format](docs/ledger-format.md) | Machine-readable Autonomy Ledger (YAML v1) + health checks |
+| [Contract template](docs/contract-template.md) | Autonomy contract + review agenda, ready to copy |
+| [Versioning](docs/versioning.md) | Ruleset/ledger versioning policy — how assessments stay comparable |
+| [Changelog](CHANGELOG.md) | Every change, classified by comparability impact |
+
+## Install
+
+**No Python needed** — standalone binaries for macOS, Linux, and Windows are
+attached to each [GitHub Release](https://github.com/emmanuel-a-otchere/MeasuringAndManagingAutonomy/releases):
+download `autonomy-score-<os>-<arch>` and `ledger-health-<os>-<arch>`, mark
+them executable, run.
+
+**With Python 3.9+** (installs the `autonomy-score` and `ledger-health`
+commands):
+
+```bash
+pipx install measuring-autonomy    # or: pip install measuring-autonomy
+```
+
+**From a clone**, the zero-install form keeps working with no packaging step:
+`python3 tools/autonomy_score.py ...` (the `tools/` scripts are shims over
+`src/measuring_autonomy/`).
+
+## Quick start: score a team
+
+```bash
+python3 tools/autonomy_score.py 1 3 2 2 1 1 --current 1
+```
+
+Scores are D1 clarity, D2 capability, D3 guardrails, D4 telemetry,
+D5 transparency, D6 accountability (0–4 each). The tool applies the
+weakest-link rule — `min(guardrails, telemetry, accountability)` — and
+outputs the safe grant level and recommended move.
+
+```bash
+python3 tools/autonomy_score.py --self-test   # verify the scoring rules
+```
+
+Track granted autonomy in a machine-readable **Autonomy Ledger** (v1 YAML
+format, [`examples/ledger.yaml`](examples/ledger.yaml)) and check its health:
+
+```bash
+python3 tools/ledger_health.py examples/ledger.yaml   # requires PyYAML (pip install pyyaml)
+```
+
+## Try it without a terminal
+
+A dependency-free web version of the assessment lives in [`site/`](site/)
+(and is published to GitHub Pages when enabled — repo **Settings → Pages →
+Source: GitHub Actions**). Open `site/index.html` locally, tick the items
+with evidence, and print the scorecard.
+
+## The three questions
+
+1. **Design** — What autonomy should this unit have, and why? →
+   [contracts](docs/framework.md#5-autonomy-contracts)
+2. **Measurement** — How much autonomy exists, and how well is it used? →
+   [maturity model](docs/maturity-model.md) + [assessment](docs/assessment.md)
+3. **Management** — When should autonomy expand, contract, or re-shape? →
+   [governance loop](docs/governance-loop.md)
+
+## Roadmap
+
+See [docs/roadmap.md](docs/roadmap.md). Current status: **v0.1 draft** — the
+written framework, maturity model, and assessment instrument are complete;
+next up are validation against real teams and optional tooling.
+
+## Contributing
+
+Feedback, corrections, and real-world applications are very welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md). Use the issue templates to report
+framework feedback or submit a case study.
+
+## License
+
+[MIT](LICENSE)

measuring_autonomy-1.1.0/src/measuring_autonomy.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/measuring_autonomy/__init__.py
+src/measuring_autonomy/ledger.py
+src/measuring_autonomy/score.py
+src/measuring_autonomy.egg-info/PKG-INFO
+src/measuring_autonomy.egg-info/SOURCES.txt
+src/measuring_autonomy.egg-info/dependency_links.txt
+src/measuring_autonomy.egg-info/entry_points.txt
+src/measuring_autonomy.egg-info/requires.txt
+src/measuring_autonomy.egg-info/top_level.txt

measuring_autonomy-1.1.0/src/measuring_autonomy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

measuring_autonomy-1.1.0/src/measuring_autonomy.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+autonomy-score = measuring_autonomy.score:main
+ledger-health = measuring_autonomy.ledger:main

measuring_autonomy-1.1.0/src/measuring_autonomy.egg-info/requires.txt

@@ -0,0 +1 @@
+pyyaml>=5.4

measuring_autonomy-1.1.0/src/measuring_autonomy.egg-info/top_level.txt

@@ -0,0 +1 @@
+measuring_autonomy