agent-lifecycle-kit 2.2.0__tar.gz → 2.3.0__tar.gz

{agent_lifecycle_kit-2.2.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.2.0
+Version: 2.3.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.2.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.3.0`, and common `agent-lifecycle version` errors.
 
 For a quick start, run:
 
@@ -68,7 +68,7 @@ agent-lifecycle start --adapter <adapter-id> --file task.md
 - The boundaries of [planning-only launch](docs/reference/planning-only-launch.md) and [frozen-task launch through a verified profile](docs/reference/qualified-host-launch.md) are documented in the reference. Shipped planning profiles remain candidates with safe failure until the corresponding profile is verified.
 - 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), or track bounded terminology with [project domain language](docs/reference/project-domain-language.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), track bounded terminology with [project domain language](docs/reference/project-domain-language.md), or coordinate several runs with the read-only [multi-run attention view](docs/reference/multi-run-attention-view.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.
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.
@@ -195,7 +195,7 @@ Adapter installation and support-level details live in [Adapter install](docs/ad
 
 - Start: [English documentation](docs/README.md), [Русская документация](docs/ru/README.md), [Install](docs/guides/install-and-first-run.md), [Quickstart](docs/guides/quickstart.md), [Beginner and advanced workflows](docs/guides/beginner-and-advanced-workflows.md), [Commands by task](docs/guides/commands-by-task.md), [Research workflow](docs/guides/research-workflow.md), [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md), and [Code review workflows](docs/guides/code-review-workflows.md).
 - Planning and adapters: [Issue to specification drafts](docs/guides/issue-to-spec.md), [Adapter install](docs/adapters/install.md), and [Adapter support matrix](docs/adapters/support-matrix.md).
-- Reference: [System architecture](docs/architecture/system-architecture.md), [workflow customization and execution controls](docs/reference/workflow-customization.md), [execution strategy](docs/reference/execution-strategy.md), [CLI reference](docs/reference/cli.md), [External verification checks](docs/reference/external-verification-checks.md), [Project domain language](docs/reference/project-domain-language.md), [Plan verification](docs/reference/plan-verification.md), [Research evidence](docs/reference/research-evidence.md), [Public locators and redaction](docs/reference/public-locators-and-redaction.md), [Finding-to-check adoption](docs/reference/finding-check-adoption.md), [Source of truth](docs/reference/source-of-truth.md), [Managed lifecycle runner](docs/reference/managed-lifecycle-runner.md), [Managed adapter sessions](docs/reference/managed-adapter-sessions.md), [Portable Agent Plugins](docs/reference/agent-plugins.md), [Plugin publication](docs/reference/plugin-publication.md), [Implementation audit](docs/reference/implementation-audit.md), [Plan completeness](docs/reference/plan-completeness.md), [Public contracts](docs/reference/public-contracts.md), and [Readiness diagnostics](docs/reference/readiness-diagnostics.md).
+- Reference: [System architecture](docs/architecture/system-architecture.md), [workflow customization and execution controls](docs/reference/workflow-customization.md), [execution strategy](docs/reference/execution-strategy.md), [CLI reference](docs/reference/cli.md), [External verification checks](docs/reference/external-verification-checks.md), [Project domain language](docs/reference/project-domain-language.md), [Multi-run attention view](docs/reference/multi-run-attention-view.md), [Plan verification](docs/reference/plan-verification.md), [Research evidence](docs/reference/research-evidence.md), [Public locators and redaction](docs/reference/public-locators-and-redaction.md), [Finding-to-check adoption](docs/reference/finding-check-adoption.md), [Source of truth](docs/reference/source-of-truth.md), [Managed lifecycle runner](docs/reference/managed-lifecycle-runner.md), [Managed adapter sessions](docs/reference/managed-adapter-sessions.md), [Portable Agent Plugins](docs/reference/agent-plugins.md), [Plugin publication](docs/reference/plugin-publication.md), [Implementation audit](docs/reference/implementation-audit.md), [Plan completeness](docs/reference/plan-completeness.md), [Public contracts](docs/reference/public-contracts.md), and [Readiness diagnostics](docs/reference/readiness-diagnostics.md).
 - Quality and resources: [Reference-task evaluation](docs/reference/reference-task-evaluation.md), [model routing](docs/reference/model-routing.md), [quality-cost learning](docs/reference/quality-cost-learning.md), [performance and resource budgets](docs/reference/performance-and-resource-budgets.md), [lifecycle cost accounting](docs/reference/lifecycle-cost.md), [host-local token accounting](docs/reference/host-local-token-accounting.md), [process execution observability](docs/reference/process-execution-observability.md), [Usage export](docs/reference/usage-export.md), and [Evidence integrity](docs/reference/evidence-integrity.md).
 - Profiles and operations: [Project workflow presets](docs/reference/workflow-presets.md), [Project workflow profile](docs/reference/project-workflow-profile.md), [Read-only status views](docs/reference/read-only-status-view.md), [Adapter progress bridge](docs/reference/automatic-progress-bridge.md), [Sandbox boundaries](docs/reference/sandbox-boundaries.md), [Import mappers](docs/reference/import-mappers.md), [Episode retrieval](docs/reference/episode-retrieval.md), [Runner migration](docs/guides/runner-migration-2.md), [Runner recovery records](docs/reference/runner-recovery.md), [Cross-check profile](docs/reference/cross-check-profile.md), [Review Mesh](docs/reference/review-mesh.md), [Risk-bound independent verification](docs/reference/risk-bound-independent-verification.md), [Bug Forensics profile](docs/reference/bug-forensics.md), and [Bug Forensics context budget](docs/reference/bug-forensics-context-budget.md).
 - Release assets: [Task templates](templates/tasks/README.md), [Neutrality scanning](docs/reference/neutrality.md), and [Release security](docs/security/release-security.md).

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.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.2.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.3.0`, and common `agent-lifecycle version` errors.
 
 For a quick start, run:
 
@@ -46,7 +46,7 @@ agent-lifecycle start --adapter <adapter-id> --file task.md
 - The boundaries of [planning-only launch](docs/reference/planning-only-launch.md) and [frozen-task launch through a verified profile](docs/reference/qualified-host-launch.md) are documented in the reference. Shipped planning profiles remain candidates with safe failure until the corresponding profile is verified.
 - 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), or track bounded terminology with [project domain language](docs/reference/project-domain-language.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), track bounded terminology with [project domain language](docs/reference/project-domain-language.md), or coordinate several runs with the read-only [multi-run attention view](docs/reference/multi-run-attention-view.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.
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.
@@ -173,7 +173,7 @@ Adapter installation and support-level details live in [Adapter install](docs/ad
 
 - Start: [English documentation](docs/README.md), [Русская документация](docs/ru/README.md), [Install](docs/guides/install-and-first-run.md), [Quickstart](docs/guides/quickstart.md), [Beginner and advanced workflows](docs/guides/beginner-and-advanced-workflows.md), [Commands by task](docs/guides/commands-by-task.md), [Research workflow](docs/guides/research-workflow.md), [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md), and [Code review workflows](docs/guides/code-review-workflows.md).
 - Planning and adapters: [Issue to specification drafts](docs/guides/issue-to-spec.md), [Adapter install](docs/adapters/install.md), and [Adapter support matrix](docs/adapters/support-matrix.md).
-- Reference: [System architecture](docs/architecture/system-architecture.md), [workflow customization and execution controls](docs/reference/workflow-customization.md), [execution strategy](docs/reference/execution-strategy.md), [CLI reference](docs/reference/cli.md), [External verification checks](docs/reference/external-verification-checks.md), [Project domain language](docs/reference/project-domain-language.md), [Plan verification](docs/reference/plan-verification.md), [Research evidence](docs/reference/research-evidence.md), [Public locators and redaction](docs/reference/public-locators-and-redaction.md), [Finding-to-check adoption](docs/reference/finding-check-adoption.md), [Source of truth](docs/reference/source-of-truth.md), [Managed lifecycle runner](docs/reference/managed-lifecycle-runner.md), [Managed adapter sessions](docs/reference/managed-adapter-sessions.md), [Portable Agent Plugins](docs/reference/agent-plugins.md), [Plugin publication](docs/reference/plugin-publication.md), [Implementation audit](docs/reference/implementation-audit.md), [Plan completeness](docs/reference/plan-completeness.md), [Public contracts](docs/reference/public-contracts.md), and [Readiness diagnostics](docs/reference/readiness-diagnostics.md).
+- Reference: [System architecture](docs/architecture/system-architecture.md), [workflow customization and execution controls](docs/reference/workflow-customization.md), [execution strategy](docs/reference/execution-strategy.md), [CLI reference](docs/reference/cli.md), [External verification checks](docs/reference/external-verification-checks.md), [Project domain language](docs/reference/project-domain-language.md), [Multi-run attention view](docs/reference/multi-run-attention-view.md), [Plan verification](docs/reference/plan-verification.md), [Research evidence](docs/reference/research-evidence.md), [Public locators and redaction](docs/reference/public-locators-and-redaction.md), [Finding-to-check adoption](docs/reference/finding-check-adoption.md), [Source of truth](docs/reference/source-of-truth.md), [Managed lifecycle runner](docs/reference/managed-lifecycle-runner.md), [Managed adapter sessions](docs/reference/managed-adapter-sessions.md), [Portable Agent Plugins](docs/reference/agent-plugins.md), [Plugin publication](docs/reference/plugin-publication.md), [Implementation audit](docs/reference/implementation-audit.md), [Plan completeness](docs/reference/plan-completeness.md), [Public contracts](docs/reference/public-contracts.md), and [Readiness diagnostics](docs/reference/readiness-diagnostics.md).
 - Quality and resources: [Reference-task evaluation](docs/reference/reference-task-evaluation.md), [model routing](docs/reference/model-routing.md), [quality-cost learning](docs/reference/quality-cost-learning.md), [performance and resource budgets](docs/reference/performance-and-resource-budgets.md), [lifecycle cost accounting](docs/reference/lifecycle-cost.md), [host-local token accounting](docs/reference/host-local-token-accounting.md), [process execution observability](docs/reference/process-execution-observability.md), [Usage export](docs/reference/usage-export.md), and [Evidence integrity](docs/reference/evidence-integrity.md).
 - Profiles and operations: [Project workflow presets](docs/reference/workflow-presets.md), [Project workflow profile](docs/reference/project-workflow-profile.md), [Read-only status views](docs/reference/read-only-status-view.md), [Adapter progress bridge](docs/reference/automatic-progress-bridge.md), [Sandbox boundaries](docs/reference/sandbox-boundaries.md), [Import mappers](docs/reference/import-mappers.md), [Episode retrieval](docs/reference/episode-retrieval.md), [Runner migration](docs/guides/runner-migration-2.md), [Runner recovery records](docs/reference/runner-recovery.md), [Cross-check profile](docs/reference/cross-check-profile.md), [Review Mesh](docs/reference/review-mesh.md), [Risk-bound independent verification](docs/reference/risk-bound-independent-verification.md), [Bug Forensics profile](docs/reference/bug-forensics.md), and [Bug Forensics context budget](docs/reference/bug-forensics-context-budget.md).
 - Release assets: [Task templates](templates/tasks/README.md), [Neutrality scanning](docs/reference/neutrality.md), and [Release security](docs/security/release-security.md).

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.2.0"
+version = "2.3.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.2.0 → agent_lifecycle_kit-2.3.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.0}/src/agent_lifecycle/audit/ownership.py

@@ -53,6 +53,18 @@ def report_has_category(report: dict[str, Any], categories: set[str]) -> bool:
     return any(entry.get("category") in categories for entry in report.get("entries", []))
 
 
+def declared_ownership_paths(manifest: dict[str, Any]) -> list[str]:
+    """Return literal workstream ownership paths for read-only projections."""
+
+    classifiers = _classifiers(manifest, None)
+    paths = {
+        path
+        for roots in classifiers["workstreams"].values()
+        for path in roots
+    }
+    return sorted(paths)
+
+
 def _classifiers(manifest: dict[str, Any], manifest_path: Path | None) -> dict[str, Any]:
     package_value = manifest.get("package")
     package = package_value if isinstance(package_value, dict) else {}

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.0}/src/agent_lifecycle/cli/dispatch_observability.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import argparse
+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.context import check_context, load_context_profile, render_context
 from agent_lifecycle.context.checkpoint_store import (
     restore_context_checkpoint,
@@ -54,7 +56,6 @@ from agent_lifecycle.metrics.audit_optimization import (
     validate_audit_optimization_report,
 )
 from agent_lifecycle.metrics.audit_samples import build_audit_samples
-from agent_lifecycle.cli.dispatch_metrics import _dispatch_execution_report
 from agent_lifecycle.model_routing import (
     resolve_model_route,
     validate_host_model_profile,
@@ -70,6 +71,7 @@ from agent_lifecycle.reporting import (
     build_change_summary_receipt,
     build_lifecycle_progress_view,
     build_lifecycle_progress_watch,
+    build_multi_run_attention_view,
     build_progress_bridge_receipt,
     build_status_view,
     build_workflow_event_feed,
@@ -127,7 +129,8 @@ def _dispatch_thread(args: argparse.Namespace) -> dict[str, Any]:
                 "thread request and receipt lineage validation failed",
                 {"validation": validation},
             )
-        limits = request.get("limits") if isinstance(request.get("limits"), dict) else {}
+        raw_limits = request.get("limits")
+        limits: dict[str, Any] = raw_limits if isinstance(raw_limits, dict) else {}
         imported = prepare_thread_context_import(
             operation_id=request["operationId"],
             source_receipt_digest=receipt["receiptDigest"],
@@ -181,6 +184,18 @@ def _dispatch_report(args: argparse.Namespace) -> dict[str, Any] | str:
         if args.out:
             write_json_create(Path(args.out), payload)
         return payload
+    if args.report_command in {"multi-run", "attention"}:
+        payload = build_multi_run_attention_view(
+            project_root=Path(args.project_root),
+            run_roots=[Path(item) for item in args.run_root],
+            max_runs=args.max_runs,
+            max_bytes_per_run=args.max_bytes_per_run,
+            stale_after_seconds=args.stale_after_seconds,
+            now=_parse_report_time(args.now),
+        )
+        if args.out:
+            write_json_create(Path(args.out), payload)
+        return payload
     if args.report_command == "progress":
         if args.watch:
             payload = build_lifecycle_progress_watch(
@@ -215,6 +230,18 @@ def _dispatch_report(args: argparse.Namespace) -> dict[str, Any] | str:
     raise LifecycleError("command-not-implemented", "report command is not implemented")
 
 
+def _parse_report_time(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise LifecycleError("multi-run-invalid-time", "--now must be an ISO-8601 timestamp") from exc
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
 def _dispatch_context(args: argparse.Namespace) -> dict[str, Any]:
     if args.context_command == "profile-check":
         return load_context_profile(Path(args.profile))
@@ -328,7 +355,10 @@ def _dispatch_context_checkpoint(args: argparse.Namespace) -> dict[str, Any]:
 def _require_checkpoint_output_root(root: Path) -> None:
     resolved = root.resolve()
     if ".alk" not in resolved.parts or not resolved.name == "checkpoints":
-        raise LifecycleError("context-checkpoint-output-root-invalid", "checkpoint output must remain in a .alk/context/checkpoints directory")
+        raise LifecycleError(
+            "context-checkpoint-output-root-invalid",
+            "checkpoint output must remain in a .alk/context/checkpoints directory",
+        )
 
 
 def _dispatch_goal(args: argparse.Namespace) -> dict[str, Any] | str:
@@ -383,12 +413,20 @@ def _dispatch_model(args: argparse.Namespace) -> dict[str, Any]:
         return validate_model_routing_profile(profile)
     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
+        host_profile = (
+            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
+        decision = (
+            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)
         if result["status"] == "FAIL":
@@ -401,7 +439,7 @@ def _dispatch_model(args: argparse.Namespace) -> dict[str, Any]:
     raise LifecycleError("command-not-implemented", "model command is not implemented")
 
 
-def _dispatch_metrics(args: argparse.Namespace) -> dict[str, Any]:
+def _dispatch_metrics(args: argparse.Namespace) -> dict[str, Any] | str:
     if args.metrics_command == "cost-check":
         report = read_json_object(Path(args.receipt), label="lifecycle cost report")
         return require_lifecycle_cost_pass(validate_lifecycle_cost_report(report))
@@ -505,32 +543,15 @@ def _dispatch_metrics(args: argparse.Namespace) -> dict[str, Any]:
         write_json_create(Path(args.out), payload)
         return payload
     if args.metrics_command == "audit-report":
-        samples = _read_audit_samples(args.sample)
-        candidates = _read_json_items(args.candidate_profile, label="candidate profile")
-        references = _read_json_items(args.reference_task, label="reference task")
-        holdouts = _read_json_items(args.holdout_task, label="holdout task")
-        current = read_json_object(Path(args.current_profile), label="current optimization profile") if args.current_profile else None
-        report = build_audit_optimization_report(
-            samples,
-            candidate_profiles=candidates,
-            reference_tasks=references,
-            holdout_tasks=holdouts,
-            task_shape=args.task_shape,
-            quality_floor=args.quality_floor,
-            current_profile=current,
-        )
-        validation = validate_audit_optimization_report(report)
-        if validation["status"] != "PASS":
-            raise LifecycleError("audit-optimization-report-invalid", "audit optimization report validation failed", {"validation": validation})
-        write_json_create(Path(args.out), report)
-        if args.terminal:
-            return render_audit_optimization_terminal(report)
-        return report
+        return _dispatch_audit_report(args)
     if args.metrics_command == "audit-proposal":
         report = read_json_object(Path(args.report), label="audit optimization report")
-        recommendation = report.get("recommendation") if isinstance(report.get("recommendation"), dict) else {}
+        raw_recommendation = report.get("recommendation")
+        proposal_recommendation: dict[str, Any] = (
+            raw_recommendation if isinstance(raw_recommendation, dict) else {}
+        )
         proposal = build_optimization_proposal(
-            recommendation,
+            proposal_recommendation,
             approved=args.approved,
             target_kind=args.target_kind,
             target_revision=args.target_revision,
@@ -545,11 +566,44 @@ def _dispatch_metrics(args: argparse.Namespace) -> dict[str, Any]:
     raise LifecycleError("command-not-implemented", "metrics command is not implemented")
 
 
+def _dispatch_audit_report(args: argparse.Namespace) -> dict[str, Any] | str:
+    samples = _read_audit_samples(args.sample)
+    candidates = _read_json_items(args.candidate_profile, label="candidate profile")
+    references = _read_json_items(args.reference_task, label="reference task")
+    holdouts = _read_json_items(args.holdout_task, label="holdout task")
+    current = (
+        read_json_object(Path(args.current_profile), label="current optimization profile")
+        if args.current_profile
+        else None
+    )
+    report = build_audit_optimization_report(
+        samples,
+        candidate_profiles=candidates,
+        reference_tasks=references,
+        holdout_tasks=holdouts,
+        task_shape=args.task_shape,
+        quality_floor=args.quality_floor,
+        current_profile=current,
+    )
+    validation = validate_audit_optimization_report(report)
+    if validation["status"] != "PASS":
+        raise LifecycleError(
+            "audit-optimization-report-invalid",
+            "audit optimization report validation failed",
+            {"validation": validation},
+        )
+    write_json_create(Path(args.out), report)
+    if args.terminal:
+        return render_audit_optimization_terminal(report)
+    return report
+
+
 def _read_audit_samples(paths: list[str]) -> list[dict[str, Any]]:
     samples: list[dict[str, Any]] = []
     for item in paths:
         payload = read_json_object(Path(item), label="audit sample")
-        rows = payload.get("samples") if isinstance(payload.get("samples"), list) else [payload]
+        raw_samples = payload.get("samples")
+        rows = raw_samples if isinstance(raw_samples, list) else [payload]
         samples.extend(row for row in rows if isinstance(row, dict))
     return samples
 
@@ -558,7 +612,8 @@ def _read_json_items(paths: list[str], *, label: str) -> list[dict[str, Any]]:
     items: list[dict[str, Any]] = []
     for item in paths:
         payload = read_json_object(Path(item), label=label)
-        rows = payload if isinstance(payload, list) else payload.get("items") if isinstance(payload.get("items"), list) else [payload]
+        raw_items = payload.get("items")
+        rows = raw_items if isinstance(raw_items, list) else [payload]
         items.extend(row for row in rows if isinstance(row, dict))
     return items
 

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.0}/src/agent_lifecycle/cli/observability_parsers.py

@@ -17,6 +17,14 @@ def _add_report_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentP
     event_feed = report_sub.add_parser("event-feed")
     event_feed.add_argument("--state", required=True)
     event_feed.add_argument("--out")
+    multi_run = report_sub.add_parser("multi-run", aliases=["attention"])
+    multi_run.add_argument("--project-root", default=".")
+    multi_run.add_argument("--run-root", "--run", dest="run_root", action="append", default=[])
+    multi_run.add_argument("--max-runs", type=int, default=32)
+    multi_run.add_argument("--max-bytes-per-run", type=int, default=1_048_576)
+    multi_run.add_argument("--stale-after-seconds", type=int, default=86_400)
+    multi_run.add_argument("--now")
+    multi_run.add_argument("--out")
     progress = report_sub.add_parser("progress")
     progress.add_argument("--state", required=True)
     progress.add_argument("--usage-receipt", action="append", default=[])

agent_lifecycle_kit-2.3.0/src/agent_lifecycle/contracts/multi_run_view_schemas.py

@@ -0,0 +1,114 @@
+"""Contracts for bounded, read-only views over several lifecycle runs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts.schema_builders import open_object_schema
+
+_DIGEST = {"type": "string", "minLength": 64, "maxLength": 64}
+_BLOCKERS = {"type": "array", "items": {"type": "object"}, "maxItems": 64}
+
+MULTI_RUN_ATTENTION_ITEM_SCHEMA = "agent-multi-run-attention-item.v1"
+MULTI_RUN_OVERLAP_SCHEMA = "agent-multi-run-overlap.v1"
+MULTI_RUN_VIEW_SCHEMA = "agent-multi-run-attention-view.v1"
+
+MULTI_RUN_VIEW_SCHEMAS: dict[str, dict[str, Any]] = {
+    MULTI_RUN_ATTENTION_ITEM_SCHEMA: open_object_schema(
+        MULTI_RUN_ATTENTION_ITEM_SCHEMA,
+        required=[
+            "schemaVersion",
+            "itemId",
+            "reasonCode",
+            "severity",
+            "runId",
+            "packageId",
+            "planRevision",
+            "planDigest",
+            "sourceRevision",
+            "stateRevision",
+        ],
+        properties={
+            "itemId": {"type": "string", "minLength": 1, "maxLength": 256},
+            "reasonCode": {"enum": [
+                "BLOCKER_PRESENT",
+                "USER_ACTION_REQUIRED",
+                "PENDING_REVIEW",
+                "STALE_ATTEMPT",
+                "FAILED_EVIDENCE",
+                "TERMINAL_RUN",
+                "SOURCE_UNAVAILABLE",
+            ]},
+            "severity": {"enum": ["HIGH", "MEDIUM", "LOW", "INFO"]},
+            "runId": {"type": "string", "minLength": 1},
+            "packageId": {"type": ["string", "null"]},
+            "planRevision": {"type": ["integer", "null"], "minimum": 0},
+            "planDigest": {"type": ["string", "null"], "minLength": 0, "maxLength": 64},
+            "sourceRevision": {"type": ["string", "null"]},
+            "stateRevision": {"type": ["integer", "null"], "minimum": 1},
+            "taskId": {"type": ["string", "null"]},
+            "phase": {"type": ["string", "null"]},
+            "message": {"type": "string", "maxLength": 512},
+            "sourcePath": {"type": ["string", "null"]},
+            "blockerCode": {"type": ["string", "null"]},
+        },
+    ),
+    MULTI_RUN_OVERLAP_SCHEMA: open_object_schema(
+        MULTI_RUN_OVERLAP_SCHEMA,
+        required=["schemaVersion", "overlapId", "path", "runIds", "authorityRetained"],
+        properties={
+            "overlapId": {"type": "string", "minLength": 1, "maxLength": 256},
+            "path": {"type": "string", "minLength": 1},
+            "runIds": {"type": "array", "minItems": 2, "items": {"type": "string", "minLength": 1}},
+            "packageIds": {"type": "array", "items": {"type": "string", "minLength": 1}},
+            "planRevisions": {"type": "array", "items": {"type": "integer", "minimum": 0}},
+            "authorityRetained": {"const": True},
+            "reasonCode": {"const": "DECLARED_PATH_OVERLAP"},
+        },
+    ),
+    MULTI_RUN_VIEW_SCHEMA: open_object_schema(
+        MULTI_RUN_VIEW_SCHEMA,
+        required=[
+            "schemaVersion",
+            "status",
+            "sourceOfTruth",
+            "readOnly",
+            "modelCallsStarted",
+            "stateWritten",
+            "projectRoot",
+            "sourceCount",
+            "sources",
+            "attentionItems",
+            "overlaps",
+            "blockers",
+            "productionPromotionClaimed",
+            "viewDigest",
+        ],
+        properties={
+            "status": {"enum": ["PASS", "FAIL"]},
+            "sourceOfTruth": {"const": False},
+            "readOnly": {"const": True},
+            "modelCallsStarted": {"const": False},
+            "stateWritten": {"const": False},
+            "projectRoot": {"const": "<checkout>"},
+            "sourceCount": {"type": "integer", "minimum": 0},
+            "successfulSourceCount": {"type": "integer", "minimum": 0},
+            "failedSourceCount": {"type": "integer", "minimum": 0},
+            "sources": {"type": "array", "items": {"type": "object"}},
+            "attentionItems": {"type": "array", "items": {"type": "object"}},
+            "overlaps": {"type": "array", "items": {"type": "object"}},
+            "blockers": _BLOCKERS,
+            "limits": {"type": "object"},
+            "productionPromotionClaimed": {"const": False},
+            "viewDigest": _DIGEST,
+        },
+    ),
+}
+
+
+__all__ = [
+    "MULTI_RUN_ATTENTION_ITEM_SCHEMA",
+    "MULTI_RUN_OVERLAP_SCHEMA",
+    "MULTI_RUN_VIEW_SCHEMA",
+    "MULTI_RUN_VIEW_SCHEMAS",
+]

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.0}/src/agent_lifecycle/contracts/schemas.py

@@ -49,6 +49,7 @@ from agent_lifecycle.contracts.lifecycle_control_definitions import (
     QUALIFICATION_STATUSES,
 )
 from agent_lifecycle.contracts.metric_schemas import METRIC_SCHEMAS
+from agent_lifecycle.contracts.multi_run_view_schemas import MULTI_RUN_VIEW_SCHEMAS
 from agent_lifecycle.contracts.plan_contract_schemas import PLAN_CONTRACT_SCHEMAS
 from agent_lifecycle.contracts.plan_delta_schemas import PLAN_DELTA_SCHEMAS
 from agent_lifecycle.contracts.plan_manifest_schemas import PLAN_MANIFEST_SCHEMAS
@@ -752,6 +753,7 @@ _SCHEMA_GROUPS = (
     PLAN_DELTA_SCHEMAS,
     PLANNING_LAUNCH_SCHEMAS,
     METRIC_SCHEMAS,
+    MULTI_RUN_VIEW_SCHEMAS,
     POLICY_SCHEMAS,
     LIFECYCLE_START_SCHEMAS,
     RISK_EXECUTION_SCHEMAS,

{agent_lifecycle_kit-2.2.0 → agent_lifecycle_kit-2.3.0}/src/agent_lifecycle/reporting/__init__.py

@@ -1,7 +1,9 @@
 """Read-only reporting views over existing lifecycle artifacts."""
 
-from agent_lifecycle.reporting.event_feed import build_workflow_event_feed
+from agent_lifecycle.reporting.attention import build_attention_projection, build_multi_run_overlap
 from agent_lifecycle.reporting.change_summary import build_change_summary_receipt
+from agent_lifecycle.reporting.event_feed import build_workflow_event_feed
+from agent_lifecycle.reporting.multi_run import build_multi_run_attention_view, build_multi_run_view
 from agent_lifecycle.reporting.progress_bridge import (
     build_progress_bridge_config,
     build_progress_bridge_receipt,
@@ -12,23 +14,27 @@ from agent_lifecycle.reporting.progress_hooks import (
     build_progress_hook_receipt,
     write_progress_hook_receipt,
 )
-from agent_lifecycle.reporting.progress_view import build_lifecycle_progress_view, build_lifecycle_progress_watch
 from agent_lifecycle.reporting.progress_terminal import render_goal_view_terminal, render_progress_terminal
+from agent_lifecycle.reporting.progress_view import build_lifecycle_progress_view, build_lifecycle_progress_watch
 from agent_lifecycle.reporting.status_view import build_status_view, require_status_view_pass
 from agent_lifecycle.reporting.usage_export import render_usage_export_json, render_usage_export_table
 
 __all__ = [
+    "build_attention_projection",
     "build_change_summary_receipt",
     "build_lifecycle_progress_view",
     "build_lifecycle_progress_watch",
+    "build_multi_run_attention_view",
+    "build_multi_run_overlap",
+    "build_multi_run_view",
     "build_progress_bridge_config",
     "build_progress_bridge_receipt",
     "build_progress_hook_policy",
     "build_progress_hook_receipt",
     "build_status_view",
     "build_workflow_event_feed",
-    "render_progress_bridge_terminal",
     "render_goal_view_terminal",
+    "render_progress_bridge_terminal",
     "render_progress_terminal",
     "render_usage_export_json",
     "render_usage_export_table",