agent-lifecycle-kit 2.9.0__tar.gz → 2.11.0__tar.gz

{agent_lifecycle_kit-2.9.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.9.0
+Version: 2.11.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.9.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.11.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), and cross session boundaries with the bounded [phase-to-session handoff](docs/guides/phase-session-handoff.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), 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.9.0 → agent_lifecycle_kit-2.11.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.9.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.11.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), and cross session boundaries with the bounded [phase-to-session handoff](docs/guides/phase-session-handoff.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), 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.9.0 → agent_lifecycle_kit-2.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.9.0"
+version = "2.11.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"
@@ -41,9 +41,9 @@ dependencies = []
 
 [dependency-groups]
 quality = [
-  "ruff==0.16.3",
-  "mypy==1.17.1",
-  "coverage==7.10.6",
+  "ruff==0.16.5",
+  "mypy==2.3.1",
+  "coverage==7.15.4",
 ]
 
 [project.scripts]

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.11.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.9.0"
+__version__ = "2.11.0"

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.11.0}/src/agent_lifecycle/cli/dispatch_lifecycle.py

@@ -21,7 +21,15 @@ from agent_lifecycle.cli.progress_hooks import (
     maybe_emit_workflow_progress_hook,
     validate_workflow_progress_hook_request,
 )
-from agent_lifecycle.contracts import LifecycleError, read_json_object, write_json_create
+from agent_lifecycle.compiler import build_phase_packet
+from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object, write_json_create
+from agent_lifecycle.contracts.phase_packet_schemas import (
+    IMPLEMENTATION_PAYLOAD_SCHEMA,
+    REMEDIATION_PAYLOAD_SCHEMA,
+    TASK_AUDIT_PAYLOAD_SCHEMA,
+)
+from agent_lifecycle.freeze import verify_plan_lock
+from agent_lifecycle.quality import build_validation_selection
 from agent_lifecycle.workflow import (
     accept_task,
     adopt_plan,
@@ -32,6 +40,7 @@ from agent_lifecycle.workflow import (
     block_run,
     commit_task_result,
     continue_workflow,
+    continue_workflow_batch,
     finalize_run,
     initialize_workflow_state,
     migrate_workflow_state,
@@ -91,6 +100,8 @@ def _dispatch_workflow(args: argparse.Namespace) -> dict[str, Any]:
         return status(state_path, full=args.full)
     if args.workflow_command == "next":
         return next_action(status(state_path, full=True)["state"])
+    if args.workflow_command == "validation-select":
+        return _dispatch_validation_select(args, state_path)
     if args.workflow_command == "run":
         validate_workflow_progress_hook_request(args, command="workflow run")
         payload = run_workflow_step(
@@ -107,22 +118,7 @@ def _dispatch_workflow(args: argparse.Namespace) -> dict[str, Any]:
         maybe_emit_workflow_progress_hook(args, command="workflow run", state_path=state_path)
         return payload
     if args.workflow_command == "continue":
-        payload = continue_workflow(
-            state_path=state_path,
-            manifest_path=Path(args.manifest),
-            lock_path=Path(args.lock) if args.lock else None,
-            operation_id=args.operation_id,
-            expected_revision=args.expected_revision,
-            source_revision=args.source_revision,
-            reason=args.reason,
-            apply=args.apply,
-            projected_state_revision=args.projected_state_revision,
-            projected_action_digest=args.projected_action_digest,
-            inputs=_continuation_inputs(args),
-        )
-        if args.out:
-            write_json_create(Path(args.out), payload)
-        return payload
+        return _dispatch_workflow_continue(args, state_path)
     if args.workflow_command == "adopt-plan":
         return adopt_plan(
             state_path,
@@ -198,6 +194,7 @@ def _dispatch_workflow(args: argparse.Namespace) -> dict[str, Any]:
             follow_up_register_path=args.follow_up_register,
             completion_gate_receipt_path=args.completion_gate_receipt,
             final_implementation_audit_path=args.final_implementation_audit,
+            release_full_receipt_path=args.release_full_receipt,
             review_mesh_quorum_paths=args.review_mesh_quorum,
             reason=args.reason,
         )
@@ -208,10 +205,7 @@ def _dispatch_workflow(args: argparse.Namespace) -> dict[str, Any]:
 
 def _dispatch_workflow_task(args: argparse.Namespace, state_path: Path) -> dict[str, Any]:
     if args.workflow_command == "task-snapshot":
-        payload = build_current_task_change_set(state_path, task_id=args.task)
-        if args.out:
-            write_json_create(Path(args.out), payload)
-        return payload
+        return _dispatch_task_snapshot(args, state_path)
     if args.workflow_command == "block":
         return block_run(
             state_path,
@@ -337,12 +331,360 @@ def _dispatch_workflow_task(args: argparse.Namespace, state_path: Path) -> dict[
     raise LifecycleError("command-not-implemented", "workflow command is not implemented")
 
 
+def _dispatch_task_snapshot(args: argparse.Namespace, state_path: Path) -> dict[str, Any]:
+    packet_args = (args.manifest, args.lock, args.phase_packet_purpose, args.phase_packet_out)
+    packet_requested = any(value is not None for value in packet_args)
+    if packet_requested and not all(value is not None for value in packet_args):
+        raise LifecycleError(
+            "phase-packet-required-fact-missing",
+            "task snapshot phase packet requires --manifest, --lock, --phase-packet-purpose and --phase-packet-out",
+        )
+    state = read_json_object(state_path, label="workflow state") if packet_requested else None
+    task = _state_task(state, args.task) if isinstance(state, dict) else None
+    if args.phase_packet_purpose == "TASK_AUDIT" and isinstance(task, dict) and task.get("status") == "VERIFYING":
+        assert state is not None
+        payload = _result_bound_task_change_set(state, task)
+    else:
+        payload = build_current_task_change_set(state_path, task_id=args.task)
+    if args.out:
+        write_json_create(Path(args.out), payload)
+    if packet_requested:
+        assert state is not None
+        manifest = read_json_object(Path(args.manifest), label="plan manifest")
+        lock = read_json_object(Path(args.lock), label="plan lock")
+        verify_plan_lock(manifest, lock)
+        packet = _build_task_phase_packet(
+            manifest=manifest,
+            lock=lock,
+            state=state,
+            task_id=args.task,
+            purpose=args.phase_packet_purpose,
+            snapshot=payload,
+        )
+        write_json_create(Path(args.phase_packet_out), packet)
+    return payload
+
+
+def _result_bound_task_change_set(state: dict[str, Any], task: dict[str, Any]) -> dict[str, Any]:
+    evidence = task.get("resultChangeSetEvidence")
+    if not isinstance(evidence, dict):
+        raise LifecycleError("phase-packet-required-fact-missing", "task audit result change-set evidence is missing")
+    required = ("provider", "baselineSha", "fileSetHash", "diffHash", "snapshotHash")
+    if any(not isinstance(evidence.get(field), str) or not evidence[field] for field in required):
+        raise LifecycleError(
+            "phase-packet-required-fact-missing", "task audit result change-set evidence is incomplete"
+        )
+    return {
+        **evidence,
+        "runId": state.get("runId"),
+        "packageId": state.get("packageId"),
+        "taskId": task.get("id"),
+        "attempt": task.get("attempt"),
+        "planDigest": state.get("planDigest"),
+        "sourceRevision": state.get("sourceRevision"),
+        "readOnly": True,
+        "stateWritten": False,
+        "modelCallsStarted": False,
+        "productionPromotionClaimed": False,
+        "claim": {
+            "schemaVersion": "agent-task-change-set-claim.v1",
+            **{key: evidence[key] for key in required},
+        },
+    }
+
+
+def _dispatch_validation_select(args: argparse.Namespace, state_path: Path) -> dict[str, Any]:
+    state = read_json_object(state_path, label="workflow state")
+    task = _state_task(state, args.task)
+    snapshot = read_json_object(Path(args.snapshot), label="task snapshot")
+    if snapshot.get("taskId") != task.get("id"):
+        raise LifecycleError("task-snapshot-lineage-mismatch", "task snapshot does not match the requested task")
+    payload = build_validation_selection(
+        manifest=read_json_object(Path(args.manifest), label="plan manifest"),
+        lock=read_json_object(Path(args.lock), label="plan lock"),
+        state=state,
+        snapshot=snapshot,
+        repository_root=Path.cwd(),
+    )
+    if args.out:
+        write_json_create(Path(args.out), payload)
+    return payload
+
+
+def _build_task_phase_packet(
+    *,
+    manifest: dict[str, Any],
+    lock: dict[str, Any],
+    state: dict[str, Any],
+    task_id: str,
+    purpose: str,
+    snapshot: dict[str, Any],
+) -> dict[str, Any]:
+    task = _state_task(state, task_id)
+    workstream = _manifest_workstream(manifest, task_id)
+    plan_digest = canonical_digest(manifest)
+    if state.get("planDigest") != plan_digest:
+        raise LifecycleError("phase-packet-required-fact-missing", "workflow state plan lineage is stale")
+    attempt = task.get("attempt")
+    if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1:
+        raise LifecycleError("phase-packet-required-fact-missing", "task attempt is required")
+    writes = _task_scope(manifest, workstream, task, "writes")
+    read_only = _task_scope(manifest, workstream, task, "readOnly")
+    forbidden = _task_scope(manifest, workstream, task, "forbiddenWrites")
+    acceptance = _task_acceptance(manifest, workstream)
+    evidence = _task_evidence(workstream)
+    active_blockers = _task_active_blockers(state, task)
+    payload = _task_phase_payload(
+        purpose=purpose,
+        manifest=manifest,
+        task=task,
+        task_id=task_id,
+        attempt=attempt,
+        snapshot=snapshot,
+        writes=writes,
+        read_only=read_only,
+        forbidden=forbidden,
+        acceptance=acceptance,
+        evidence=evidence,
+        active_blockers=active_blockers,
+    )
+    state_revision = state.get("stateRevision")
+    source_revision = state.get("sourceRevision")
+    if not isinstance(state_revision, int) or isinstance(state_revision, bool) or state_revision < 1:
+        raise LifecycleError("phase-packet-required-fact-missing", "workflow state revision is required")
+    if not isinstance(source_revision, str) or not source_revision:
+        raise LifecycleError("phase-packet-required-fact-missing", "workflow source revision is required")
+    return build_phase_packet(
+        purpose=purpose,
+        payload=payload,
+        plan_digest=plan_digest,
+        plan_lock_digest=canonical_digest(lock),
+        state_revision=state_revision,
+        source_revision=source_revision,
+        write_scope_digest=canonical_digest({"writes": writes, "readOnly": read_only, "forbiddenWrites": forbidden}),
+        acceptance_digest=canonical_digest(acceptance),
+        evidence_digest=canonical_digest(evidence),
+        active_blocker_ids=active_blockers,
+    )
+
+
+def _task_phase_payload(
+    *,
+    purpose: str,
+    manifest: dict[str, Any],
+    task: dict[str, Any],
+    task_id: str,
+    attempt: int,
+    snapshot: dict[str, Any],
+    writes: list[str],
+    read_only: list[str],
+    forbidden: list[str],
+    acceptance: list[dict[str, Any]],
+    evidence: list[dict[str, Any]],
+    active_blockers: list[str],
+) -> dict[str, Any]:
+    common = {
+        "taskId": task_id,
+        "attempt": attempt,
+        "writes": writes,
+        "readOnly": read_only,
+        "forbiddenWrites": forbidden,
+        "acceptanceCriteria": acceptance,
+        "activeBlockerIds": active_blockers,
+    }
+    if purpose == "IMPLEMENTATION":
+        packet = task.get("packet")
+        task_packet_digest = packet.get("sha256") if isinstance(packet, dict) else None
+        return {
+            "schemaVersion": IMPLEMENTATION_PAYLOAD_SCHEMA,
+            **common,
+            "taskPacketDigest": task_packet_digest,
+            "evidenceRequirements": evidence,
+        }
+    changed_paths = _task_strings(snapshot.get("changedFiles"))
+    if purpose == "TASK_AUDIT":
+        result = task.get("result")
+        result_digest = result.get("sha256") if isinstance(result, dict) else None
+        return {
+            "schemaVersion": TASK_AUDIT_PAYLOAD_SCHEMA,
+            **common,
+            "resultDigest": result_digest,
+            "changeSetDigest": snapshot.get("snapshotHash"),
+            "changedPaths": changed_paths,
+            "reviewRequirements": {
+                "independentRequired": True,
+                "minimumVerdict": "ACCEPTED",
+                "requiredReviewerIds": _required_reviewer_ids(task),
+            },
+            "evidenceReferences": [item["id"] for item in evidence],
+        }
+    if purpose != "REMEDIATION":
+        raise LifecycleError("phase-packet-required-fact-missing", "phase packet purpose is unsupported")
+    history = task.get("attemptHistory")
+    prior = history[-1] if isinstance(history, list) and history and isinstance(history[-1], dict) else None
+    prior_result = prior.get("result") if isinstance(prior, dict) else None
+    prior_review = prior.get("review") if isinstance(prior, dict) else None
+    return {
+        "schemaVersion": REMEDIATION_PAYLOAD_SCHEMA,
+        **common,
+        "priorResultDigest": prior_result.get("sha256") if isinstance(prior_result, dict) else None,
+        "priorReviewDigest": prior_review.get("sha256") if isinstance(prior_review, dict) else None,
+        "changedPaths": changed_paths,
+        "openFindingIds": _task_strings(task.get("remediationFindingIds")),
+        "remainingAttempts": max(1, _max_task_attempts(manifest) - attempt + 1),
+        "evidenceRequirements": evidence,
+    }
+
+
+def _state_task(state: dict[str, Any], task_id: str) -> dict[str, Any]:
+    tasks = state.get("tasks")
+    if isinstance(tasks, list):
+        for task in tasks:
+            if isinstance(task, dict) and task.get("id") == task_id:
+                return task
+    raise LifecycleError("task-not-found", "workflow task does not exist", {"taskId": task_id})
+
+
+def _manifest_workstream(manifest: dict[str, Any], task_id: str) -> dict[str, Any]:
+    workstreams = manifest.get("workstreams")
+    if isinstance(workstreams, list):
+        for workstream in workstreams:
+            if isinstance(workstream, dict) and workstream.get("id") == task_id:
+                return workstream
+    raise LifecycleError("phase-packet-required-fact-missing", "manifest workstream is missing", {"taskId": task_id})
+
+
+def _task_acceptance(manifest: dict[str, Any], workstream: dict[str, Any]) -> list[dict[str, Any]]:
+    acceptance = manifest.get("acceptance")
+    criteria = acceptance.get("criteria") if isinstance(acceptance, dict) else []
+    criteria = criteria if isinstance(criteria, list) else []
+    by_id = {item.get("id"): item for item in criteria if isinstance(item, dict) and isinstance(item.get("id"), str)}
+    return [dict(by_id.get(item, {"id": item})) for item in _task_strings(workstream.get("acceptanceIds"))]
+
+
+def _task_evidence(workstream: dict[str, Any]) -> list[dict[str, Any]]:
+    return [{"id": item, "required": True} for item in _task_strings(workstream.get("evidenceIds"))]
+
+
+def _task_scope(manifest: dict[str, Any], workstream: dict[str, Any], task: dict[str, Any], field: str) -> list[str]:
+    return sorted(
+        set(_task_strings(manifest.get(field)) + _task_strings(workstream.get(field)) + _task_strings(task.get(field)))
+    )
+
+
+def _task_active_blockers(state: dict[str, Any], task: dict[str, Any]) -> list[str]:
+    blockers = _task_strings(task.get("remediationFindingIds"))
+    blocker = state.get("blocker")
+    if isinstance(blocker, dict):
+        value = blocker.get("id") or blocker.get("code")
+        if isinstance(value, str) and value:
+            blockers.append(value)
+    return sorted(set(blockers))
+
+
+def _required_reviewer_ids(task: dict[str, Any]) -> list[str]:
+    reviewer = task.get("reviewer")
+    if isinstance(reviewer, str) and reviewer:
+        return [reviewer]
+    if isinstance(reviewer, dict) and isinstance(reviewer.get("id"), str) and reviewer["id"]:
+        return [reviewer["id"]]
+    return []
+
+
+def _max_task_attempts(manifest: dict[str, Any]) -> int:
+    orchestration = manifest.get("orchestration")
+    value = orchestration.get("maxTaskAttempts") if isinstance(orchestration, dict) else None
+    return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else 1
+
+
+def _task_strings(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return sorted({item for item in value if isinstance(item, str) and item})
+
+
 def _require_args(args: argparse.Namespace, names: list[str], *, mode: str) -> None:
     missing = [name.replace("_", "-") for name in names if not getattr(args, name, None)]
     if missing:
         raise LifecycleError("missing-cli-argument", f"{mode} requires arguments", {"missing": missing})
 
 
+def _dispatch_workflow_continue(args: argparse.Namespace, state_path: Path) -> dict[str, Any]:
+    batch_options = (args.input_bundle, args.max_transitions, args.max_io_bytes, args.resume_receipt)
+    if not args.until_blocked:
+        if any(value is not None for value in batch_options):
+            raise LifecycleError(
+                "continuation-batch-option-conflict",
+                "bounded continuation options require --until-blocked",
+            )
+        if not args.operation_id:
+            raise LifecycleError(
+                "continuation-one-step-operation-id-required",
+                "one-step continuation requires --operation-id",
+            )
+        payload = continue_workflow(
+            state_path=state_path,
+            manifest_path=Path(args.manifest),
+            lock_path=Path(args.lock) if args.lock else None,
+            operation_id=args.operation_id,
+            expected_revision=args.expected_revision,
+            source_revision=args.source_revision,
+            reason=args.reason,
+            apply=args.apply,
+            projected_state_revision=args.projected_state_revision,
+            projected_action_digest=args.projected_action_digest,
+            inputs=_continuation_inputs(args),
+        )
+        if args.out:
+            write_json_create(Path(args.out), payload)
+        return payload
+    if not args.apply:
+        raise LifecycleError(
+            "continuation-batch-apply-required",
+            "bounded continuation requires --apply",
+        )
+    if (
+        args.operation_id is not None
+        or args.projected_state_revision is not None
+        or args.projected_action_digest is not None
+    ):
+        raise LifecycleError(
+            "continuation-batch-option-conflict",
+            "bounded continuation cannot use singular operation or projection options",
+        )
+    if _continuation_inputs(args):
+        raise LifecycleError(
+            "continuation-batch-option-conflict",
+            "bounded continuation inputs must come from --input-bundle",
+        )
+    required = ("lock", "input_bundle", "max_transitions", "max_io_bytes", "out")
+    missing = [name.replace("_", "-") for name in required if getattr(args, name) is None or getattr(args, name) == ""]
+    if missing:
+        raise LifecycleError(
+            "continuation-batch-arguments-required",
+            "bounded continuation requires explicit lock, bundle, caps and output",
+            {"missing": missing},
+        )
+    if args.max_transitions <= 0 or args.max_io_bytes <= 0:
+        raise LifecycleError(
+            "continuation-batch-cap-invalid",
+            "bounded continuation caps must be positive",
+        )
+    return continue_workflow_batch(
+        state_path=state_path,
+        manifest_path=Path(args.manifest),
+        lock_path=Path(args.lock),
+        input_bundle_path=args.input_bundle,
+        output_path=args.out,
+        max_transitions=args.max_transitions,
+        max_io_bytes=args.max_io_bytes,
+        expected_revision=args.expected_revision,
+        source_revision=args.source_revision,
+        reason=args.reason,
+        resume_receipt_path=args.resume_receipt,
+    )
+
+
 def _continuation_inputs(args: argparse.Namespace) -> dict[str, Any]:
     singular = {
         "taskId": args.task,

{agent_lifecycle_kit-2.9.0 → agent_lifecycle_kit-2.11.0}/src/agent_lifecycle/cli/dispatch_planning.py

@@ -7,9 +7,10 @@ from pathlib import Path
 from typing import Any
 
 from agent_lifecycle.cli.plan_lock_commands import create_reviewed_plan_lock
-from agent_lifecycle.compiler import compile_small_model_packets, compile_task_packets
+from agent_lifecycle.compiler import build_phase_packet, compile_small_model_packets, compile_task_packets
 from agent_lifecycle.contracts import (
     LifecycleError,
+    canonical_digest,
     read_json_object,
     write_json_create,
 )
@@ -18,6 +19,7 @@ from agent_lifecycle.contracts.finding_check_schemas import (
     validate_finding_check_evidence,
     validate_finding_check_proposal,
 )
+from agent_lifecycle.contracts.phase_packet_schemas import PLANNING_HANDOFF_PAYLOAD_SCHEMA
 from agent_lifecycle.freeze import verify_plan_lock
 from agent_lifecycle.planning import (
     build_plan_delta,
@@ -181,6 +183,25 @@ def _dispatch_plan(args: argparse.Namespace) -> dict[str, Any]:
             )
         if args.out:
             write_json_create(Path(args.out), payload)
+        if args.phase_packet_out:
+            if not args.snapshot or not args.lock:
+                raise LifecycleError(
+                    "phase-packet-required-fact-missing",
+                    "plan handoff phase packet requires --snapshot and --lock",
+                )
+            lock = read_json_object(Path(args.lock), label="plan lock")
+            verify_plan_lock(manifest, lock)
+            packet = _build_planning_handoff_phase_packet(
+                manifest,
+                lock,
+                handoff_snapshot,
+                selected_workstream_ids=[
+                    item["id"]
+                    for item in payload.get("workstreams", [])
+                    if isinstance(item, dict) and isinstance(item.get("id"), str)
+                ],
+            )
+            write_json_create(Path(args.phase_packet_out), packet)
         return payload
     if args.plan_command == "delta":
 
@@ -215,6 +236,103 @@ def _dispatch_plan(args: argparse.Namespace) -> dict[str, Any]:
     raise LifecycleError("command-not-implemented", "plan command is not implemented")
 
 
+def _build_planning_handoff_phase_packet(
+    manifest: dict[str, Any],
+    lock: dict[str, Any],
+    snapshot: dict[str, Any] | None,
+    *,
+    selected_workstream_ids: list[str],
+) -> dict[str, Any]:
+    if not isinstance(snapshot, dict):
+        raise LifecycleError("phase-packet-required-fact-missing", "plan handoff snapshot is required")
+    all_workstreams = [item for item in manifest.get("workstreams", []) if isinstance(item, dict)]
+    by_id = {item.get("id"): item for item in all_workstreams if isinstance(item.get("id"), str)}
+    selected: list[dict[str, Any]] = []
+    for workstream_id in selected_workstream_ids:
+        workstream = by_id.get(workstream_id)
+        if not isinstance(workstream, dict):
+            raise LifecycleError(
+                "phase-packet-required-fact-missing",
+                "plan handoff selected an unknown workstream",
+                {"workstreamId": workstream_id},
+            )
+        acceptance = _phase_acceptance(manifest, workstream)
+        evidence = _phase_evidence(workstream)
+        selected.append(
+            {
+                "id": workstream_id,
+                "dependsOn": _string_list(workstream.get("dependsOn")),
+                "writes": _string_list(workstream.get("writes")),
+                "readOnly": _scope_list(manifest, workstream, "readOnly"),
+                "forbiddenWrites": _scope_list(manifest, workstream, "forbiddenWrites"),
+                "acceptanceCriteria": acceptance,
+                "evidenceRequirements": evidence,
+                "activeBlockerIds": _string_list(workstream.get("activeBlockerIds")),
+            }
+        )
+    payload = {
+        "schemaVersion": PLANNING_HANDOFF_PAYLOAD_SCHEMA,
+        "workstreams": selected,
+        "dependencyEdges": [
+            {"from": dependency, "to": item["id"]} for item in selected for dependency in item["dependsOn"]
+        ],
+    }
+    base_revision = manifest.get("baseRevision")
+    source_revision = None
+    if isinstance(base_revision, dict):
+        source_revision = base_revision.get("sha") or base_revision.get("ref")
+    if not isinstance(source_revision, str) or not source_revision:
+        source_revision = snapshot.get("sourceDigest")
+    if not isinstance(source_revision, str) or not source_revision:
+        raise LifecycleError("phase-packet-required-fact-missing", "plan handoff source revision is required")
+    acceptance = [criterion for item in selected for criterion in item["acceptanceCriteria"]]
+    evidence = [requirement for item in selected for requirement in item["evidenceRequirements"]]
+    blockers = [blocker for item in selected for blocker in item["activeBlockerIds"]]
+    scopes = [
+        {
+            "id": item["id"],
+            "writes": item["writes"],
+            "readOnly": item["readOnly"],
+            "forbiddenWrites": item["forbiddenWrites"],
+        }
+        for item in selected
+    ]
+    return build_phase_packet(
+        purpose="PLANNING_HANDOFF",
+        payload=payload,
+        plan_digest=canonical_digest(manifest),
+        plan_lock_digest=canonical_digest(lock),
+        state_revision=None,
+        source_revision=source_revision,
+        write_scope_digest=canonical_digest(scopes),
+        acceptance_digest=canonical_digest(acceptance),
+        evidence_digest=canonical_digest(evidence),
+        active_blocker_ids=blockers,
+    )
+
+
+def _phase_acceptance(manifest: dict[str, Any], workstream: dict[str, Any]) -> list[dict[str, Any]]:
+    acceptance = manifest.get("acceptance")
+    criteria = acceptance.get("criteria") if isinstance(acceptance, dict) else []
+    criteria = criteria if isinstance(criteria, list) else []
+    by_id = {item.get("id"): item for item in criteria if isinstance(item, dict) and isinstance(item.get("id"), str)}
+    return [dict(by_id.get(item, {"id": item})) for item in _string_list(workstream.get("acceptanceIds"))]
+
+
+def _phase_evidence(workstream: dict[str, Any]) -> list[dict[str, Any]]:
+    return [{"id": item, "required": True} for item in _string_list(workstream.get("evidenceIds"))]
+
+
+def _scope_list(manifest: dict[str, Any], workstream: dict[str, Any], field: str) -> list[str]:
+    return sorted(set(_string_list(manifest.get(field)) + _string_list(workstream.get(field))))
+
+
+def _string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return sorted({item for item in value if isinstance(item, str) and item})
+
+
 def _dispatch_finding_check(args: argparse.Namespace) -> dict[str, Any]:
     def read(path: str, label: str) -> dict[str, Any]:
         return read_json_object(Path(path), label=label)