feat(estates): Estates Warden Ostrom completeness check + commons health report

[Argocyte]

Summary

Two agent behaviours needed to operationalise the Ostrom commons charter framework: (1) a completeness check that blocks ill-formed asset policies, and (2) a periodic commons health report that detects when a charter's principles are degrading in practice.

Depends on: Issue #120 (commons charter template)
See Discussion #115 for full Ostrom framework assessment.

1. Estates Warden Completeness Check

When a member submits a new asset policy or charter amendment via the Estates Warden, the agent validates it against Ostrom's 8 principles before allowing it to proceed to Loomio:

# In Estates Warden tools.py

OSTROM_SECTIONS = {
    "boundaries": "Who has rights to the resource and what counts as the resource",
    "proportional_equivalence": "Benefits received match contributions made",
    "collective_choice": "Those affected can modify the rules",
    "monitoring": "Who monitors and how",
    "graduated_sanctions": "Violation tiers and restorative responses",
    "conflict_resolution": "Fast and formal dispute paths",
    "right_to_organise": "External recognition of self-governance right",
    "nested_enterprises": "How this resource sits in the wider scope hierarchy",
}

def validate_commons_charter(charter: dict) -> dict:
    """
    Returns {
      "valid": bool,
      "missing_sections": list[str],
      "incomplete_sections": list[str],  # sections present but "TBD"
      "sanctions_warning": bool,  # True if sanctions section lacks "restorative" framing
    }
    """
    missing = [k for k in OSTROM_SECTIONS if k not in charter]
    incomplete = [k for k in OSTROM_SECTIONS if charter.get(k) in (None, "", "TBD")]
    sanctions_ok = "restorative" in str(charter.get("graduated_sanctions", "")).lower()
    return {
        "valid": not missing and not incomplete,
        "missing_sections": missing,
        "incomplete_sections": incomplete,
        "sanctions_warning": not sanctions_ok,
    }

If valid = False: Estates Warden posts a gap report to the governance Mattermost channel and does not open a Loomio proposal. The gap report names the missing sections by their plain-language description (from OSTROM_SECTIONS).

If sanctions_warning = True: adds a note: "Graduated sanctions section should describe restorative (not punitive) responses. Please review."

2. Commons Health Report (Steward Agent, Weekly)

The Steward agent runs a weekly commons health check across all active commons charters:

def commons_health_check() -> list[HealthIssue]:
    """
    For each active commons charter, check that the 8 principles
    are still operationally satisfied. Return issues where a principle
    is degrading.
    """
    issues = []
    
    for charter in get_active_charters():
        # Principle 4: Monitoring — check for logging gaps
        last_log = get_last_estates_log(charter.asset_id)
        if last_log and (now() - last_log) > timedelta(days=45):
            issues.append(HealthIssue(
                charter=charter,
                principle=4,
                severity="warning",
                message=f"No monitoring log in 45 days. Principle 4 (Monitoring) at risk."
            ))
        
        # Principle 5: Graduated sanctions — check for unresolved Tier 2+ flags
        open_sanctions = get_open_sanctions(charter.asset_id, tier_gte=2)
        if open_sanctions and max(s.age_days for s in open_sanctions) > 14:
            issues.append(HealthIssue(
                charter=charter,
                principle=5,
                severity="alert",
                message=f"{len(open_sanctions)} Tier 2+ sanction(s) unresolved >14 days."
            ))
        
        # Principle 3: Collective choice — charter not reviewed in >1 year
        if (now() - charter.last_reviewed).days > 365:
            issues.append(HealthIssue(
                charter=charter,
                principle=3,
                severity="info",
                message="Charter not reviewed in >1 year. Consider scheduling a review."
            ))
    
    return issues

Steward posts weekly summary to governance channel. Alerts go immediately. Warnings and info items go in the weekly digest.

Glass Box Logging

All Estates Warden completeness checks are logged to the Glass Box:

Agent: EstatesWarden | Action: charter_validation | Asset: [id] | Result: invalid | Missing: [list]
Agent: EstatesWarden | Action: charter_validation | Asset: [id] | Result: valid | Loomio: opened

ICA Principles

• P2 Democratic Member Control — agents validate; humans decide
• P4 Autonomy — completeness check is self-governance, not external audit

[Argocyte]

Phase C.5 coordination — 2026-04-11

Phase C.5 Q4 Estates Warden (#138) absorbs this as a sub-task — the Ostrom completeness check is the inaugural report the agent produces. The broader Estates Warden agent has a wider scope than this issue alone.