agent-lifecycle-kit 2.18.0__tar.gz → 2.19.0__tar.gz

{agent_lifecycle_kit-2.18.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.18.0
+Version: 2.19.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
@@ -41,9 +41,9 @@ and secret handling stay in adapters or host-local profiles.
 ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.
 
 ## Quick start
-Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
+Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.18.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.19.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.18.0 → agent_lifecycle_kit-2.19.0}/README.md

@@ -19,9 +19,9 @@ and secret handling stay in adapters or host-local profiles.
 ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.
 
 ## Quick start
-Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
+Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.18.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.19.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.18.0 → agent_lifecycle_kit-2.19.0}/pyproject.toml

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

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.18.0"
+__version__ = "2.19.0"

{agent_lifecycle_kit-2.18.0 → agent_lifecycle_kit-2.19.0}/src/agent_lifecycle/cli/dispatch_contracts.py

@@ -85,7 +85,7 @@ def dispatch_contracts(args: argparse.Namespace) -> dict[str, Any]:
         return {"schemaVersion": "agent-lifecycle-version.v1", "version": __version__}
     if args.command == "schema":
         if args.schema_command == "list":
-            return list_schemas()
+            return list_schemas(scope=args.scope)
         if args.schema_command == "show":
             return get_schema(args.schema_id)
         raise LifecycleError("command-not-implemented", "schema command is not implemented")
@@ -369,9 +369,16 @@ def _dispatch_review_mesh(args: argparse.Namespace) -> dict[str, Any]:
             blocking=args.blocking,
             evidence_ids=args.evidence_id,
             out_dir=Path(args.out_dir) if args.out_dir else None,
+            review_input=read_json_object(Path(args.review_input)) if args.review_input else None,
+            repository_root=Path(args.repository_root),
+            authority_manifest=read_json_object(Path(args.manifest)) if args.manifest else None,
+            summary_output=Path(args.out) if args.out else None,
         )
         if args.out:
-            write_json_create(Path(args.out), payload)
+            output = Path(args.out)
+            if args.review_input and not output.is_absolute():
+                output = Path(args.repository_root) / output
+            write_json_create(output, payload)
         return payload
     if args.review_mesh_command == "assign":
         source = _review_mesh_source(args, code="review-mesh-assignment-source-missing", label="assignment")

{agent_lifecycle_kit-2.18.0 → agent_lifecycle_kit-2.19.0}/src/agent_lifecycle/cli/dispatch_planning.py

@@ -6,7 +6,7 @@ import argparse
 from pathlib import Path
 from typing import Any
 
