agent-lifecycle-kit 2.13.0__tar.gz → 2.14.0__tar.gz

{agent_lifecycle_kit-2.13.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.13.0
+Version: 2.14.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
@@ -43,7 +43,7 @@ ALK provides a verifiable finish for external-agent work with proportionate cont
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.13.0`, and common `agent-lifecycle version` errors.
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.14.0`, and common `agent-lifecycle version` errors.
 
 For a quick start, run:
 
@@ -69,7 +69,7 @@ agent-lifecycle start --adapter <adapter-id> --file task.md
 - The [system architecture](docs/architecture/system-architecture.md) page explains how the project is organized, and [project comparison](docs/reference/project-comparison.md) shows how it differs from similar tools.
 - Multiple-agent boundaries, workflow configuration, model choice, prompts, timeouts and retries are described in [workflow customization and execution controls](docs/reference/workflow-customization.md).
 - Create a local project profile with `agent-lifecycle project profile init`; see [project workflow profile](docs/reference/project-workflow-profile.md). Explain the selected profile, plan constraints and adapter capability lineage with [effective configuration](docs/reference/effective-configuration.md), [structured result qualification](docs/reference/structured-result-qualification.md) and [adapter action evidence](docs/reference/adapter-action-evidence.md). Add optional project-owned architecture and dependency evidence with [external verification checks](docs/reference/external-verification-checks.md), run longer specialized adapter work through [bounded external tool jobs](docs/reference/external-tool-jobs.md), track bounded terminology with [project domain language](docs/reference/project-domain-language.md), coordinate several runs with the read-only [multi-run attention view](docs/reference/multi-run-attention-view.md), or use the optional [security analysis profile](docs/reference/security-analysis-profile.md) for untrusted findings and independently verified remediation.
-- For long sessions, use [context checkpoints and compaction recovery](docs/reference/context-checkpoints.md). They preserve a bounded local continuation package without changing plan authority. Measure phases and releases with [release accounting](docs/reference/release-accounting.md), follow the bounded [phase-to-session handoff](docs/guides/phase-session-handoff.md) with [phase packets](docs/reference/phase-packets.md), and choose focused checks through the read-only [validation ladder](docs/reference/validation-ladder.md).
+- For long sessions, use [context checkpoints and compaction recovery](docs/reference/context-checkpoints.md). They preserve a bounded local continuation package without changing plan authority. Measure phases and releases with [release accounting](docs/reference/release-accounting.md), compare only compatible evidence through [workflow economics](docs/reference/workflow-economics.md), follow the bounded [phase-to-session handoff](docs/guides/phase-session-handoff.md) with [phase packets](docs/reference/phase-packets.md), and choose focused checks through the read-only [validation ladder](docs/reference/validation-ladder.md).
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.
 - One process for different CLIs: adapter-specific commands stay outside the

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/README.md

@@ -21,7 +21,7 @@ ALK provides a verifiable finish for external-agent work with proportionate cont
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.13.0`, and common `agent-lifecycle version` errors.
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.14.0`, and common `agent-lifecycle version` errors.
 
 For a quick start, run:
 
@@ -47,7 +47,7 @@ agent-lifecycle start --adapter <adapter-id> --file task.md
 - The [system architecture](docs/architecture/system-architecture.md) page explains how the project is organized, and [project comparison](docs/reference/project-comparison.md) shows how it differs from similar tools.
 - Multiple-agent boundaries, workflow configuration, model choice, prompts, timeouts and retries are described in [workflow customization and execution controls](docs/reference/workflow-customization.md).
 - Create a local project profile with `agent-lifecycle project profile init`; see [project workflow profile](docs/reference/project-workflow-profile.md). Explain the selected profile, plan constraints and adapter capability lineage with [effective configuration](docs/reference/effective-configuration.md), [structured result qualification](docs/reference/structured-result-qualification.md) and [adapter action evidence](docs/reference/adapter-action-evidence.md). Add optional project-owned architecture and dependency evidence with [external verification checks](docs/reference/external-verification-checks.md), run longer specialized adapter work through [bounded external tool jobs](docs/reference/external-tool-jobs.md), track bounded terminology with [project domain language](docs/reference/project-domain-language.md), coordinate several runs with the read-only [multi-run attention view](docs/reference/multi-run-attention-view.md), or use the optional [security analysis profile](docs/reference/security-analysis-profile.md) for untrusted findings and independently verified remediation.
-- For long sessions, use [context checkpoints and compaction recovery](docs/reference/context-checkpoints.md). They preserve a bounded local continuation package without changing plan authority. Measure phases and releases with [release accounting](docs/reference/release-accounting.md), follow the bounded [phase-to-session handoff](docs/guides/phase-session-handoff.md) with [phase packets](docs/reference/phase-packets.md), and choose focused checks through the read-only [validation ladder](docs/reference/validation-ladder.md).
+- For long sessions, use [context checkpoints and compaction recovery](docs/reference/context-checkpoints.md). They preserve a bounded local continuation package without changing plan authority. Measure phases and releases with [release accounting](docs/reference/release-accounting.md), compare only compatible evidence through [workflow economics](docs/reference/workflow-economics.md), follow the bounded [phase-to-session handoff](docs/guides/phase-session-handoff.md) with [phase packets](docs/reference/phase-packets.md), and choose focused checks through the read-only [validation ladder](docs/reference/validation-ladder.md).
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.
 - One process for different CLIs: adapter-specific commands stay outside the

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.13.0"
+version = "2.14.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.15"

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.13.0"
+__version__ = "2.14.0"

agent_lifecycle_kit-2.14.0/src/agent_lifecycle/cli/dispatch_metrics.py

@@ -0,0 +1,85 @@
+"""Metrics-specific dispatch helpers for the observability facade."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object, write_json_create
+from agent_lifecycle.metrics import require_lifecycle_recommendation_pass
+from agent_lifecycle.metrics.recommendations import recommend_from_workflow_comparison
+from agent_lifecycle.metrics.regression_signals import (
+    compare_workflow_economics,
+    validate_workflow_economics_comparison_view,
+    workflow_comparison_context_from_fixture,
+)
+from agent_lifecycle.reporting.execution_resources import (
+    build_execution_resource_report,
+    validate_execution_resource_report,
+)
+
+
+def _dispatch_execution_report(args: argparse.Namespace) -> dict[str, Any]:
+    receipts: list[dict[str, Any]] = []
+    for item in args.receipt:
+        payload = read_json_object(Path(item), label="process execution receipt")
+        raw_receipt = payload.get("processReceipt")
+        candidate = raw_receipt if isinstance(raw_receipt, dict) else payload
+        receipts.append(candidate)
+    lineage = {"operationId": args.operation_id} if args.operation_id else None
+    report = build_execution_resource_report(receipts, lineage=lineage)
+    validation = validate_execution_resource_report(report)
+    write_json_create(Path(args.out), report)
+    return {
+        "schemaVersion": "agent-execution-resource-report-generation.v1",
+        "status": validation["status"],
+        "reportPath": args.out,
+        "reportDigest": canonical_digest(report),
+        "validation": validation,
+        "liveCallsStarted": False,
+        "productionPromotionClaimed": False,
+    }
+
+
+def _dispatch_workflow_compare(args: argparse.Namespace) -> dict[str, Any]:
+    before = workflow_comparison_context_from_fixture(
+        read_json_object(Path(args.before), label="workflow comparison before fixture")
+    )
+    after = workflow_comparison_context_from_fixture(
+        read_json_object(Path(args.after), label="workflow comparison after fixture")
+    )
+    comparison_pair = (
+        read_json_object(Path(args.comparison_pair), label="workflow comparison pair") if args.comparison_pair else None
+    )
+    comparison = compare_workflow_economics(before, after, comparison_pair=comparison_pair)
+    validation = validate_workflow_economics_comparison_view(comparison)
+    if validation["status"] != "PASS":
+        raise LifecycleError(
+            "workflow-comparison-invalid",
+            "workflow economics comparison failed validation",
+            {"validation": validation},
+        )
+    write_json_create(Path(args.out), comparison)
+    return comparison
+
+
+def _dispatch_workflow_recommend(args: argparse.Namespace) -> dict[str, Any]:
+    comparison = read_json_object(Path(args.comparison), label="workflow economics comparison")
+    validation = validate_workflow_economics_comparison_view(comparison)
+    if validation["status"] != "PASS":
+        raise LifecycleError(
+            "workflow-comparison-invalid",
+            "workflow economics comparison failed validation",
+            {"validation": validation},
+        )
+    recommendation = recommend_from_workflow_comparison(
+        comparison=comparison,
+        task_shape=args.task_shape,
+        current_mode=args.current_mode,
+        required_mode=args.required_mode,
+        protected_work=args.protected_work,
+    )
+    require_lifecycle_recommendation_pass(recommendation)
+    write_json_create(Path(args.out), recommendation)
+    return recommendation

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/cli/dispatch_observability.py

@@ -7,7 +7,11 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
-from agent_lifecycle.cli.dispatch_metrics import _dispatch_execution_report
+from agent_lifecycle.cli.dispatch_metrics import (
+    _dispatch_execution_report,
+    _dispatch_workflow_compare,
+    _dispatch_workflow_recommend,
+)
 from agent_lifecycle.context import check_context, load_context_profile, render_context
 from agent_lifecycle.context.checkpoint_store import (
     restore_context_checkpoint,
@@ -452,18 +456,14 @@ def _dispatch_model(args: argparse.Namespace) -> dict[str, Any]:
     if args.model_command == "route":
         routing_profile = read_json_object(Path(args.profile), label="model routing profile")
         host_profile = (
-            read_json_object(Path(args.host_profile), label="host model profile")
-            if args.host_profile
-            else None
+            read_json_object(Path(args.host_profile), label="host model profile") if args.host_profile else None
         )
         request = read_json_object(Path(args.request), label="model route request")
         return resolve_model_route(request, routing_profile, host_profile=host_profile)
     if args.model_command == "usage-check":
         receipt = read_json_object(Path(args.receipt), label="model usage receipt")
         decision = (
-            read_json_object(Path(args.route_decision), label="model route decision")
-            if args.route_decision
-            else None
+            read_json_object(Path(args.route_decision), label="model route decision") if args.route_decision else None
         )
         targets = read_json_object(Path(args.budget_targets), label="budget targets") if args.budget_targets else None
         result = validate_usage_receipt(receipt, budget_targets=targets, route_decision=decision)
@@ -512,6 +512,10 @@ def _dispatch_metrics(args: argparse.Namespace) -> dict[str, Any] | str:
         return _dispatch_phase_resources(args)
     if args.metrics_command == "release-accounting":
         return _dispatch_release_accounting(args)
+    if args.metrics_command == "workflow-compare":
+        return _dispatch_workflow_compare(args)
+    if args.metrics_command == "workflow-recommend":
+        return _dispatch_workflow_recommend(args)
     if args.metrics_command == "usage-export":
         export = build_usage_export(
             artifact_paths=[Path(item) for item in args.artifact],
@@ -591,9 +595,7 @@ def _dispatch_metrics(args: argparse.Namespace) -> dict[str, Any] | str:
     if args.metrics_command == "audit-proposal":
         report = read_json_object(Path(args.report), label="audit optimization report")
         raw_recommendation = report.get("recommendation")
-        proposal_recommendation: dict[str, Any] = (
-            raw_recommendation if isinstance(raw_recommendation, dict) else {}
-        )
+        proposal_recommendation: dict[str, Any] = raw_recommendation if isinstance(raw_recommendation, dict) else {}
         proposal = build_optimization_proposal(
             proposal_recommendation,
             approved=args.approved,
@@ -648,9 +650,7 @@ def _dispatch_phase_resources(args: argparse.Namespace) -> dict[str, Any]:
 
 def _dispatch_release_accounting(args: argparse.Namespace) -> dict[str, Any]:
     declared_provenance = (
-        read_json_object(Path(args.provenance), label="release accounting provenance")
-        if args.provenance
-        else None
+        read_json_object(Path(args.provenance), label="release accounting provenance") if args.provenance else None
     )
     accounting = build_release_accounting(
         args.release_id,

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/cli/metrics_parser.py

@@ -31,6 +31,24 @@ def add_metrics_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentP
     release_accounting.add_argument("--project-root", default=".")
     release_accounting.add_argument("--provenance")
     release_accounting.add_argument("--out", required=True)
+    workflow_compare = metrics_sub.add_parser(
+        "workflow-compare",
+        help="compare two explicitly bound workflow economics fixtures",
+    )
+    workflow_compare.add_argument("--before", required=True)
+    workflow_compare.add_argument("--after", required=True)
+    workflow_compare.add_argument("--comparison-pair")
+    workflow_compare.add_argument("--out", required=True)
+    workflow_recommend = metrics_sub.add_parser(
+        "workflow-recommend",
+        help="build an advisory recommendation from a workflow comparison",
+    )
+    workflow_recommend.add_argument("--comparison", required=True)
+    workflow_recommend.add_argument("--task-shape", default="feature")
+    workflow_recommend.add_argument("--current-mode", choices=MODES, required=True)
+    workflow_recommend.add_argument("--required-mode", choices=MODES, required=True)
+    workflow_recommend.add_argument("--protected-work", action="store_true")
+    workflow_recommend.add_argument("--out", required=True)
     usage_export = metrics_sub.add_parser("usage-export")
     usage_export.add_argument("--artifact", action="append", default=[])
     usage_export.add_argument("--project-root", default=".")

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/contracts/metric_schemas.py

@@ -17,6 +17,7 @@ METRIC_SCHEMAS: dict[str, dict[str, Any]] = {
             "sourceArtifacts": {"type": "array", "items": {"type": "object"}},
             "lineage": {"type": "object"},
             "usageConfidence": {"type": "object"},
+            "workflowEconomics": {"type": "array", "items": {"type": "object"}},
             "compactSummary": {"type": "object"},
             "limits": {"type": "object"},
             "overLimitReason": {"type": "string"},
@@ -79,6 +80,7 @@ METRIC_SCHEMAS: dict[str, dict[str, Any]] = {
             "categoryTotals": {"type": "object"},
             "ratios": {"type": "object"},
             "usageConfidence": {"type": "object"},
+            "workflowEconomics": {"type": "array", "items": {"type": "object"}},
             "usefulWorkTokens": {"type": "integer", "minimum": 0},
             "processOverheadTokens": {"type": "integer", "minimum": 0},
         },
@@ -294,6 +296,7 @@ METRIC_SCHEMAS: dict[str, dict[str, Any]] = {
             "phases": {"type": "array", "minItems": 1, "maxItems": 256, "items": {"type": "object"}},
             "usageExport": {"type": "object"},
             "totals": {"type": "object"},
+            "workflowEconomics": {"type": "object"},
             "blockers": {"type": "array", "items": {"type": "object"}},
             "productionPromotionClaimed": {"const": False},
             "measurementDigest": {"type": "string", "minLength": 64, "maxLength": 64},

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/contracts/release_accounting_schemas.py

@@ -28,6 +28,7 @@ RELEASE_ACCOUNTING_SCHEMAS: dict[str, dict[str, Any]] = {
             "releaseId": {"type": "string", "minLength": 1, "maxLength": 256},
             "entryCount": {"type": "integer", "minimum": 1, "maximum": 1024},
             "entries": {"type": "array", "minItems": 1, "maxItems": 1024, "items": {"type": "object"}},
+            "workflowEconomics": {"type": "object"},
             "provenance": {"type": "object"},
             "blockers": _BLOCKERS,
             "productionPromotionClaimed": {"const": False},
@@ -64,6 +65,7 @@ RELEASE_ACCOUNTING_SCHEMAS: dict[str, dict[str, Any]] = {
             "views": {"type": "object"},
             "categoryTotals": {"type": "object"},
             "totals": {"type": "object"},
+            "workflowEconomics": {"type": "object"},
             "exclusions": {"type": "array", "items": {"type": "object"}},
             "provenance": {"type": "object"},
             "blockers": _BLOCKERS,

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/contracts/workflow_economics_schemas.py

@@ -9,8 +9,90 @@ from agent_lifecycle.contracts.schema_builders import open_object_schema
 
 _DIGEST = {"type": "string", "minLength": 64, "maxLength": 64}
 _IMPLEMENTATION_REQUIRED = ["role", "sourceRevision", "coreVersion", "publicationVersions"]
+_SOURCE_STATUS = ["MEASURED", "ESTIMATED", "TIME_WINDOW_ONLY", "UNAVAILABLE"]
+_AGGREGATE_STATUS = [*_SOURCE_STATUS, "MIXED", "PARTIAL"]
+_NON_WINDOW_AGGREGATE_STATUS = [status for status in _AGGREGATE_STATUS if status != "TIME_WINDOW_ONLY"]
+_WORKFLOW_METRIC_KEYS = (
+    "modelInputTokens",
+    "modelCachedInputTokens",
+    "modelOutputTokens",
+    "modelTurns",
+    "toolCalls",
+    "toolWallMs",
+    "toolOutputBytes",
+    "packetBytes",
+    "controllerTransitions",
+    "requiredGateCount",
+    "passedGateCount",
+    "failedGateCount",
+    "elapsedWallMs",
+    "parallelComputeMs",
+)
+_METRIC_VALUE = {"type": ["integer", "null"], "minimum": 0, "maximum": (1 << 63) - 1}
+_SOURCE_METRIC = {
+    "type": "object",
+    "required": ["status", "value"],
+    "properties": {"status": {"enum": _SOURCE_STATUS}, "value": _METRIC_VALUE},
+    "additionalProperties": False,
+}
+_AGGREGATE_METRIC = {
+    "type": "object",
+    "required": ["status", "value"],
+    "properties": {"status": {"enum": _AGGREGATE_STATUS}, "value": _METRIC_VALUE},
+    "additionalProperties": False,
+}
+
+
+def _aggregate_metric_schema(name: str) -> dict[str, Any]:
+    statuses = _AGGREGATE_STATUS if name in {"elapsedWallMs", "toolWallMs"} else _NON_WINDOW_AGGREGATE_STATUS
+    return {
+        "type": "object",
+        "required": ["status", "value"],
+        "properties": {"status": {"enum": statuses}, "value": _METRIC_VALUE},
+        "additionalProperties": False,
+    }
+
 
 WORKFLOW_ECONOMICS_SCHEMAS: dict[str, dict[str, Any]] = {
+    "agent-workflow-resource-summary.v1": open_object_schema(
+        "agent-workflow-resource-summary.v1",
+        required=[
+            "schemaVersion",
+            "status",
+            "sourceAvailabilityStatuses",
+            "derivedAggregateStatuses",
+            "sourceCount",
+            "enclosingElapsedWall",
+            "metrics",
+            "productionPromotionClaimed",
+            "summaryDigest",
+        ],
+        properties={
+            "status": {"const": "PASS"},
+            "sourceAvailabilityStatuses": {"const": _SOURCE_STATUS},
+            "derivedAggregateStatuses": {"const": ["MIXED", "PARTIAL"]},
+            "sourceCount": {"type": "integer", "minimum": 0, "maximum": 1024},
+            "enclosingElapsedWall": _SOURCE_METRIC,
+            "metrics": {
+                "type": "object",
+                "required": list(_WORKFLOW_METRIC_KEYS),
+                "properties": {name: _aggregate_metric_schema(name) for name in _WORKFLOW_METRIC_KEYS},
+                "additionalProperties": False,
+            },
+            "productionPromotionClaimed": {"const": False},
+            "summaryDigest": _DIGEST,
+        },
+    ),
+    "agent-workflow-resource-summary-validation.v1": open_object_schema(
+        "agent-workflow-resource-summary-validation.v1",
+        required=["schemaVersion", "status", "blockers", "summaryDigest", "validationDigest"],
+        properties={
+            "status": {"enum": ["PASS", "FAIL"]},
+            "blockers": {"type": "array", "items": {"type": "object"}},
+            "summaryDigest": {"type": ["string", "null"], "minLength": 64, "maxLength": 64},
+            "validationDigest": _DIGEST,
+        },
+    ),
     "agent-comparable-workload-identity.v1": open_object_schema(
         "agent-comparable-workload-identity.v1",
         required=[
@@ -154,9 +236,7 @@ def validate_workflow_economics_comparison(
         workload_identity = {}
         blockers.append({"code": "comparison-workload-identity-invalid"})
     else:
-        identity_body = {
-            key: value for key, value in workload_identity.items() if key != "workloadIdentityDigest"
-        }
+        identity_body = {key: value for key, value in workload_identity.items() if key != "workloadIdentityDigest"}
         if workload_identity.get("workloadIdentityDigest") != canonical_digest(identity_body):
             blockers.append({"code": "comparison-workload-identity-digest-invalid"})
 

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/metrics/__init__.py

@@ -47,15 +47,26 @@ from agent_lifecycle.metrics.usage_export import (
     usage_export_totals,
     validate_usage_export,
 )
+from agent_lifecycle.metrics.workflow_economics import (
+    DERIVED_AGGREGATE_STATUSES,
+    SOURCE_AVAILABILITY_STATUSES,
+    WORKFLOW_METRIC_KEYS,
+    build_workflow_metric_set,
+    build_workflow_resource_summary,
+    validate_workflow_resource_summary,
+)
 
 __all__ = [
     "ACCOUNTING_VIEWS",
     "COST_CATEGORIES",
     "DEFAULT_MODE_LIMITS",
+    "DERIVED_AGGREGATE_STATUSES",
     "MAX_PHASE_RESOURCE_ENTRIES",
     "MAX_RELEASE_ACCOUNTING_ARTIFACTS",
     "MAX_RELEASE_ACCOUNTING_ENTRIES",
     "PROVENANCE_FIELDS",
+    "SOURCE_AVAILABILITY_STATUSES",
+    "WORKFLOW_METRIC_KEYS",
     "build_lifecycle_cost_summary",
     "build_lifecycle_recommendation_summary",
     "build_phase_resource_measurement",
@@ -65,6 +76,8 @@ __all__ = [
     "build_release_accounting_source",
     "build_task_outcome_index",
     "build_usage_export",
+    "build_workflow_metric_set",
+    "build_workflow_resource_summary",
     "generate_lifecycle_cost_report",
     "recommend_from_quality_cost_signals",
     "recommend_lifecycle_mode",
@@ -82,6 +95,7 @@ __all__ = [
     "validate_release_accounting",
     "validate_release_accounting_source",
     "validate_usage_export",
+    "validate_workflow_resource_summary",
 ]
 
 _LAZY_AUDIT_OPTIMIZATION_EXPORTS = {

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/metrics/audit_efficiency.py

@@ -9,8 +9,12 @@ from agent_lifecycle.contracts.audit_optimization_schemas import (
     AUDIT_EFFICIENCY_INPUT_SCHEMA,
     AUDIT_EFFICIENCY_REPORT_SCHEMA,
 )
+from agent_lifecycle.metrics.regression_signals import (
+    compare_workflow_economics,
+    validate_workflow_economics_comparison_view,
+)
 
-METRIC_STATUSES = ("MEASURED", "ESTIMATED", "TIME_WINDOW_ONLY", "MIXED", "UNAVAILABLE")
+METRIC_STATUSES = ("MEASURED", "ESTIMATED", "TIME_WINDOW_ONLY", "UNAVAILABLE")
 _VIEW_NAMES = ("alkProcess", "implementation", "audit", "postAuditRemediation")
 _VIEW_METRICS = ("tokens", "elapsedWallMs", "computeMs")
 _OUTCOME_METRICS = (
@@ -31,6 +35,8 @@ def build_audit_efficiency_input(
     views: dict[str, Any],
     outcomes: dict[str, Any],
     totals: dict[str, Any],
+    comparison_context: dict[str, Any] | None = None,
+    comparison_pair: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     """Build a portable accounting input without inventing unavailable values."""
 
@@ -45,6 +51,10 @@ def build_audit_efficiency_input(
         "totals": totals,
         "productionPromotionClaimed": False,
     }
+    if comparison_context is not None:
+        body["comparisonContext"] = comparison_context
+    if comparison_pair is not None:
+        body["comparisonPair"] = comparison_pair
     result = {**body, "inputDigest": canonical_digest(body)}
     validation = validate_audit_efficiency_input(result)
     if validation["status"] != "PASS":
@@ -107,6 +117,7 @@ def validate_audit_efficiency_input(value: Any) -> dict[str, Any]:
             blockers,
             code="audit-efficiency-total-metric-invalid",
             location="totals.elapsedWallMs",
+            allow_derived=True,
         )
     if value.get("productionPromotionClaimed") is not False:
         blockers.append({"code": "audit-efficiency-production-claim"})
@@ -181,6 +192,15 @@ def validate_audit_efficiency_report(report: Any) -> dict[str, Any]:
             metric = comparison.get(field)
             if metric != _unavailable("comparison-sample-required"):
                 blockers.append({"code": "audit-efficiency-single-sample-reduction", "field": field})
+    workflow_comparison = comparison.get("workflowComparison")
+    if workflow_comparison is not None:
+        workflow_validation = validate_workflow_economics_comparison_view(workflow_comparison)
+        if workflow_validation["status"] != "PASS":
+            blockers.append({"code": "audit-efficiency-workflow-comparison-invalid"})
+        if workflow_comparison.get("status") != "IMPROVED":
+            for field in ("tokenReductionPercent", "wallReductionPercent"):
+                if _available(comparison.get(field)):
+                    blockers.append({"code": "audit-efficiency-unproven-reduction", "field": field})
     expected = canonical_digest({key: item for key, item in report.items() if key != "reportDigest"})
     if report.get("reportDigest") != expected:
         blockers.append({"code": "audit-efficiency-report-digest-mismatch"})
@@ -265,16 +285,61 @@ def _comparison(
             "wallReductionPercent": _unavailable("comparison-telemetry-unavailable"),
             "qualityFloorPreserved": True,
         }
+    before_context = baseline.get("comparisonContext")
+    after_context = measurement.get("comparisonContext")
+    if not isinstance(before_context, dict) or not isinstance(after_context, dict):
+        blockers.append({"code": "audit-efficiency-comparison-context-unavailable"})
+        return {
+            "sampleCount": sample_count,
+            "workflowStatus": "NO_COMPARABLE_BASELINE",
+            "tokenReductionPercent": _unavailable("comparison-context-unavailable"),
+            "wallReductionPercent": _unavailable("comparison-context-unavailable"),
+            "qualityFloorPreserved": True,
+        }
+    before_pair = baseline.get("comparisonPair")
+    after_pair = measurement.get("comparisonPair")
+    pair = before_pair if before_pair == after_pair and isinstance(before_pair, dict) else None
+    if (before_pair is None) != (after_pair is None) or (
+        before_pair is not None and after_pair is not None and before_pair != after_pair
+    ):
+        blockers.append({"code": "audit-efficiency-comparison-pair-mismatch"})
+    workflow_comparison = compare_workflow_economics(before_context, after_context, comparison_pair=pair)
+    workflow_validation = validate_workflow_economics_comparison_view(workflow_comparison)
+    if workflow_validation["status"] != "PASS":
+        blockers.append({"code": "audit-efficiency-workflow-comparison-invalid", "validation": workflow_validation})
+    if workflow_comparison["status"] == "NO_COMPARABLE_BASELINE":
+        blockers.append(
+            {
+                "code": "audit-efficiency-workflow-baseline-not-comparable",
+                "comparisonBlockers": workflow_comparison["blockers"],
+            }
+        )
+    if workflow_comparison["assurance"]["status"] == "WEAKER":
+        blockers.append(
+            {
+                "code": "audit-efficiency-assurance-weakened",
+                "reasons": workflow_comparison["assurance"]["reasons"],
+            }
+        )
+    reductions_allowed = workflow_comparison["status"] == "IMPROVED" and not blockers
     return {
         "sampleCount": sample_count,
-        "tokenReductionPercent": _reduction(
-            baseline["views"]["audit"]["tokens"], measurement["views"]["audit"]["tokens"]
+        "workflowStatus": workflow_comparison["status"],
+        "workflowComparison": workflow_comparison,
+        "tokenReductionPercent": (
+            _reduction(baseline["views"]["audit"]["tokens"], measurement["views"]["audit"]["tokens"])
+            if reductions_allowed
+            else _unavailable("workflow-improvement-not-proven")
         ),
-        "wallReductionPercent": _reduction(
-            baseline["views"]["audit"]["elapsedWallMs"],
-            measurement["views"]["audit"]["elapsedWallMs"],
+        "wallReductionPercent": (
+            _reduction(
+                baseline["views"]["audit"]["elapsedWallMs"],
+                measurement["views"]["audit"]["elapsedWallMs"],
+            )
+            if reductions_allowed
+            else _unavailable("workflow-improvement-not-proven")
         ),
-        "qualityFloorPreserved": True,
+        "qualityFloorPreserved": workflow_comparison["assurance"]["status"] != "WEAKER",
     }
 
 
@@ -322,8 +387,10 @@ def _validate_metric(
     code: str,
     location: str,
     integer: bool = False,
+    allow_derived: bool = False,
 ) -> None:
-    if not isinstance(metric, dict) or metric.get("status") not in METRIC_STATUSES:
+    allowed_statuses = {*METRIC_STATUSES, "MIXED", "PARTIAL"} if allow_derived else set(METRIC_STATUSES)
+    if not isinstance(metric, dict) or metric.get("status") not in allowed_statuses:
         blockers.append({"code": code, "location": location})
         return
     value = metric.get("value")

{agent_lifecycle_kit-2.13.0 → agent_lifecycle_kit-2.14.0}/src/agent_lifecycle/metrics/cost_collection.py

@@ -48,6 +48,9 @@ def generate_lifecycle_cost_report(
         "lineage": _lineage(source_artifacts, payloads),
         "entries": entries,
         "usageConfidence": summarize_usage_confidence(entries),
+        "workflowEconomics": [
+            entry["workflowEconomics"] for entry in entries if isinstance(entry.get("workflowEconomics"), dict)
+        ],
         "productionPromotionClaimed": False,
     }
     report["compactSummary"] = build_lifecycle_cost_summary(report)
@@ -91,6 +94,7 @@ def build_lifecycle_cost_summary(report: dict[str, Any]) -> dict[str, Any]:
         "categoryTotals": totals,
         "ratios": ratios,
         "usageConfidence": usage_confidence,
+        "workflowEconomics": report.get("workflowEconomics", []),
         "usefulWorkTokens": totals["implementation"]["tokens"] + totals["productValidation"]["tokens"],
         "processOverheadTokens": totals["pipelineCompliance"]["tokens"] + totals["coordination"]["tokens"],
     }
@@ -140,6 +144,10 @@ def _entry_from_artifact(index: int, source: dict[str, Any], payload: dict[str,
         value = payload.get(field)
         if isinstance(value, (str, int)):
             entry[field] = value
+    if payload.get("schemaVersion") == PHASE_RESOURCE_MEASUREMENT_SCHEMA and isinstance(
+        payload.get("workflowEconomics"), dict
+    ):
+        entry["workflowEconomics"] = payload["workflowEconomics"]
     return entry