agent-lifecycle-kit 2.30.0__tar.gz → 2.32.0__tar.gz

{agent_lifecycle_kit-2.30.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.30.0
+Version: 2.32.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -35,14 +35,14 @@ Dynamic: license-file
 
 The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
 
-ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification. Release 2.30 adds [bounded workflow history, migration and exact-run authorization renewal](docs/reference/workflow-state-storage.md), preserving history, costs, clocks and the existing review attempt. Install the Python package as well as the plugin for the new CLI commands.
+Release 2.32 adds [advisory process observations and eight selected reading routes](docs/reference/cli.md#release-232-process-observations-and-reading-scope); missing whole-run evidence and provider usage remain null/UNAVAILABLE. ALK provides a verifiable finish for external-agent work with proportionate control. Release 2.31 strengthens supported-text secret checks, enforces global branch and critical-file coverage floors, and gives a bounded structural refusal for malformed legacy state. See [the 2.31 check boundaries](docs/reference/cli.md#release-231-bounded-quality-checks). See [workflow history and recovery](docs/reference/workflow-state-storage.md) for the earlier storage and renewal features. Install the Python package as well as the plugin for the new CLI commands.
 
 Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/performance-and-resource-budgets.md#release-228-lifecycle-and-accounting-baselines). Repository tools measure real read-only operations and separate fixture preparation from operation and subprocess time. The Windows fixture comparison observed a 13.08% median reduction in one six-sample experiment; it is not a universal speed promise. All security and platform checks remain required.
 
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.30.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.32.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/README.md

@@ -12,14 +12,14 @@
 
 The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
 
-ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification. Release 2.30 adds [bounded workflow history, migration and exact-run authorization renewal](docs/reference/workflow-state-storage.md), preserving history, costs, clocks and the existing review attempt. Install the Python package as well as the plugin for the new CLI commands.
+Release 2.32 adds [advisory process observations and eight selected reading routes](docs/reference/cli.md#release-232-process-observations-and-reading-scope); missing whole-run evidence and provider usage remain null/UNAVAILABLE. ALK provides a verifiable finish for external-agent work with proportionate control. Release 2.31 strengthens supported-text secret checks, enforces global branch and critical-file coverage floors, and gives a bounded structural refusal for malformed legacy state. See [the 2.31 check boundaries](docs/reference/cli.md#release-231-bounded-quality-checks). See [workflow history and recovery](docs/reference/workflow-state-storage.md) for the earlier storage and renewal features. Install the Python package as well as the plugin for the new CLI commands.
 
 Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/performance-and-resource-budgets.md#release-228-lifecycle-and-accounting-baselines). Repository tools measure real read-only operations and separate fixture preparation from operation and subprocess time. The Windows fixture comparison observed a 13.08% median reduction in one six-sample experiment; it is not a universal speed promise. All security and platform checks remain required.
 
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.30.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.32.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.30.0"
+version = "2.32.0"
 description = "Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion."
 readme = "README.md"
 requires-python = ">=3.11,<3.16"

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.30.0"
+__version__ = "2.32.0"

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/src/agent_lifecycle/accounting/workflow_authority_store.py

@@ -29,6 +29,7 @@ from agent_lifecycle.contracts.workflow_state_schemas import (
     validate_adoption_input,
     validate_adoption_selection,
     validate_runtime_binding,
+    validate_workflow_state,
 )
 from agent_lifecycle.contracts.workflow_storage_context import StorageOperation
 
@@ -480,6 +481,7 @@ def prepare_legacy_adoption_candidate(
         raise LifecycleError("workflow-adoption-invalid", "Legacy state path differs from binding")
     state_raw = _adoption_artifact(root, state_ref)
     state = load_json_object(state_raw, label="legacy workflow state")
+    validate_workflow_state(state)
     if (
         not has_current_workflow_semantics(state)
         or state["runId"] != binding["runId"]

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/src/agent_lifecycle/contracts/metric_schemas.py

@@ -19,6 +19,7 @@ METRIC_SCHEMAS: dict[str, dict[str, Any]] = {
             "usageConfidence": {"type": "object"},
             "workflowEconomics": {"type": "array", "items": {"type": "object"}},
             "compactSummary": {"type": "object"},
+            "processObservation": {"type": "object"},
             "limits": {"type": "object"},
             "overLimitReason": {"type": "string"},
             "productionPromotionClaimed": {"const": False},
@@ -32,6 +33,7 @@ METRIC_SCHEMAS: dict[str, dict[str, Any]] = {
             "mode": {"type": ["string", "null"]},
             "totals": {"type": "object"},
             "ratios": {"type": "object"},
+            "processObservation": {"type": "object"},
             "usageConfidence": {"type": "object"},
             "limits": {"type": "object"},
             "blockers": {"type": "array", "items": {"type": "object"}},
@@ -78,6 +80,7 @@ METRIC_SCHEMAS: dict[str, dict[str, Any]] = {
             "nextRequiredAction": {"type": "string"},
             "doNotDo": {"type": "array", "items": {"type": "string"}},
             "categoryTotals": {"type": "object"},
+            "processObservation": {"type": "object"},
             "ratios": {"type": "object"},
             "usageConfidence": {"type": "object"},
             "workflowEconomics": {"type": "array", "items": {"type": "object"}},

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/src/agent_lifecycle/metrics/cost_collection.py

@@ -11,6 +11,7 @@ from agent_lifecycle.metrics.costs import (
     COST_SUMMARY_SCHEMA,
     cost_entry_totals,
     cost_ratios,
+    observe_process_costs,
     summarize_usage_confidence,
 )
 from agent_lifecycle.metrics.phase_resources import (
@@ -34,13 +35,18 @@ def generate_lifecycle_cost_report(
     source_artifacts: list[dict[str, Any]] = []
     entries: list[dict[str, Any]] = []
     payloads: list[dict[str, Any]] = []
-    for index, raw_path in enumerate(artifact_paths):
-        payload, source = _load_source_artifact(raw_path, project_root)
+    seen_paths: set[Path] = set()
+    for raw_path in artifact_paths:
+        source_path = (raw_path if raw_path.is_absolute() else project_root / raw_path).resolve()
+        if source_path in seen_paths:
+            continue
+        seen_paths.add(source_path)
+        payload, source = _load_source_artifact(source_path, project_root)
         source_artifacts.append(source)
-        entries.append(_entry_from_artifact(index, source, payload))
+        entries.append(_entry_from_artifact(len(entries), source, payload))
         payloads.append(payload)
 
-    report = {
+    report: dict[str, Any] = {
         "schemaVersion": COST_REPORT_SCHEMA,
         "mode": mode,
         "generatedBy": "agent-lifecycle metrics cost-report",
@@ -54,6 +60,7 @@ def generate_lifecycle_cost_report(
         "productionPromotionClaimed": False,
     }
     report["compactSummary"] = build_lifecycle_cost_summary(report)
+    report["processObservation"] = report["compactSummary"]["processObservation"]
     return report
 
 
@@ -65,6 +72,7 @@ def build_lifecycle_cost_summary(report: dict[str, Any]) -> dict[str, Any]:
     totals = cost_entry_totals(entries)
     ratios = cost_ratios(totals)
     usage_confidence = summarize_usage_confidence(entries)
+    process_observation = observe_process_costs(entries)
     source_paths = _source_paths(report)
     missing_usage = usage_confidence["missingEntries"]
     next_action = "review missing usage entries" if missing_usage else "continue with the selected lifecycle policy"
@@ -76,6 +84,8 @@ def build_lifecycle_cost_summary(report: dict[str, Any]) -> dict[str, Any]:
             f"pipelineTokenShare={ratios['pipelineTokenShare']}",
             f"pipelineStepShare={ratios['pipelineStepShare']}",
             f"missingUsageEntries={missing_usage}",
+            f"suppliedRecordsProcessTokenShare={process_observation['reportedSubtotal']['processTokenShare']}",
+            "wholeRunCoverage=UNAVAILABLE",
         ],
         "openBlockers": [],
         "acceptedEvidence": [
@@ -94,6 +104,7 @@ def build_lifecycle_cost_summary(report: dict[str, Any]) -> dict[str, Any]:
         "categoryTotals": totals,
         "ratios": ratios,
         "usageConfidence": usage_confidence,
+        "processObservation": process_observation,
         "workflowEconomics": report.get("workflowEconomics", []),
         "usefulWorkTokens": totals["implementation"]["tokens"] + totals["productValidation"]["tokens"],
         "processOverheadTokens": totals["pipelineCompliance"]["tokens"] + totals["coordination"]["tokens"],

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0}/src/agent_lifecycle/metrics/costs.py

@@ -79,6 +79,7 @@ def validate_lifecycle_cost_report(report: dict[str, Any]) -> dict[str, Any]:
         "totals": totals,
         "ratios": ratios,
         "usageConfidence": usage_confidence,
+        "processObservation": observe_process_costs(entries),
         "limits": limits,
         "blockers": blockers,
         "reportDigest": canonical_digest(report),
@@ -206,6 +207,92 @@ def cost_ratios(totals: dict[str, dict[str, int]]) -> dict[str, float]:
     }
 
 
+def observe_process_costs(entries: list[Any]) -> dict[str, Any]:
+    """Describe supplied records without claiming a complete run inventory."""
+
+    reported = _empty_totals()
+    confirmed = _empty_totals()
+    confidence_states: set[str] = set()
+    reported_count = confirmed_count = 0
+    for entry in entries:
+        if not isinstance(entry, dict) or entry.get("category") not in COST_CATEGORIES:
+            continue
+        tokens, steps = entry.get("tokens"), entry.get("steps")
+        if (
+            not isinstance(tokens, int)
+            or isinstance(tokens, bool)
+            or tokens < 0
+            or not isinstance(steps, int)
+            or isinstance(steps, bool)
+            or steps < 0
+        ):
+            continue
+        if tokens == 0 and steps == 0:
+            continue
+        category = entry["category"]
+        confidence = entry.get("usageConfidence")
+        confidence_states.add(confidence if confidence in USAGE_CONFIDENCE_STATES else "UNSPECIFIED")
+        reported_count += 1
+        reported[category]["tokens"] += tokens
+        reported[category]["steps"] += steps
+        if confidence == "ATTESTED":
+            confirmed_count += 1
+            confirmed[category]["tokens"] += tokens
+            confirmed[category]["steps"] += steps
+    confidence = next(iter(confidence_states)) if len(confidence_states) == 1 else "MIXED"
+    if not confidence_states:
+        confidence = "UNAVAILABLE"
+    reported_subtotal = _process_subtotal(reported, reported_count, confidence)
+    warnings = []
+    if (
+        reported_subtotal["processOverheadTokens"] > reported_subtotal["usefulWorkTokens"]
+        or reported_subtotal["processOverheadSteps"] > reported_subtotal["usefulWorkSteps"]
+    ):
+        warnings.append(
+            {
+                "code": "process-overhead-dominates-supplied-records",
+                "advisoryOnly": True,
+                "scope": "supplied_report_entries",
+                "message": "Pipeline compliance plus coordination exceeds useful work in supplied records; "
+                "pipeline PASS does not establish economy or whole-run coverage.",
+            }
+        )
+    return {
+        "scope": "supplied_report_entries",
+        "confidence": confidence,
+        "reportedSubtotal": reported_subtotal,
+        "confirmedSubtotal": _process_subtotal(confirmed, confirmed_count, "ATTESTED") if confirmed_count else None,
+        "wholeRunCoverage": {
+            "status": "UNAVAILABLE",
+            "reason": "complete-run-inventory-unavailable",
+            "processTokenShare": None,
+            "processStepShare": None,
+        },
+        "warnings": warnings,
+    }
+
+
+def _process_subtotal(totals: dict[str, dict[str, int]], count: int, confidence: str) -> dict[str, Any]:
+    useful_tokens = totals["implementation"]["tokens"] + totals["productValidation"]["tokens"]
+    useful_steps = totals["implementation"]["steps"] + totals["productValidation"]["steps"]
+    process_tokens = totals["pipelineCompliance"]["tokens"] + totals["coordination"]["tokens"]
+    process_steps = totals["pipelineCompliance"]["steps"] + totals["coordination"]["steps"]
+    total_tokens, total_steps = useful_tokens + process_tokens, useful_steps + process_steps
+    return {
+        "scope": "supplied_report_entries",
+        "confidence": confidence,
+        "entryCount": count,
+        "tokens": total_tokens,
+        "steps": total_steps,
+        "usefulWorkTokens": useful_tokens,
+        "usefulWorkSteps": useful_steps,
+        "processOverheadTokens": process_tokens,
+        "processOverheadSteps": process_steps,
+        "processTokenShare": round(process_tokens / total_tokens, 6) if total_tokens else None,
+        "processStepShare": round(process_steps / total_steps, 6) if total_steps else None,
+    }
+
+
 def _check_pipeline_limits(
     totals: dict[str, dict[str, int]],
     ratios: dict[str, float],

{agent_lifecycle_kit-2.30.0 → agent_lifecycle_kit-2.32.0/src/agent_lifecycle_kit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.30.0
+Version: 2.32.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -35,14 +35,14 @@ Dynamic: license-file
 
 The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
 
-ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification. Release 2.30 adds [bounded workflow history, migration and exact-run authorization renewal](docs/reference/workflow-state-storage.md), preserving history, costs, clocks and the existing review attempt. Install the Python package as well as the plugin for the new CLI commands.
+Release 2.32 adds [advisory process observations and eight selected reading routes](docs/reference/cli.md#release-232-process-observations-and-reading-scope); missing whole-run evidence and provider usage remain null/UNAVAILABLE. ALK provides a verifiable finish for external-agent work with proportionate control. Release 2.31 strengthens supported-text secret checks, enforces global branch and critical-file coverage floors, and gives a bounded structural refusal for malformed legacy state. See [the 2.31 check boundaries](docs/reference/cli.md#release-231-bounded-quality-checks). See [workflow history and recovery](docs/reference/workflow-state-storage.md) for the earlier storage and renewal features. Install the Python package as well as the plugin for the new CLI commands.
 
 Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/performance-and-resource-budgets.md#release-228-lifecycle-and-accounting-baselines). Repository tools measure real read-only operations and separate fixture preparation from operation and subprocess time. The Windows fixture comparison observed a 13.08% median reduction in one six-sample experiment; it is not a universal speed promise. All security and platform checks remain required.
 
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.30.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.32.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run: