aocl 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
aocl/__init__.py ADDED
@@ -0,0 +1,76 @@
1
+ """aocl — Autonomous Operations & Closed Loops toolkit.
2
+
3
+ Formalizes the TechNE Hub "Autonomous Operations and Closed Loops" guide
4
+ (v1.2.0) as a versioned, tool-supported model: L1-L5 loop maturity assessment
5
+ across three vectors, the informative realization heuristic, loop velocity
6
+ taxonomy, and a CLAM-aligned loop modeler format.
7
+
8
+ The interlock in one line: Autonomous Operations cannot exist without Closed
9
+ Loops — loops translate intent into action, action into observation, and
10
+ observation into learning.
11
+ """
12
+
13
+ from aocl.assess import (
14
+ DECISION_MODELS,
15
+ FRONTIERS,
16
+ HITL,
17
+ LEVEL_NAMES,
18
+ RULESET_VERSION,
19
+ VECTORS,
20
+ VELOCITIES,
21
+ assess,
22
+ frontier,
23
+ gap_notes,
24
+ overall_level,
25
+ parse_vector_scores,
26
+ recommended_hitl,
27
+ recommended_model,
28
+ )
29
+ from aocl.realization import (
30
+ REFERENCE_POINTS,
31
+ assess_position,
32
+ complexity_from_components,
33
+ effort,
34
+ experience_from_components,
35
+ nearest_reference,
36
+ realize,
37
+ required_complexity,
38
+ required_experience,
39
+ sensitivity,
40
+ value_band,
41
+ value_exponential,
42
+ value_logarithmic,
43
+ )
44
+
45
+ __version__ = "0.1.0"
46
+
47
+ __all__ = [
48
+ "__version__",
49
+ "RULESET_VERSION",
50
+ "VECTORS",
51
+ "LEVEL_NAMES",
52
+ "FRONTIERS",
53
+ "HITL",
54
+ "DECISION_MODELS",
55
+ "VELOCITIES",
56
+ "parse_vector_scores",
57
+ "overall_level",
58
+ "frontier",
59
+ "recommended_model",
60
+ "recommended_hitl",
61
+ "gap_notes",
62
+ "assess",
63
+ "realize",
64
+ "effort",
65
+ "experience_from_components",
66
+ "complexity_from_components",
67
+ "sensitivity",
68
+ "required_complexity",
69
+ "required_experience",
70
+ "nearest_reference",
71
+ "value_band",
72
+ "value_logarithmic",
73
+ "value_exponential",
74
+ "assess_position",
75
+ "REFERENCE_POINTS",
76
+ ]
aocl/assess.py ADDED
@@ -0,0 +1,225 @@
1
+ """AOCL loop maturity assessment engine (OODA/MAPE decision-model guidance).
2
+
3
+ Three vectors — Goal Decisioning (GD), Data Veracity (DV), Feedback Intelligence (FI) —
4
+ each scored L1..L5. The loop's overall level is the WEAKEST of the three vectors.
5
+ See model/levels.yaml and model/vectors.yaml for the harvested definitions.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+ import sys
12
+
13
+ RULESET_VERSION = "1.0.0"
14
+
15
+ VECTORS = (("GD", "Goal Decisioning"), ("DV", "Data Veracity"), ("FI", "Feedback Intelligence"))
16
+ LEVEL_MIN, LEVEL_MAX = 1, 5
17
+
18
+ LEVEL_NAMES = {1: "Static", 2: "Reactive", 3: "Proactive", 4: "Predictive", 5: "Pre-emptive"}
19
+
20
+ # Frontier to the next level (doc §3.3); barrier notes in parentheses.
21
+ FRONTIERS = {
22
+ 1: ("Automation Frontier", "instrumentation, orchestration, rule engines — barrier: organizational trust"),
23
+ 2: ("Prediction Frontier", "data science capability, forecast models — barrier: data quality and feature engineering"),
24
+ 3: ("Cognition Frontier", "AI/ML infrastructure, model governance, MLOps, explainability — barriers: AI talent scarcity, non-stationary environments"),
25
+ 4: ("Autonomy Frontier", "experimentation infrastructure, digital twins, causal inference — barrier: delegating goal-setting to machines"),
26
+ }
27
+
28
+ DECISION_MODELS = ("OODA", "MAPE") # CUSTOM passes through for CLAM compatibility but is not advised here
29
+ VELOCITIES = ("fast", "tactical", "slow")
30
+
31
+ HITL = {1: "HITL", 2: "HITL", 3: "HOTL", 4: "HOTL", 5: "HOOTL"}
32
+
33
+
34
+ def parse_vector_scores(values) -> dict:
35
+ """Parse 3 integers (GD, DV, FI), each 1..5."""
36
+ if len(values) != len(VECTORS):
37
+ raise SystemExit(
38
+ f"error: expected exactly {len(VECTORS)} vector scores (GD DV FI), got {len(values)}\n"
39
+ "usage: aocl-score GD DV FI (each 1..5)"
40
+ )
41
+ scores = {}
42
+ for (code, _name), raw in zip(VECTORS, values):
43
+ if isinstance(raw, bool) or not isinstance(raw, (int, str)):
44
+ raise SystemExit(f"error: score for {code} must be an integer, got {raw!r}")
45
+ try:
46
+ score = int(raw)
47
+ except ValueError:
48
+ raise SystemExit(f"error: score for {code} must be an integer, got {raw!r}")
49
+ if not LEVEL_MIN <= score <= LEVEL_MAX:
50
+ raise SystemExit(f"error: score for {code} must be in {LEVEL_MIN}..{LEVEL_MAX}, got {score}")
51
+ scores[code] = score
52
+ return scores
53
+
54
+
55
+ def overall_level(vector_scores: dict) -> int:
56
+ """Weakest link across the three vectors."""
57
+ return min(vector_scores[v] for v, _ in VECTORS)
58
+
59
+
60
+ def frontier(level: int) -> tuple[str, str] | None:
61
+ """(name, barrier note) for the frontier to the next level; None at L5."""
62
+ return FRONTIERS.get(level)
63
+
64
+
65
+ def recommended_model(level: int, velocity: str = "tactical") -> str:
66
+ """(level x velocity) -> suggested decision model. L4-L5 fast loops keep the
67
+ deterministic MAPE skeleton; learning lives in the Slow Loops that parametrize them."""
68
+ if velocity not in VELOCITIES:
69
+ raise SystemExit(f"error: velocity must be one of {VELOCITIES}, got {velocity!r}")
70
+ if level <= 3:
71
+ return "MAPE"
72
+ return "OODA" if velocity in ("tactical", "slow") else "MAPE"
73
+
74
+
75
+ def recommended_hitl(level: int) -> str:
76
+ return HITL[level]
77
+
78
+
79
+ def _recommended_move(level: int) -> str:
80
+ return {
81
+ 1: "stabilize: automate thresholds to reach the Automation Frontier (reactive control)",
82
+ 2: "predict: add trend analysis and forecasting to cross the Prediction Frontier",
83
+ 3: "learn: introduce AI/ML strategy generation to cross the Cognition Frontier",
84
+ 4: "delegate: extend autonomy toward goal-setting across the Autonomy Frontier",
85
+ 5: "hold: govern at the strategic level; re-review on cadence",
86
+ }[level]
87
+
88
+
89
+ def gap_notes(vector_scores: dict, current: int | None) -> list[str]:
90
+ """Weakest-vector, frontier, and positioning notes."""
91
+ notes: list[str] = []
92
+ level = overall_level(vector_scores)
93
+ weakest_code, weakest_name = min(
94
+ ((v, n) for v, n in VECTORS if vector_scores[v] == level),
95
+ key=lambda t: t[0],
96
+ )
97
+ laggards = [v for v, _ in VECTORS if vector_scores[v] == level]
98
+ if len(laggards) < len(VECTORS):
99
+ names = ", ".join(n for v, n in VECTORS if v in laggards)
100
+ notes.append(f"weakest link: {names} at L{level} — advance the lagging vector(s) before raising the overall level")
101
+ if level < LEVEL_MAX:
102
+ name, barrier = FRONTIERS[level]
103
+ notes.append(f"next: {name} — {barrier}")
104
+ if current is not None:
105
+ if current == 0:
106
+ notes.append("no formal loop in operation: nothing is delegated to the loop yet")
107
+ headroom = level - current
108
+ if headroom > 0:
109
+ notes.append(f"headroom: assessed level exceeds current operation by {headroom}; raise after clean review cycles")
110
+ elif headroom < 0:
111
+ notes.append(f"over-assessment: operating level exceeds assessed level by {-headroom}; reassess the vectors or step the operation down")
112
+ else:
113
+ notes.append("operating level matches assessment: hold and review")
114
+ return notes
115
+
116
+
117
+ def assess(vector_scores: dict, current: int | None = None, velocity: str = "tactical") -> dict:
118
+ """Return the assessment record (the CLI --json shape). Pass-through: the vector
119
+ scores are echoed exactly as issued; nothing here re-scores them."""
120
+ level = overall_level(vector_scores)
121
+ return {
122
+ "ruleset_version": RULESET_VERSION,
123
+ "vector_levels": {v: vector_scores[v] for v, _ in VECTORS},
124
+ "level": level,
125
+ "current_level": current,
126
+ "velocity": velocity,
127
+ "notes": gap_notes(vector_scores, current),
128
+ "frontier": frontier(level)[0] if level < LEVEL_MAX else None,
129
+ "recommended_decision_model": recommended_model(level, velocity),
130
+ "hitl": recommended_hitl(level),
131
+ "recommended_move": _recommended_move(level),
132
+ }
133
+
134
+
135
+ def render(result: dict) -> str:
136
+ lines = [
137
+ "AOCL Loop Maturity Assessment",
138
+ f"Ruleset version: {result['ruleset_version']}",
139
+ ]
140
+ levels = result["vector_levels"]
141
+ for code, name in VECTORS:
142
+ lines.append(f" {code} {name}: L{levels[code]}")
143
+ lines.append(f"Overall level: L{result['level']} — {LEVEL_NAMES[result['level']]}")
144
+ if result["frontier"]:
145
+ lines.append(f"Next frontier: {result['frontier']}")
146
+ lines.append(f"Recommended decision model: {result['recommended_decision_model']}")
147
+ lines.append(f"Human interaction model: {result['hitl']}")
148
+ lines.append(f"Recommended move: {result['recommended_move']}")
149
+ if result["notes"]:
150
+ lines.append("Notes:")
151
+ lines.extend(f" - {n}" for n in result["notes"])
152
+ return "\n".join(lines)
153
+
154
+
155
+ def main(argv=None) -> int:
156
+ argv = list(sys.argv[1:] if argv is None else argv)
157
+ if "--self-test" in argv:
158
+ return _self_test()
159
+ velocity = "tactical"
160
+ if "--velocity" in argv:
161
+ i = argv.index("--velocity")
162
+ velocity = argv[i + 1]
163
+ del argv[i : i + 2]
164
+ as_json = "--json" in argv
165
+ if as_json:
166
+ argv.remove("--json")
167
+ current = None
168
+ if "--current" in argv:
169
+ i = argv.index("--current")
170
+ try:
171
+ current = int(argv[i + 1])
172
+ except (ValueError, IndexError):
173
+ raise SystemExit("error: --current must be an integer 1..5 (0 = no formal loop)")
174
+ if not 0 <= current <= 5:
175
+ raise SystemExit("error: --current must be an integer 1..5 (0 = no formal loop)")
176
+ del argv[i : i + 2]
177
+ scores = parse_vector_scores(argv)
178
+ result = assess(scores, current=current, velocity=velocity)
179
+ if as_json:
180
+ import json
181
+
182
+ print(json.dumps(result, indent=2))
183
+ else:
184
+ print(render(result))
185
+ return 0
186
+
187
+
188
+ def _self_test() -> int:
189
+ assert overall_level({"GD": 3, "DV": 4, "FI": 2}) == 2
190
+ assert overall_level({"GD": 5, "DV": 5, "FI": 5}) == 5
191
+ assert recommended_model(2, "fast") == "MAPE"
192
+ assert recommended_model(4, "slow") == "OODA"
193
+ assert recommended_model(5, "fast") == "MAPE"
194
+ assert recommended_hitl(3) == "HOTL"
195
+ assert recommended_hitl(5) == "HOOTL"
196
+ assert frontier(5) is None and frontier(1)[0] == "Automation Frontier"
197
+ try:
198
+ parse_vector_scores([6, 3, 3])
199
+ raise AssertionError("expected rejection of out-of-range score")
200
+ except SystemExit:
201
+ pass
202
+ try:
203
+ recommended_model(3, "hyper")
204
+ raise AssertionError("expected rejection of bad velocity")
205
+ except SystemExit:
206
+ pass
207
+ r = assess({"GD": 3, "DV": 3, "FI": 3}, current=3)
208
+ assert r["level"] == 3 and r["recommended_decision_model"] == "MAPE"
209
+ # Cross-engine version parity: site/scoring.js must carry the same literal.
210
+ try:
211
+ import os
212
+
213
+ js = os.path.join(os.path.dirname(__file__), "..", "..", "site", "scoring.js")
214
+ with open(js, encoding="utf-8") as fh:
215
+ src = fh.read()
216
+ match = re.search(r'RULESET_VERSION\s*=\s*"([^"]+)"', src)
217
+ assert match and match.group(1) == RULESET_VERSION, "site/scoring.js RULESET_VERSION drift"
218
+ except FileNotFoundError:
219
+ pass # installed wheel/binary: JS not adjacent
220
+ print(f"self-test OK (ruleset {RULESET_VERSION})")
221
+ return 0
222
+
223
+
224
+ if __name__ == "__main__":
225
+ sys.exit(main())
aocl/ledger.py ADDED
@@ -0,0 +1,344 @@
1
+ """AOCL loop ledger: the registry of managed closed loops (schema 1).
2
+
3
+ Validates a loop-ledger YAML file and reports organizational health:
4
+ validity, guardrail hygiene (L3+ loops need guardrails), review staleness,
5
+ and vector/level consistency. Modeled on the autonomy-ledger pattern:
6
+ the file declares its format with a top-level `schema:` integer.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import datetime as _dt
12
+ import json
13
+ import re
14
+ import sys
15
+ from pathlib import Path
16
+
17
+ try:
18
+ import yaml
19
+ except ImportError: # pragma: no cover
20
+ sys.exit("error: pyyaml is required for aocl-ledger (pip install pyyaml)")
21
+
22
+ RULESET_VERSION = "1.0.0"
23
+ SUPPORTED_SCHEMA_VERSION = 1
24
+
25
+ STATES = ("designed", "validated", "published", "active", "paused", "error", "retired")
26
+ VELOCITIES = ("fast", "tactical", "slow")
27
+ ENTITY_KINDS = ("process", "capability", "system", "function")
28
+ DECISION_MODELS = ("OODA", "MAPE", "CUSTOM") # CUSTOM passes through for CLAM compatibility
29
+ HITL_MODELS = ("HITL", "HOTL", "HOOTL")
30
+ HITL_BY_LEVEL = {1: "HITL", 2: "HITL", 3: "HOTL", 4: "HOTL", 5: "HOOTL"}
31
+
32
+ REQUIRED_FIELDS = (
33
+ "id", "entity", "entity_kind", "velocity", "level",
34
+ "decision_model", "owner", "state",
35
+ )
36
+ OPTIONAL_FIELDS = (
37
+ "vector_levels", "hitl", "guardrails", "budget_end_to_end",
38
+ "last_review", "review_cadence_days", "notes",
39
+ )
40
+
41
+ _BUDGETS = {
42
+ "fast": "< 100 ms",
43
+ "tactical": "< 10 min",
44
+ "slow": "< 7 days",
45
+ }
46
+
47
+
48
+ def _isodate(value) -> _dt.date | None:
49
+ if isinstance(value, _dt.date):
50
+ return value
51
+ if isinstance(value, str):
52
+ try:
53
+ return _dt.date.fromisoformat(value)
54
+ except ValueError:
55
+ return None
56
+ return None
57
+
58
+
59
+ def _validate_loop(raw, index: int) -> tuple[dict, list[str], list[str]]:
60
+ """Returns (loop, errors, warnings)."""
61
+ problems: list[str] = []
62
+ warnings: list[str] = []
63
+ if not isinstance(raw, dict):
64
+ return {}, [f"loops[{index}] is not a mapping"], []
65
+ lid = raw.get("id")
66
+ label = f"loop {lid!r}" if isinstance(lid, str) and lid else f"loops[{index}]"
67
+
68
+ for name in REQUIRED_FIELDS:
69
+ if name not in raw:
70
+ problems.append(f"{label}: missing required field {name!r}")
71
+ if problems:
72
+ return raw, problems, warnings
73
+
74
+ if not re.match(r"^[a-z0-9][a-z0-9-]*$", str(lid)):
75
+ problems.append(f"{label}: id must be a lowercase slug")
76
+ if raw["entity_kind"] not in ENTITY_KINDS:
77
+ problems.append(f"{label}: entity_kind must be one of {ENTITY_KINDS}")
78
+ if raw["velocity"] not in VELOCITIES:
79
+ problems.append(f"{label}: velocity must be one of {VELOCITIES}")
80
+ if raw["decision_model"] not in DECISION_MODELS:
81
+ problems.append(f"{label}: decision_model must be one of {DECISION_MODELS}")
82
+ if raw["state"] not in STATES:
83
+ problems.append(f"{label}: state must be one of {STATES}")
84
+ if not isinstance(raw["owner"], str) or not raw["owner"].strip():
85
+ problems.append(f"{label}: owner must be a non-empty string")
86
+
87
+ level = raw["level"]
88
+ if not isinstance(level, int) or isinstance(level, bool) or not 1 <= level <= 5:
89
+ problems.append(f"{label}: level must be an integer 1..5, got {level!r}")
90
+ level = None
91
+
92
+ vlevels = raw.get("vector_levels")
93
+ if vlevels is not None:
94
+ if not isinstance(vlevels, dict) or set(vlevels) != {"GD", "DV", "FI"}:
95
+ problems.append(f"{label}: vector_levels must be a mapping with exactly GD, DV, FI")
96
+ else:
97
+ for code, val in vlevels.items():
98
+ if not isinstance(val, int) or isinstance(val, bool) or not 1 <= val <= 5:
99
+ problems.append(f"{label}: vector_levels.{code} must be an integer 1..5")
100
+ if all(isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= 5 for v in vlevels.values()):
101
+ weakest = min(vlevels.values())
102
+ if level is not None and level != weakest:
103
+ problems.append(
104
+ f"{label}: level {level} inconsistent with weakest vector level {weakest} "
105
+ "(overall level = min of GD/DV/FI)"
106
+ )
107
+
108
+ hitl = raw.get("hitl")
109
+ if hitl is not None:
110
+ if hitl not in HITL_MODELS:
111
+ problems.append(f"{label}: hitl must be one of {HITL_MODELS}")
112
+ elif level is not None and hitl != HITL_BY_LEVEL[level]:
113
+ warnings.append(
114
+ f"{label}: hitl {hitl} differs from the level-{level} default "
115
+ f"{HITL_BY_LEVEL[level]} (permitted; recorded)"
116
+ )
117
+
118
+ guardrails = raw.get("guardrails", [])
119
+ if guardrails is None:
120
+ guardrails = []
121
+ if not isinstance(guardrails, list) or not all(isinstance(g, str) and g.strip() for g in guardrails):
122
+ problems.append(f"{label}: guardrails must be a list of non-empty strings")
123
+ elif level is not None and level >= 3 and not guardrails:
124
+ problems.append(
125
+ f"{label}: a loop at L{level} without guardrails is not AO-ready "
126
+ "(safety-envelope integrity, assumption 4)"
127
+ )
128
+
129
+ if raw["velocity"] == "fast" and not raw.get("budget_end_to_end"):
130
+ warnings.append(f"{label}: fast loop without a recorded end-to-end latency budget")
131
+ if raw.get("budget_end_to_end") and raw.get("budget_end_to_end") != _BUDGETS.get(raw["velocity"]) and raw.get("budget_end_to_end") != "custom":
132
+ warnings.append(
133
+ f"{label}: budget {raw['budget_end_to_end']!r} differs from the {raw['velocity']} "
134
+ f"reference budget {_BUDGETS[raw['velocity']]!r} (permitted; recorded)"
135
+ )
136
+
137
+ horizon_ok = True
138
+ if "last_review" in raw and raw["last_review"] is not None:
139
+ parsed = _isodate(raw["last_review"])
140
+ if parsed is None:
141
+ problems.append(f"{label}: last_review must be an ISO date, got {raw['last_review']!r}")
142
+ horizon_ok = False
143
+ cadence = raw.get("review_cadence_days", 90)
144
+ if not isinstance(cadence, int) or isinstance(cadence, bool) or cadence <= 0:
145
+ problems.append(f"{label}: review_cadence_days must be a positive integer")
146
+
147
+ unknown = set(raw) - set(REQUIRED_FIELDS) - set(OPTIONAL_FIELDS)
148
+ if unknown:
149
+ problems.append(f"{label}: unknown fields {sorted(unknown)} — ledger schema 1 does not define them")
150
+
151
+ _ = horizon_ok # staleness handled in health_report against --today
152
+ return raw, problems, warnings
153
+
154
+
155
+ def load_ledger(path) -> dict:
156
+ path = Path(path)
157
+ with path.open(encoding="utf-8") as fh:
158
+ data = yaml.safe_load(fh)
159
+ if not isinstance(data, dict):
160
+ raise ValueError(f"{path}: ledger must be a YAML mapping with 'schema' and 'loops'")
161
+
162
+ schema = data.get("schema")
163
+ warnings: list[str] = []
164
+ if schema is None:
165
+ warnings.append("pre-versioning ledger: no 'schema' field — re-save with 'schema: 1'")
166
+ schema = None
167
+ elif not isinstance(schema, int) or isinstance(schema, bool):
168
+ raise ValueError(f"{path}: 'schema' must be an integer, got {schema!r}")
169
+ elif schema > SUPPORTED_SCHEMA_VERSION:
170
+ raise ValueError(
171
+ f"{path}: ledger schema {schema} is newer than supported schema "
172
+ f"{SUPPORTED_SCHEMA_VERSION} — fail-closed; update the tool"
173
+ )
174
+ elif schema < SUPPORTED_SCHEMA_VERSION:
175
+ warnings.append(f"ledger schema {schema} is older than supported {SUPPORTED_SCHEMA_VERSION}")
176
+
177
+ loops_raw = data.get("loops")
178
+ if not isinstance(loops_raw, list):
179
+ raise ValueError(f"{path}: top-level 'loops' must be a list")
180
+
181
+ loops, errors, loop_warnings = [], [], []
182
+ for i, raw in enumerate(loops_raw):
183
+ loop, problems, warns = _validate_loop(raw, i)
184
+ loops.append(loop)
185
+ errors.extend(problems)
186
+ loop_warnings.extend(warns)
187
+
188
+ ids = [l.get("id") for l in loops if isinstance(l, dict) and l.get("id")]
189
+ duplicates = sorted({i for i in ids if ids.count(i) > 1})
190
+ if duplicates:
191
+ errors.append(f"duplicate loop ids: {duplicates}")
192
+
193
+ return {
194
+ "schema_version": schema,
195
+ "loops": loops,
196
+ "errors": errors,
197
+ "warnings": warnings + loop_warnings,
198
+ "source": str(path),
199
+ }
200
+
201
+
202
+ def health_report(ledger: dict, today: _dt.date | None = None) -> dict:
203
+ today = today or _dt.date.today()
204
+ loops = ledger["loops"]
205
+ active = [l for l in loops if l.get("state") == "active"]
206
+ by_level: dict[int, int] = {}
207
+ by_velocity: dict[str, int] = {}
208
+ for l in loops:
209
+ lv = l.get("level")
210
+ if isinstance(lv, int):
211
+ by_level[lv] = by_level.get(lv, 0) + 1
212
+ v = l.get("velocity")
213
+ if isinstance(v, str):
214
+ by_velocity[v] = by_velocity.get(v, 0) + 1
215
+
216
+ stale, unhygienic = [], 0
217
+ for l in loops:
218
+ problems = 0
219
+ cadence = l.get("review_cadence_days", 90)
220
+ last = _isodate(l.get("last_review")) if l.get("last_review") else None
221
+ if l.get("state") == "active":
222
+ if last is None:
223
+ stale.append({"id": l["id"], "reason": "active loop has never been reviewed"})
224
+ problems += 1
225
+ elif (today - last).days > cadence:
226
+ stale.append({
227
+ "id": l["id"],
228
+ "reason": f"last review {last} is {(today - last).days} days old (cadence {cadence})",
229
+ })
230
+ problems += 1
231
+ if l.get("level", 0) >= 3 and not l.get("guardrails"):
232
+ problems += 1
233
+ unhygienic += problems
234
+
235
+ coverage = 0.0
236
+ if loops:
237
+ complete = sum(
238
+ 1 for l in loops
239
+ if all(l.get(f) not in (None, "") for f in REQUIRED_FIELDS)
240
+ and (l.get("level", 5) < 3 or bool(l.get("guardrails")))
241
+ )
242
+ coverage = complete / len(loops)
243
+
244
+ return {
245
+ "ruleset_version": RULESET_VERSION,
246
+ "schema_version": ledger["schema_version"],
247
+ "schema_warnings": ledger["warnings"],
248
+ "total_loops": len(loops),
249
+ "active": len(active),
250
+ "by_level": {f"L{k}": v for k, v in sorted(by_level.items())},
251
+ "by_velocity": {k: v for k, v in sorted(by_velocity.items())},
252
+ "validity_errors": ledger["errors"],
253
+ "stale_reviews": stale,
254
+ "unhygienic_count": unhygienic,
255
+ "coverage": round(coverage, 4),
256
+ "today": today.isoformat(),
257
+ }
258
+
259
+
260
+ def render(report: dict) -> str:
261
+ lines = [
262
+ "AOCL Loop Ledger Health",
263
+ f"Ruleset version: {report['ruleset_version']}",
264
+ f"Loops: {report['total_loops']} total, {report['active']} active",
265
+ ]
266
+ if report["by_level"]:
267
+ lines.append("By level: " + ", ".join(f"{k}: {v}" for k, v in report["by_level"].items()))
268
+ if report["by_velocity"]:
269
+ lines.append("By velocity: " + ", ".join(f"{k}: {v}" for k, v in report["by_velocity"].items()))
270
+ lines.append(f"Coverage (complete loops): {report['coverage']:.0%}")
271
+ for w in report["schema_warnings"]:
272
+ lines.append(f"warning: {w}")
273
+ for e in report["validity_errors"]:
274
+ lines.append(f"error: {e}")
275
+ for s in report["stale_reviews"]:
276
+ lines.append(f"stale: {s['id']} — {s['reason']}")
277
+ if report["unhygienic_count"]:
278
+ lines.append(f"hygiene findings: {report['unhygienic_count']}")
279
+ lines.append(f"(as of {report['today']})")
280
+ return "\n".join(lines)
281
+
282
+
283
+ def main(argv=None) -> int:
284
+ argv = list(sys.argv[1:] if argv is None else argv)
285
+ if "--self-test" in argv:
286
+ return _self_test()
287
+ as_json = "--json" in argv
288
+ argv = [a for a in argv if a != "--json"]
289
+ today = None
290
+ if "--today" in argv:
291
+ i = argv.index("--today")
292
+ today = _dt.date.fromisoformat(argv[i + 1])
293
+ del argv[i : i + 2]
294
+ if not argv:
295
+ print("usage: aocl-ledger <ledger.yaml> [--today YYYY-MM-DD] [--json] | --self-test")
296
+ return 2
297
+ try:
298
+ ledger = load_ledger(argv[0])
299
+ except (OSError, ValueError) as exc:
300
+ print(f"error: {exc}")
301
+ return 2
302
+ report = health_report(ledger, today)
303
+ print(json.dumps(report, indent=2) if as_json else render(report))
304
+ return 1 if (report["validity_errors"] or report["unhygienic_count"] or report["stale_reviews"]) else 0
305
+
306
+
307
+ def _self_test() -> int:
308
+ good = {
309
+ "id": "loop-a", "entity": "proc-1", "entity_kind": "process", "velocity": "fast",
310
+ "level": 3, "decision_model": "MAPE", "owner": "op-lead", "state": "active",
311
+ "guardrails": ["policy bounds enforced"], "budget_end_to_end": "< 100 ms",
312
+ "last_review": "2026-11-01", "review_cadence_days": 90,
313
+ }
314
+ loop, errors, warnings = _validate_loop(dict(good), 0)
315
+ assert not errors and not warnings, (errors, warnings)
316
+ # vector/level consistency:
317
+ bad = dict(good, level=5, vector_levels={"GD": 5, "DV": 5, "FI": 3})
318
+ _, errors, _ = _validate_loop(bad, 0)
319
+ assert any("inconsistent" in e for e in errors)
320
+ # L3 without guardrails is an error:
321
+ _, errors, _ = _validate_loop({k: v for k, v in good.items() if k != "guardrails"}, 0)
322
+ assert any("not AO-ready" in e for e in errors)
323
+ # hitl mismatch is a recorded warning, not an error:
324
+ _, errors, warnings = _validate_loop(dict(good, hitl="HOOTL"), 0)
325
+ assert not errors and any("differs from the level-3 default" in w for w in warnings)
326
+ # L1 without guardrails is fine:
327
+ l1 = dict(good, level=1, velocity="slow")
328
+ _, errors, _ = _validate_loop(l1, 0)
329
+ assert not errors
330
+ # unknown field rejected:
331
+ _, errors, _ = _validate_loop(dict(good, blended_score=9), 0)
332
+ assert any("unknown fields" in e for e in errors)
333
+ # report math with deterministic today:
334
+ ledger = {"schema_version": 1, "loops": [good], "errors": [], "warnings": [], "source": "t"}
335
+ report = health_report(ledger, today=_dt.date(2026, 12, 5)) # 34 days after review
336
+ assert report["stale_reviews"] == [] and report["coverage"] == 1.0
337
+ report = health_report(ledger, today=_dt.date(2027, 2, 1)) # 92 days after
338
+ assert len(report["stale_reviews"]) == 1
339
+ print(f"self-test OK (ruleset {RULESET_VERSION}, ledger schema {SUPPORTED_SCHEMA_VERSION})")
340
+ return 0
341
+
342
+
343
+ if __name__ == "__main__":
344
+ sys.exit(main())