-from agent_lifecycle.cli.plan_lock_commands import create_reviewed_plan_lock
+from agent_lifecycle.cli.plan_lock_commands import create_reviewed_plan_lock, prepare_freeze_candidate
 from agent_lifecycle.compiler import build_phase_packet, compile_small_model_packets, compile_task_packets
 from agent_lifecycle.contracts import (
     LifecycleError,
@@ -46,6 +46,12 @@ from agent_lifecycle.specification import (
     build_completion_gate_receipt,
     validate_specification,
 )
+from agent_lifecycle.workflow.artifact_builders import (
+    artifact_summary,
+    build_authored_artifact,
+    create_artifact,
+    inspect_artifact,
+)
 from agent_lifecycle.workflow.artifacts import build_finding_check_evidence_artifact
 
 
@@ -96,6 +102,12 @@ def _dispatch_specification(args: argparse.Namespace) -> dict[str, Any]:
 
 
 def _dispatch_plan(args: argparse.Namespace) -> dict[str, Any]:
+    if args.plan_command == "freeze-prepare":
+        return prepare_freeze_candidate(
+            manifest_path=args.manifest,
+            output_path=args.out,
+            repository_root=Path(args.repository_root),
+        )
     if args.plan_command == "lock-create":
         return create_reviewed_plan_lock(
             manifest_path=args.manifest,
@@ -125,27 +137,7 @@ def _dispatch_plan(args: argparse.Namespace) -> dict[str, Any]:
             write_json_create(Path(args.out), payload)
         return payload
     if args.plan_command == "verify":
-        manifest_path = Path(args.manifest)
-        manifest, lock, acceptance_markdown, workflow_state, package_root = load_verification_inputs(
-            manifest_path=manifest_path,
-            lock_path=Path(args.lock) if args.lock else None,
-            acceptance_path=Path(args.acceptance) if args.acceptance else None,
-            state_path=Path(args.state) if args.state else None,
-            package_root=Path(args.package_root) if args.package_root else None,
-        )
-        payload = build_plan_verification(
-            manifest,
-            manifest_path=manifest_path,
-            lock=lock,
-            acceptance_markdown=acceptance_markdown,
-            workflow_state=workflow_state,
-            repository_root=Path(args.repository_root),
-            package_root=package_root,
-        )
-        output_path = args.out or args.evidence
-        if output_path:
-            write_json_create(Path(output_path), payload)
-        return require_plan_verification_pass(payload)
+        return _verify_plan(args)
     if args.plan_command == "acceptance-check":
         manifest_path = Path(args.manifest)
         acceptance_path = Path(args.acceptance)
@@ -236,6 +228,33 @@ def _dispatch_plan(args: argparse.Namespace) -> dict[str, Any]:
     raise LifecycleError("command-not-implemented", "plan command is not implemented")
 
 
+def _verify_plan(args: argparse.Namespace) -> dict[str, Any]:
+    if args.compact and not args.out:
+        raise LifecycleError("plan-compact-output-required", "Compact display requires --out for the full receipt")
+    manifest_path = Path(args.manifest)
+    manifest, lock, markdown, state, package_root = load_verification_inputs(
+        manifest_path=manifest_path,
+        lock_path=Path(args.lock) if args.lock else None,
+        acceptance_path=Path(args.acceptance) if args.acceptance else None,
+        state_path=Path(args.state) if args.state else None,
+        package_root=Path(args.package_root) if args.package_root else None,
+    )
+    payload = build_plan_verification(
+        manifest,
+        manifest_path=manifest_path,
+        lock=lock,
+        acceptance_markdown=markdown,
+        workflow_state=state,
+        repository_root=Path(args.repository_root),
+        package_root=package_root,
+    )
+    output_path = args.out or args.evidence
+    if output_path:
+        write_json_create(Path(output_path), payload)
+    require_plan_verification_pass(payload)
+    return artifact_summary(Path(output_path), payload) if args.compact else payload
+
+
 def _build_planning_handoff_phase_packet(
     manifest: dict[str, Any],
     lock: dict[str, Any],
@@ -385,6 +404,18 @@ def _dispatch_finding_check(args: argparse.Namespace) -> dict[str, Any]:
 
 
 def _dispatch_task(args: argparse.Namespace) -> dict[str, Any]:
+    if args.task_command == "artifact-create":
+        value = build_authored_artifact(
+            read_json_object(Path(args.input)),
+            kind=args.kind,
+            redact_advisory=args.redact_advisory,
+            state=read_json_object(Path(args.state)) if args.state else None,
+            task_id=args.task,
+            repository_root=Path(args.repository_root),
+        )
+        return create_artifact(Path(args.out), value)
+    if args.task_command == "artifact-inspect":
+        return inspect_artifact(Path(args.input), max_display_bytes=args.max_display_bytes)
     if args.task_command == "compile":
         execution_strategy = (
             read_json_object(Path(args.strategy), label="execution strategy") if args.strategy else None

{agent_lifecycle_kit-2.18.0 → agent_lifecycle_kit-2.19.0}/src/agent_lifecycle/cli/lifecycle_parsers.py

@@ -121,7 +121,8 @@ def _add_diagnostics_parser(subparsers: argparse._SubParsersAction[argparse.Argu
 def _add_schema_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     schema = subparsers.add_parser("schema", help="inspect bundled JSON schemas")
     schema_sub = schema.add_subparsers(dest="schema_command", required=True)
-    schema_sub.add_parser("list")
+    schema_list = schema_sub.add_parser("list")
+    schema_list.add_argument("--scope", choices=["all", "core"], default="all")
     show = schema_sub.add_parser("show")
     show.add_argument("schema_id")
 
@@ -243,6 +244,8 @@ def _add_review_mesh_parser(subparsers: argparse._SubParsersAction[argparse.Argu
     prepare.add_argument("--evidence-id", action="append", default=[])
     prepare.add_argument("--out-dir")
     prepare.add_argument("--out")
+    prepare.add_argument("--review-input", help="explicit source-bound portable reading inventory")
+    prepare.add_argument("--repository-root", default=".")
     assign = review_mesh_sub.add_parser("assign")
     assign_source = assign.add_mutually_exclusive_group(required=True)
     assign_source.add_argument("--manifest")

{agent_lifecycle_kit-2.18.0 → agent_lifecycle_kit-2.19.0}/src/agent_lifecycle/cli/parsers.py

@@ -174,11 +174,9 @@ def _add_diagnostics_parser(subparsers: argparse._SubParsersAction[argparse.Argu
 
 
 def _add_schema_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    schema = subparsers.add_parser("schema", help="inspect bundled JSON schemas")
-    schema_sub = schema.add_subparsers(dest="schema_command", required=True)
-    schema_sub.add_parser("list")
-    show = schema_sub.add_parser("show")
-    show.add_argument("schema_id")
+    from agent_lifecycle.cli.lifecycle_parsers import _add_schema_parser as add_parser
+
+    add_parser(subparsers)
 
 
 def _add_contract_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -287,85 +285,9 @@ def _add_quality_parser(subparsers: argparse._SubParsersAction[argparse.Argument
 
 
 def _add_review_mesh_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
-    from agent_lifecycle.contracts.review_mesh_schemas import REVIEW_MESH_MODE_IDS
-    from agent_lifecycle.review_mesh.operator_templates import REVIEW_MESH_OPERATOR_TEMPLATE_IDS
+    from agent_lifecycle.cli.lifecycle_parsers import _add_review_mesh_parser as add_parser
 
-    review_mesh = subparsers.add_parser("review-mesh", help="optional Review Mesh commands")
-    review_mesh_sub = review_mesh.add_subparsers(dest="review_mesh_command", required=True)
-    template_list = review_mesh_sub.add_parser("template-list")
-    template_list.add_argument("--out")
-    profile = review_mesh_sub.add_parser("profile")
-    profile.add_argument("--profile-id", default="optional-review-mesh")
-    profile.add_argument("--mode", choices=list(REVIEW_MESH_MODE_IDS), action="append", default=[])
-    profile.add_argument("--default-mode", choices=list(REVIEW_MESH_MODE_IDS), default="leader-draft-multi-review")
-    profile.add_argument("--reviewer-model-class", action="append", default=[])
-    profile.add_argument("--require-independence", action="store_true")
-    profile.add_argument("--independence-dimension", choices=["host", "model"], action="append", default=[])
-    profile.add_argument("--allow-live-calls", action="store_true")
-    profile.add_argument("--max-invocations", type=int)
-    profile.add_argument("--max-input-tokens", type=int)
-    profile.add_argument("--max-output-tokens", type=int)
-    profile.add_argument("--max-wall-seconds", type=int)
-    profile.add_argument("--out")
-    recommend = review_mesh_sub.add_parser("recommend")
-    source = recommend.add_mutually_exclusive_group(required=True)
-    source.add_argument("--text")
-    source.add_argument("--file")
-    source.add_argument("--intake")
-    source.add_argument("--manifest")
-    recommend.add_argument("--sdd-tier", choices=["S0", "S1", "S2"])
-    recommend.add_argument("--risk-flag", action="append", default=[])
-    recommend.add_argument("--out")
-    prepare = review_mesh_sub.add_parser("prepare")
-    prepare_source = prepare.add_mutually_exclusive_group(required=True)
-    prepare_source.add_argument("--manifest")
-    prepare_source.add_argument("--intake")
-    prepare_source.add_argument("--handoff")
-    prepare.add_argument("--template", choices=list(REVIEW_MESH_OPERATOR_TEMPLATE_IDS), default="leader-draft-review")
-    prepare.add_argument("--profile-id")
-    prepare.add_argument("--phase")
-    prepare.add_argument("--reviewer", action="append", default=[])
-    prepare.add_argument("--blocking", action="store_true")
-    prepare.add_argument("--evidence-id", action="append", default=[])
-    prepare.add_argument("--out-dir")
-    prepare.add_argument("--out")
-    assign = review_mesh_sub.add_parser("assign")
-    assign_source = assign.add_mutually_exclusive_group(required=True)
-    assign_source.add_argument("--manifest")
-    assign_source.add_argument("--intake")
-    assign_source.add_argument("--handoff")
-    assign.add_argument("--profile")
-    assign.add_argument("--mode", choices=list(REVIEW_MESH_MODE_IDS), required=True)
-    assign.add_argument("--phase", required=True)
-    assign.add_argument("--assignment-id", required=True)
-    assign.add_argument("--reviewer-id", required=True)
-    assign.add_argument("--reviewer-role", default="reviewer")
-    assign.add_argument("--reviewer-model-class", default="strong-reasoning")
-    assign.add_argument("--reviewer-host-identity-hash")
-    assign.add_argument("--reviewer-model-identity-hash")
-    assign.add_argument("--blocking", action="store_true")
-    assign.add_argument("--evidence-id", action="append", default=[])
-    assign.add_argument("--out")
-    import_result = review_mesh_sub.add_parser("import-result")
-    import_result.add_argument("--profile", required=True)
-    import_result.add_argument("--assignment", required=True)
-    import_result.add_argument("--reviewer-output", required=True)
-    import_result.add_argument("--allow-local-evidence-ref", action="store_true")
-    import_result.add_argument("--out")
-    synthesize = review_mesh_sub.add_parser("synthesize")
-    synthesize.add_argument("--profile", required=True)
-    synthesize.add_argument("--result", action="append", required=True)
-    synthesize.add_argument("--mode", choices=list(REVIEW_MESH_MODE_IDS))
-    synthesize.add_argument("--accepted-finding-id", action="append", default=[])
-    synthesize.add_argument("--rejected-finding-id", action="append", default=[])
-    synthesize.add_argument("--out")
-    quorum = review_mesh_sub.add_parser("quorum")
-    quorum.add_argument("--profile", required=True)
-    quorum.add_argument("--synthesis", required=True)
-    quorum.add_argument("--min-reviewers", type=int, required=True)
-    quorum.add_argument("--required-role", action="append", default=[])
-    quorum.add_argument("--reviewer-role", action="append", default=[])
-    quorum.add_argument("--out")
+    add_parser(subparsers)
 
 
 def _add_audit_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:

agent_lifecycle_kit-2.19.0/src/agent_lifecycle/cli/plan_lock_commands.py

@@ -0,0 +1,306 @@
+"""Reviewed plan-lock creation command."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from agent_lifecycle.contracts import (
+    LifecycleError,
+    canonical_bytes,
+    canonical_digest,
+    load_json_object,
+    sha256_hex,
+    write_json_create,
+)
+from agent_lifecycle.contracts.authority_io import create_authority_bytes
+from agent_lifecycle.contracts.canonical import MAX_JSON_INPUT_BYTES
+from agent_lifecycle.contracts.ownership_paths import (
+    is_under_authority_path,
+    repository_authority_name,
+    require_declared_output_footprint,
+    require_output_footprint,
+)
+from agent_lifecycle.contracts.paths import normalize_repo_path, read_stable_repository_file
+from agent_lifecycle.freeze.package_integrity import (
+    _reject_undeclared_top_level_files,
+    build_reviewed_plan_lock_v2,
+    verify_plan_package_integrity,
+)
+from agent_lifecycle.planning.verification import build_plan_verification
+
+PLAN_LOCK_CREATION_RECEIPT = "agent-plan-lock-creation-receipt.v1"
+
+
+def create_reviewed_plan_lock(
+    *,
+    manifest_path: str,
+    review_path: str,
+    repository_root: Path,
+) -> dict[str, Any]:
+    """Create and verify the canonical lock for one reviewed frozen plan."""
+
+    root = repository_root.resolve(strict=True)
+    manifest_rel, manifest_data = _read_repository_json(root, manifest_path, label="plan manifest")
+    manifest = load_json_object(manifest_data, label="plan manifest")
+    package_value = manifest.get("package")
+    package = package_value if isinstance(package_value, dict) else {}
+    raw_plan_root = package.get("planArtifactRoot")
+    if not isinstance(raw_plan_root, str):
+        raise LifecycleError("invalid-plan-manifest", "package.planArtifactRoot is required")
+    plan_root = normalize_repo_path(raw_plan_root, label="package.planArtifactRoot")
+    expected_manifest = f"{plan_root}/plan.manifest.json"
+    if manifest_rel != expected_manifest:
+        raise LifecycleError("plan-manifest-path-mismatch", "manifest path does not match package.planArtifactRoot")
+
+    review_rel, review_data = _read_repository_json(root, review_path, label="plan review")
+    review = load_json_object(review_data, label="plan review")
+    lock = build_reviewed_plan_lock_v2(
+        manifest,
+        review,
+        review_path=review_rel,
+        review_sha256=sha256_hex(review_data),
+        repository_root=root,
+    )
+    # Reject malformed or drifting package bytes before creating the
+    # no-replace authority artifact. The second check still detects drift.
+    verify_plan_package_integrity(manifest, lock, repository_root=root)
+    lock_rel = f"{plan_root}/plan.lock.json"
+    lock_path = root.joinpath(*PurePosixPath(lock_rel).parts)
+    try:
+        write_json_create(lock_path, lock)
+    except FileExistsError as exc:
+        raise LifecycleError("plan-lock-exists", "canonical plan lock already exists", {"path": lock_rel}) from exc
+    except OSError as exc:
+        raise LifecycleError(
+            "plan-lock-write-failed",
+            "canonical plan lock could not be created",
+            {"path": lock_rel},
+        ) from exc
+    verification = verify_plan_package_integrity(manifest, lock, repository_root=root)
+    body = {
+        "schemaVersion": PLAN_LOCK_CREATION_RECEIPT,
+        "status": "PASS",
+        "packageId": package.get("id"),
+        "planRevision": manifest.get("planRevision"),
+        "manifestPath": manifest_rel,
+        "manifestHash": canonical_digest(manifest),
+        "reviewPath": review_rel,
+        "reviewId": review.get("reviewId"),
+        "reviewedPlanHash": review.get("reviewedPlanHash"),
+        "lockPath": lock_rel,
+        "lockSchemaVersion": lock.get("schemaVersion"),
+        "planFilesHash": lock.get("planFilesHash"),
+        "filesystemVerified": verification.get("filesystemVerified") is True,
+        "productionPromotionClaimed": False,
+    }
+    return {**body, "receiptDigest": canonical_digest(body)}
+
+
+def _read_repository_json(root: Path, raw_path: str, *, label: str) -> tuple[str, bytes]:
+    relative = normalize_repo_path(raw_path, label=f"{label} path")
+    data = read_stable_repository_file(root, relative, max_bytes=MAX_JSON_INPUT_BYTES, label=label)
+    return relative, data
+
+
+__all__ = ["PLAN_LOCK_CREATION_RECEIPT", "create_reviewed_plan_lock"]
+
+
+def prepare_freeze_candidate(
+    *,
+    manifest_path: str,
+    output_path: str,
+    repository_root: Path,
+) -> dict[str, Any]:
+    """Prepare exact candidate bytes before review, without review or lock authority."""
+    root = repository_root.resolve(strict=True)
+    manifest_rel, raw = _read_repository_json(root, manifest_path, label="draft manifest")
+    manifest = load_json_object(raw)
+    if manifest.get("status") != "DRAFT":
+        raise LifecycleError("freeze-prepare-requires-draft", "Only a draft may be prepared")
+    old = normalize_repo_path(manifest.get("package", {}).get("planArtifactRoot"))
+    if manifest_rel != old + "/plan.manifest.json":
+        raise LifecycleError("plan-manifest-path-mismatch", "Manifest must match its declared package")
+    if not manifest.get("packageIntegrity", {}).get("required"):
+        raise LifecycleError("plan-lock-v2-required", "Freeze preparation requires package integrity")
+    if (root / old / "plan.lock.json").exists():
+        raise LifecycleError("freeze-prepare-locked-input", "A locked package cannot be prepared again")
+    target = repository_authority_name(root / output_path, root)
+    receipt = target + ".preparation.json"
+    reservation = target + ".reservation.json"
+    require_declared_output_footprint(manifest, repository_root=root)
+    require_output_footprint(
+        manifest,
+        [target, receipt, reservation],
+        repository_root=root,
+        manifest_path=root / manifest_rel,
+    )
+    for forbidden in manifest.get("forbiddenWrites", []):
+        if is_under_authority_path(target, forbidden, operation_root=root):
+            raise LifecycleError("freeze-prepare-output-forbidden", "Candidate is inside a forbidden write path")
+    for name in (target, receipt, reservation):
+        if (root / name).exists():
+            raise LifecycleError("freeze-prepare-output-exists", "Candidate output already exists")
+    inputs = _candidate_inputs(root, manifest, old)
+    if canonical_digest(load_json_object(inputs[manifest_rel])) != canonical_digest(manifest):
+        raise LifecycleError("freeze-prepare-input-changed", "Draft manifest changed during preparation")
+    candidate, review = _relocated_candidate(manifest, old, target)
+    prepared = _candidate_bytes(inputs, candidate, old, target)
+    markdown = inputs.get(old + "/acceptance-criteria.md")
+    verification = build_plan_verification(
+        candidate,
+        manifest_path=root / target / "plan.manifest.json",
+        acceptance_markdown=markdown.decode("utf-8") if markdown is not None else None,
+        repository_root=root,
+        package_root=root / target,
+    )
+    blockers = [item for item in verification["blockers"] if item["code"] != "plan-lock-required"]
+    if blockers:
+        raise LifecycleError("freeze-prepare-preflight-failed", "Candidate preflight failed", {"blockers": blockers})
+    for name, data in inputs.items():
+        if read_stable_repository_file(root, name, max_bytes=8_388_608) != data:
+            raise LifecycleError("freeze-prepare-input-changed", "Draft inputs changed during preparation")
+    body = _preparation_receipt(manifest, candidate, inputs, prepared, review, receipt)
+    # One exclusive reservation chooses the winner before any package-file write.
+    create_authority_bytes(
+        root / reservation,
+        canonical_bytes(
+            {
+                "schemaVersion": "agent-freeze-candidate-reservation.v1",
+                "candidateDigest": canonical_digest(candidate),
+                "authorityClaimed": False,
+            }
+        )
+        + b"\n",
+        root=root,
+    )
+    for name, data in prepared.items():
+        create_authority_bytes(root / name, data, root=root)
+    create_authority_bytes(root / receipt, canonical_bytes(body) + b"\n", root=root)
+    return {
+        "schemaVersion": "agent-artifact-display-summary.v1",
+        "status": "PASS",
+        "artifact": {"path": receipt, "digest": canonical_digest(body)},
+        "candidateManifest": target + "/plan.manifest.json",
+        "authoritative": False,
+        "authorityClaimed": False,
+        "nativeAcceptanceClaimed": False,
+    }
+
+
+def _candidate_inputs(root: Path, manifest: dict[str, Any], old: str) -> dict[str, bytes]:
+    names = manifest.get("planFiles")
+    if not isinstance(names, list) or not 1 <= len(names) <= 64:
+        raise LifecycleError("freeze-prepare-inventory-invalid", "Declare between 1 and 64 plan files")
+    normalized = [normalize_repo_path(name) for name in names]
+    if len({name.casefold() for name in normalized}) != len(normalized):
+        raise LifecycleError("plan-file-duplicate", "Plan inventory has duplicate or aliased paths")
+    if old + "/plan.manifest.json" not in normalized:
+        raise LifecycleError("plan-manifest-unbound", "Manifest must be inventoried")
+    pending = manifest.get("planReview", {}).get("report")
+    inputs: dict[str, bytes] = {}
+    for name in normalized:
+        if not name.startswith(old + "/"):
+            raise LifecycleError("plan-file-outside-package", "Declared input escapes its package")
+        if name == pending:
+            if (root / name).exists():
+                raise LifecycleError("freeze-prepare-old-review", "A new candidate needs a new review")
+            continue
+        inputs[name] = read_stable_repository_file(root, name, max_bytes=8_388_608)
+        if sum(map(len, inputs.values())) > 8_388_608:
+            raise LifecycleError("freeze-prepare-input-too-large", "Candidate inventory exceeds 8 MiB")
+    # Bound the shared inventory check before its sorted directory enumeration.
+    import itertools
+
+    if len(list(itertools.islice((root / old).iterdir(), 97))) > 96:
+        raise LifecycleError("freeze-prepare-inventory-too-large", "Package has too many entries")
+    _reject_undeclared_top_level_files(
+        manifest,
+        root / old,
+        [{"path": name} for name in normalized],
+        repository_root=root,
+    )
+    return inputs
+
+
+def _relocated_candidate(
+    manifest: dict[str, Any],
+    old: str,
+    target: str,
+) -> tuple[dict[str, Any], str]:
+    candidate = load_json_object(canonical_bytes(manifest))
+
+    def relocate(name: str) -> str:
+        return target + name[len(old) :] if name.startswith(old + "/") else name
+
+    candidate["package"]["planArtifactRoot"] = target
+    candidate["status"] = "FROZEN"
+    candidate["planFiles"] = [relocate(name) for name in manifest["planFiles"]]
+    if isinstance(candidate.get("developerOverview"), str):
+        candidate["developerOverview"] = relocate(candidate["developerOverview"])
+    spec = candidate.get("specification")
+    if isinstance(spec, dict):
+        spec["status"] = "FROZEN"
+        if isinstance(spec.get("source"), str):
+            spec["source"] = relocate(spec["source"])
+    review = relocate(
+        manifest.get("planReview", {}).get(
+            "report",
+            old + "/independent-plan-review.json",
+        )
+    )
+    if not review.startswith(target + "/"):
+        raise LifecycleError("plan-review-path-mismatch", "Review must be inside the candidate")
+    candidate["planFiles"] = sorted(set([*candidate["planFiles"], review]))
+    candidate["planReview"] = {
+        "required": True,
+        "report": review,
+        "reviewedRevision": candidate["planRevision"],
+        "verdict": "READY_TO_FREEZE",
+    }
+    return candidate, review
+
+
+def _candidate_bytes(
+    inputs: dict[str, bytes],
+    candidate: dict[str, Any],
+    old: str,
+    target: str,
+) -> dict[str, bytes]:
+    prepared = {}
+    for name, data in inputs.items():
+        output = target + name[len(old) :]
+        if name == old + "/plan.manifest.json":
+            data = canonical_bytes(candidate) + b"\n"
+        elif name.endswith(".json"):
+            data = canonical_bytes(load_json_object(data)) + b"\n"
+        prepared[output] = data
+    return prepared
+
+
+def _preparation_receipt(
+    manifest: dict[str, Any],
+    candidate: dict[str, Any],
+    inputs: dict[str, bytes],
+    prepared: dict[str, bytes],
+    review: str,
+    receipt_path: str,
+) -> dict[str, Any]:
+    def inventory(values: dict[str, bytes]) -> list[dict[str, Any]]:
+        return [{"path": name, "bytes": len(data), "sha256": sha256_hex(data)} for name, data in sorted(values.items())]
+
+    return {
+        "schemaVersion": "agent-freeze-preparation-receipt.v1",
+        "status": "CANDIDATE_PREPARED",
+        "draftDigest": canonical_digest(manifest),
+        "candidateDigest": canonical_digest(candidate),
+        "inputs": inventory(inputs),
+        "candidateFiles": inventory(prepared),
+        "pendingReviewPath": review,
+        "receiptPath": receipt_path,
+        "reviewCreated": False,
+        "lockCreated": False,
+        "authorityClaimed": False,
+        "modelCallsStarted": False,
+        "productionPromotionClaimed": False,
+    }