agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/worktree/isolation.py

@@ -0,0 +1,407 @@
+"""Provider-neutral worktree isolation receipts."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_digest
+from agent_lifecycle.contracts.paths import is_under_repo_path, normalize_repo_path
+
+LINEAGE_KEYS = ("runId", "packageId", "planRevision", "planDigest", "sourceRevision")
+OUTCOMES = {"PASS", "FAILED", "BLOCKED"}
+CLEANUP_DECISIONS = {"PRESERVE", "REMOVE"}
+WRITEBACK_DECISIONS = {"APPLY", "DISCARD"}
+
+
+def validate_worktree_policy(policy: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(policy, dict):
+        raise LifecycleError("invalid-worktree-policy", "worktree policy must be an object")
+    if policy.get("schemaVersion") != "agent-worktree-isolation-policy.v1":
+        raise LifecycleError("invalid-worktree-policy", "worktree policy schemaVersion is unsupported")
+    worktree_root = normalize_repo_path(_required_string(policy.get("worktreeRoot"), label="worktreeRoot"), label="worktreeRoot")
+    allowed_write_roots = _path_list(policy.get("allowedWriteRoots", []), label="allowedWriteRoots", allow_empty=True)
+    preserve_failed = _required_bool(policy.get("preserveFailedAttempts"), label="preserveFailedAttempts")
+    cleanup_requires_operator = _required_bool(policy.get("cleanupRequiresOperator"), label="cleanupRequiresOperator")
+    body = {
+        "schemaVersion": "agent-worktree-isolation-policy-validation.v1",
+        "status": "PASS",
+        "worktreeRoot": worktree_root,
+        "allowedWriteRoots": allowed_write_roots,
+        "preserveFailedAttempts": preserve_failed,
+        "cleanupRequiresOperator": cleanup_requires_operator,
+        "policyDigest": canonical_digest(policy),
+    }
+    return body
+
+
+def build_attempt_isolation_receipt(
+    workflow_state: dict[str, Any],
+    *,
+    task_id: str,
+    attempt: int,
+    policy: dict[str, Any],
+    worktree_path: str,
+    baseline_ref: str,
+    baseline_sha: str,
+    changed_files: list[str],
+    outcome: str,
+    cleanup_decision: str | None = None,
+    operator_authorization: dict[str, Any] | None = None,
+    reason: str,
+) -> dict[str, Any]:
+    validation = validate_worktree_policy(policy)
+    task = _workflow_task(workflow_state, task_id)
+    decision = cleanup_decision or "PRESERVE"
+    body = {
+        "schemaVersion": "agent-worktree-attempt-receipt.v1",
+        "status": "PASS",
+        "lineage": _lineage_from_workflow(workflow_state),
+        "taskId": task_id,
+        "attempt": _positive_int(attempt, label="attempt"),
+        "policyDigest": validation["policyDigest"],
+        "isolation": {
+            "strategy": "git-worktree",
+            "worktreePath": normalize_repo_path(worktree_path, label="worktreePath"),
+            "worktreeRoot": validation["worktreeRoot"],
+            "baselineRef": _required_string(baseline_ref, label="baselineRef"),
+            "baselineSha": _required_string(baseline_sha, label="baselineSha"),
+            "mainWorktreeClean": True,
+            "allowedWriteRoots": _allowed_roots(validation["allowedWriteRoots"], task),
+            "changedFiles": _path_list(changed_files, label="changedFiles", allow_empty=True),
+        },
+        "outcome": _enum(outcome, OUTCOMES, label="outcome"),
+        "cleanup": {
+            "decision": _enum(decision, CLEANUP_DECISIONS, label="cleanupDecision"),
+            "operatorAuthorization": operator_authorization,
+            "reason": reason,
+        },
+        "createdAt": _now_iso(),
+    }
+    result = validate_attempt_isolation_receipt(body, workflow_state=workflow_state, policy=policy)
+    return {**body, "receiptDigest": result["receiptDigest"]}
+
+
+def validate_attempt_isolation_receipt(
+    receipt: dict[str, Any],
+    *,
+    workflow_state: dict[str, Any] | None = None,
+    policy: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if not isinstance(receipt, dict):
+        raise LifecycleError("invalid-worktree-receipt", "worktree receipt must be an object")
+    if receipt.get("schemaVersion") != "agent-worktree-attempt-receipt.v1":
+        raise LifecycleError("invalid-worktree-receipt", "worktree receipt schemaVersion is unsupported")
+    if receipt.get("status") != "PASS":
+        raise LifecycleError("worktree-isolation-not-pass", "worktree isolation receipt must be PASS")
+    lineage = _lineage(receipt.get("lineage"))
+    if workflow_state is not None:
+        _validate_workflow_binding(lineage, workflow_state)
+    task_id = _required_string(receipt.get("taskId"), label="taskId")
+    attempt = _positive_int(receipt.get("attempt"), label="attempt")
+    isolation = _isolation(receipt.get("isolation"))
+    cleanup = _cleanup(receipt.get("cleanup"))
+    if policy is not None:
+        policy_validation = validate_worktree_policy(policy)
+        if receipt.get("policyDigest") != policy_validation["policyDigest"]:
+            raise LifecycleError("worktree-policy-mismatch", "worktree receipt policyDigest mismatch")
+        if not is_under_repo_path(isolation["worktreePath"], policy_validation["worktreeRoot"]):
+            raise LifecycleError("worktree-path-outside-root", "worktree path is outside policy root")
+        if policy_validation["cleanupRequiresOperator"] and cleanup["decision"] == "REMOVE" and cleanup["operatorAuthorization"] is None:
+            raise LifecycleError("worktree-cleanup-authorization-required", "worktree cleanup requires operator authorization")
+        if policy_validation["preserveFailedAttempts"] and receipt.get("outcome") == "FAILED" and cleanup["decision"] == "REMOVE":
+            authorization = cleanup["operatorAuthorization"]
+            if not isinstance(authorization, dict) or authorization.get("allowFailedAttemptRemoval") is not True:
+                raise LifecycleError("worktree-failed-attempt-preserved", "failed attempt cleanup requires explicit removal authorization")
+    if workflow_state is not None:
+        task = _workflow_task(workflow_state, task_id)
+        _validate_changed_files_in_scope(isolation["changedFiles"], _allowed_roots(isolation["allowedWriteRoots"], task))
+    stored_digest = receipt.get("receiptDigest")
+    receipt_digest = _receipt_digest(receipt)
+    if stored_digest is not None and stored_digest != receipt_digest:
+        raise LifecycleError("worktree-receipt-digest-mismatch", "worktree receiptDigest does not match receipt")
+    body = {
+        "schemaVersion": "agent-worktree-attempt-receipt-validation.v1",
+        "status": "PASS",
+        "lineage": lineage,
+        "taskId": task_id,
+        "attempt": attempt,
+        "outcome": receipt.get("outcome"),
+        "cleanupDecision": cleanup["decision"],
+        "receiptDigest": receipt_digest,
+    }
+    return body
+
+
+def build_worktree_writeback_receipt(
+    workflow_state: dict[str, Any],
+    *,
+    task_id: str,
+    attempt: int,
+    overlay_digest: str,
+    changed_files: list[str],
+    decision: str,
+    operator_authorization: dict[str, Any],
+    reason: str,
+    applied_files: list[str] | None = None,
+    discarded_files: list[str] | None = None,
+    isolation_receipt_digest: str | None = None,
+) -> dict[str, Any]:
+    selected_decision = _enum(decision, WRITEBACK_DECISIONS, label="decision.action")
+    changed = _path_list(changed_files, label="changedFiles", allow_empty=True)
+    applied = _path_list(
+        applied_files if applied_files is not None else (changed if selected_decision == "APPLY" else []),
+        label="appliedFiles",
+        allow_empty=True,
+    )
+    discarded = _path_list(
+        discarded_files if discarded_files is not None else (changed if selected_decision == "DISCARD" else []),
+        label="discardedFiles",
+        allow_empty=True,
+    )
+    body = {
+        "schemaVersion": "agent-worktree-writeback-receipt.v1",
+        "status": "PASS",
+        "lineage": _lineage_from_workflow(workflow_state),
+        "taskId": task_id,
+        "attempt": _positive_int(attempt, label="attempt"),
+        "boundary": {
+            "kind": "isolated-overlay",
+            "isolationReceiptDigest": isolation_receipt_digest,
+            "overlayDigest": _digest(overlay_digest, label="overlayDigest"),
+            "runtimeAgnostic": True,
+        },
+        "decision": {
+            "action": selected_decision,
+            "operatorAuthorization": _operator_authorization(operator_authorization),
+            "reason": _required_string(reason, label="decision.reason"),
+        },
+        "changedFiles": changed,
+        "appliedFiles": applied,
+        "discardedFiles": discarded,
+        "createdAt": _now_iso(),
+        "productionPromotionClaimed": False,
+    }
+    result = validate_worktree_writeback_receipt(body, workflow_state=workflow_state)
+    return {**body, "receiptDigest": result["receiptDigest"]}
+
+
+def validate_worktree_writeback_receipt(
+    receipt: dict[str, Any],
+    *,
+    workflow_state: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if not isinstance(receipt, dict):
+        raise LifecycleError("invalid-worktree-writeback-receipt", "worktree write-back receipt must be an object")
+    if receipt.get("schemaVersion") != "agent-worktree-writeback-receipt.v1":
+        raise LifecycleError("invalid-worktree-writeback-receipt", "worktree write-back schemaVersion is unsupported")
+    if receipt.get("status") != "PASS":
+        raise LifecycleError("worktree-writeback-not-pass", "worktree write-back receipt must be PASS")
+    lineage = _lineage(receipt.get("lineage"))
+    if workflow_state is not None:
+        _validate_workflow_binding(lineage, workflow_state)
+    task_id = _required_string(receipt.get("taskId"), label="taskId")
+    attempt = _positive_int(receipt.get("attempt"), label="attempt")
+    boundary = _writeback_boundary(receipt.get("boundary"))
+    decision = _writeback_decision(receipt.get("decision"))
+    changed = _path_list(receipt.get("changedFiles", []), label="changedFiles", allow_empty=True)
+    applied = _path_list(receipt.get("appliedFiles", []), label="appliedFiles", allow_empty=True)
+    discarded = _path_list(receipt.get("discardedFiles", []), label="discardedFiles", allow_empty=True)
+    _validate_writeback_paths(changed, applied=applied, discarded=discarded, decision=decision["action"])
+    if workflow_state is not None:
+        task = _workflow_task(workflow_state, task_id)
+        _validate_changed_files_in_scope(changed, _allowed_roots([], task))
+    if receipt.get("productionPromotionClaimed") is not False:
+        raise LifecycleError("worktree-writeback-production-claim", "write-back receipt must not claim production promotion")
+    stored_digest = receipt.get("receiptDigest")
+    receipt_digest = _receipt_digest(receipt)
+    if stored_digest is not None and stored_digest != receipt_digest:
+        raise LifecycleError("worktree-writeback-receipt-digest-mismatch", "worktree write-back receiptDigest does not match receipt")
+    return {
+        "schemaVersion": "agent-worktree-writeback-receipt-validation.v1",
+        "status": "PASS",
+        "lineage": lineage,
+        "taskId": task_id,
+        "attempt": attempt,
+        "decision": decision["action"],
+        "overlayDigest": boundary["overlayDigest"],
+        "changedFileCount": len(changed),
+        "appliedFileCount": len(applied),
+        "discardedFileCount": len(discarded),
+        "receiptDigest": receipt_digest,
+    }
+
+
+def _isolation(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError("invalid-worktree-receipt", "worktree isolation is required")
+    strategy = value.get("strategy")
+    if strategy != "git-worktree":
+        raise LifecycleError("invalid-worktree-receipt", "worktree isolation strategy is unsupported")
+    if value.get("mainWorktreeClean") is not True:
+        raise LifecycleError("worktree-main-dirty", "main worktree must be clean before isolated attempt")
+    return {
+        "strategy": strategy,
+        "worktreePath": normalize_repo_path(_required_string(value.get("worktreePath"), label="isolation.worktreePath"), label="isolation.worktreePath"),
+        "worktreeRoot": normalize_repo_path(_required_string(value.get("worktreeRoot"), label="isolation.worktreeRoot"), label="isolation.worktreeRoot"),
+        "baselineRef": _required_string(value.get("baselineRef"), label="isolation.baselineRef"),
+        "baselineSha": _required_string(value.get("baselineSha"), label="isolation.baselineSha"),
+        "allowedWriteRoots": _path_list(value.get("allowedWriteRoots", []), label="isolation.allowedWriteRoots", allow_empty=True),
+        "changedFiles": _path_list(value.get("changedFiles", []), label="isolation.changedFiles", allow_empty=True),
+    }
+
+
+def _cleanup(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError("invalid-worktree-receipt", "worktree cleanup is required")
+    decision = _enum(value.get("decision"), CLEANUP_DECISIONS, label="cleanup.decision")
+    authorization = value.get("operatorAuthorization")
+    if authorization is not None and not isinstance(authorization, dict):
+        raise LifecycleError("invalid-worktree-receipt", "operatorAuthorization must be an object")
+    _required_string(value.get("reason"), label="cleanup.reason")
+    return {"decision": decision, "operatorAuthorization": authorization}
+
+
+def _writeback_boundary(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError("invalid-worktree-writeback-receipt", "write-back boundary is required")
+    if value.get("kind") != "isolated-overlay":
+        raise LifecycleError("invalid-worktree-writeback-receipt", "write-back boundary kind is unsupported")
+    if value.get("runtimeAgnostic") is not True:
+        raise LifecycleError("invalid-worktree-writeback-receipt", "write-back boundary must be runtime agnostic")
+    isolation_digest = value.get("isolationReceiptDigest")
+    if isolation_digest is not None:
+        _digest(isolation_digest, label="boundary.isolationReceiptDigest")
+    return {
+        "kind": "isolated-overlay",
+        "isolationReceiptDigest": isolation_digest,
+        "overlayDigest": _digest(value.get("overlayDigest"), label="boundary.overlayDigest"),
+        "runtimeAgnostic": True,
+    }
+
+
+def _writeback_decision(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError("invalid-worktree-writeback-receipt", "write-back decision is required")
+    action = _enum(value.get("action"), WRITEBACK_DECISIONS, label="decision.action")
+    authorization = _operator_authorization(value.get("operatorAuthorization"))
+    _required_string(value.get("reason"), label="decision.reason")
+    return {"action": action, "operatorAuthorization": authorization}
+
+
+def _operator_authorization(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError("invalid-worktree-writeback-receipt", "operatorAuthorization must be an object")
+    if not isinstance(value.get("operatorIdentityHash"), str) or not value["operatorIdentityHash"]:
+        raise LifecycleError("invalid-worktree-writeback-receipt", "operatorIdentityHash is required")
+    return dict(value)
+
+
+def _validate_writeback_paths(
+    changed: list[str],
+    *,
+    applied: list[str],
+    discarded: list[str],
+    decision: str,
+) -> None:
+    changed_set = set(changed)
+    applied_set = set(applied)
+    discarded_set = set(discarded)
+    overlap = sorted(applied_set.intersection(discarded_set))
+    if overlap:
+        raise LifecycleError("worktree-writeback-path-overlap", "applied and discarded paths overlap", {"paths": overlap})
+    outside = sorted(applied_set.union(discarded_set) - changed_set)
+    if outside:
+        raise LifecycleError("worktree-writeback-path-outside-overlay", "write-back path is outside overlay changes", {"paths": outside})
+    if decision == "DISCARD" and applied:
+        raise LifecycleError("worktree-writeback-discard-applied-paths", "discard decision must not apply files")
+    if decision == "APPLY" and changed and not applied:
+        raise LifecycleError("worktree-writeback-apply-empty", "apply decision must apply at least one changed file")
+
+
+def _validate_changed_files_in_scope(changed_files: list[str], allowed_roots: list[str]) -> None:
+    for path in changed_files:
+        if not any(is_under_repo_path(path, root) for root in allowed_roots):
+            raise LifecycleError("worktree-write-scope-violation", "worktree changed file is outside task write scope", {"path": path, "allowedWriteRoots": allowed_roots})
+
+
+def _allowed_roots(policy_roots: list[str], task: dict[str, Any]) -> list[str]:
+    task_writes = _path_list(task.get("writes", []), label="task.writes", allow_empty=False)
+    if not policy_roots:
+        return task_writes
+    return [root for root in policy_roots if any(is_under_repo_path(root, task_root) or is_under_repo_path(task_root, root) for task_root in task_writes)] or task_writes
+
+
+def _workflow_task(workflow_state: dict[str, Any], task_id: str) -> dict[str, Any]:
+    for task in workflow_state.get("tasks", []):
+        if isinstance(task, dict) and task.get("id") == task_id:
+            return task
+    raise LifecycleError("worktree-task-not-found", "worktree task is missing from workflow state", {"taskId": task_id})
+
+
+def _lineage_from_workflow(state: dict[str, Any]) -> dict[str, Any]:
+    return {key: state.get(key) for key in LINEAGE_KEYS}
+
+
+def _lineage(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise LifecycleError("invalid-worktree-receipt", "worktree lineage is required")
+    result = {key: value.get(key) for key in LINEAGE_KEYS}
+    for key, item in result.items():
+        if key == "planRevision":
+            _positive_int(item, label="lineage.planRevision")
+        elif not isinstance(item, str) or not item:
+            raise LifecycleError("invalid-worktree-receipt", f"worktree lineage.{key} is required")
+    return result
+
+
+def _validate_workflow_binding(lineage: dict[str, Any], workflow_state: dict[str, Any]) -> None:
+    for key in LINEAGE_KEYS:
+        if lineage.get(key) != workflow_state.get(key):
+            raise LifecycleError("worktree-lineage-mismatch", f"worktree {key} mismatch")
+
+
+def _path_list(value: Any, *, label: str, allow_empty: bool) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(item, str) and item for item in value):
+        raise LifecycleError("invalid-worktree-receipt", f"{label} must be a list of non-empty paths")
+    if not value and not allow_empty:
+        raise LifecycleError("invalid-worktree-receipt", f"{label} must not be empty")
+    return [normalize_repo_path(item, label=label) for item in value]
+
+
+def _enum(value: Any, allowed: set[str], *, label: str) -> str:
+    if value not in allowed:
+        raise LifecycleError("invalid-worktree-receipt", f"{label} is unsupported")
+    return str(value)
+
+
+def _required_string(value: Any, *, label: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise LifecycleError("invalid-worktree-receipt", f"{label} is required")
+    return value
+
+
+def _required_bool(value: Any, *, label: str) -> bool:
+    if not isinstance(value, bool):
+        raise LifecycleError("invalid-worktree-policy", f"{label} must be boolean")
+    return value
+
+
+def _digest(value: Any, *, label: str) -> str:
+    if not isinstance(value, str) or len(value) != 64:
+        raise LifecycleError("invalid-worktree-writeback-receipt", f"{label} must be a sha256 digest")
+    return value
+
+
+def _positive_int(value: Any, *, label: str) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise LifecycleError("invalid-worktree-receipt", f"{label} must be a positive integer")
+    return value
+
+
+def _receipt_digest(receipt: dict[str, Any]) -> str:
+    return canonical_digest({key: value for key, value in receipt.items() if key != "receiptDigest"})
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")

agent_lifecycle_kit-1.50.1.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: agent-lifecycle-kit
+Version: 1.50.1
+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
+Keywords: adapter-conformance,agent-lifecycle,agent-workflows,agents,ai-agents,audit,coding-agents,lifecycle,model-routing,planning,sdd,software-delivery,task-orchestration,workflow
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/agent-lifecycle-kit-banner.svg?v=2026-08-02-1" alt="Agent Lifecycle Kit - plan, execute, prove, finish agent work" width="100%">
+</p>
+
+# Agent Lifecycle Kit
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/avksp/agent-lifecycle-kit?label=release)](https://github.com/avksp/agent-lifecycle-kit/releases)
+![Python](https://img.shields.io/badge/python-3.11--3.13-blue.svg)
+
+**Agent Lifecycle Kit (ALK)** gives coding agents one delivery workflow from
+request to verified result. It turns a user task into a reviewed specification,
+an approved plan, bounded implementation work, review, and final proof, so
+agents finish the job instead of stopping at a patch.
+
+The workflow is provider-neutral. Codex, Claude Code, Qwen Code, Goose,
+OpenInterpreter, Pi, Grok Build, or another CLI can follow the same lifecycle,
+while provider commands, model choice, and secret handling stay in adapters or
+host-local profiles.
+
+## Quick start
+
+From a source checkout:
+
+```bash
+python -m pip install -e .
+agent-lifecycle version
+agent-lifecycle diagnose --no-install-plans
+agent-lifecycle adapter validate --descriptor adapters/codex/adapter.descriptor.json
+```
+
+Package install, when available for the release:
+`python -m pip install agent-lifecycle-kit==1.50.1`.
+
+For a short walkthrough, use [Quickstart](docs/guides/quickstart.md) and the [Lifecycle cookbook](docs/guides/lifecycle-cookbook.md). For structure and positioning, see [System architecture](docs/architecture/system-architecture.md) and [Project comparison](docs/reference/project-comparison.md). Russian documentation starts at [Документация на русском](docs/ru/README.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
+  core, and new adapters can be added without changing lifecycle schemas.
+- Small-model friendly packets: compact context, clear next actions, and
+  deterministic checks for local or cheaper models.
+- Quality without overengineering: optional profiles turn on only when risk or
+  task type requires them.
+- Usage visibility: tokens, time, and resource counters are native; monetary
+  cost is optional and only used when a metered host reports it.
+- Read-only progress and managed sessions: host UIs can show lifecycle state,
+  attested tokens and Git-style change counters; `adapter task start` accepts
+  task text, Markdown or frozen run requests while preserving review/freeze
+  boundaries.
+
+## Feature areas
+
+### Plan and execute
+
+- Reviewed specification and plan flow before implementation starts.
+- Deterministic task packets for splitting work across agents.
+- Execution records capture completion checks, blockers, retries, and final
+  proof; missing required evidence fails the step.
+- Ready-made task templates cover bug fixes, idea-to-PR flow, PR review,
+  merge-conflict repair, and release-readiness work.
+
+### Quality and proof
+
+- Implementation audits compare results with the frozen plan and acceptance
+  evidence.
+- For explicit bug and regression repair, the optional Bug Forensics profile
+  records reproduction, fingerprint, failure class, hypotheses, minimal patch,
+  regression proof, and reusable recipes.
+- Optional proof-integrity evidence for high-risk final proofs: stable findings,
+  root-cause digests, fix-impact receipts, and hash chains.
+- Cross-checks and runtime-policy receipts are opt-in controls; plans can
+  require proof for an external system update before acceptance.
+- Optional Review Mesh covers leader-draft review, parallel research synthesis
+  and audit panels. The advisor can suggest a mode; `review-mesh prepare`
+  creates local reviewer packets; opted-in plans can require
+  assignment/result/synthesis/quorum receipts, but ALK core does not start hosts.
+
+### Routing and resource control
+
+- Compact context profiles, small-model packets, objective snapshots, and
+  local quality-cost learning help choose the lightest safe mode.
+- Phase resource measurements reuse the usage export envelope for tokens,
+  duration, and resource counters without mandatory monetary accounting.
+- Usage/session exports include tokens, resources, receipt digests, and optional
+  host-reported `cost_usd`.
+
+### Security and containment
+
+- Neutrality filters use host-supplied deny rules to keep local paths, secrets, trust roots, and signing keys out of portable artifacts.
+- Host env files require explicit `--host-env-allow`; receipts store redacted metadata, not secret values or private env-file paths.
+- Imports, diagnostics, and usage exports redact local paths and common secret markers before validation.
+- Sandbox receipts separate runtime filesystem, network, process, and environment containment from git write-scope.
+- Release security gates reject leaked local paths, credentials, and unsupported adapter or production claims.
+
+### Adapters and interop
+
+- Adapter contracts keep host-specific projections separate from lifecycle
+  schemas.
+- New CLI hosts start as adapters: descriptor, command projection, environment
+  boundary, and verification evidence live outside the lifecycle core.
+- Adapter capability checks and progress bridge support compare live receipts
+  and display lifecycle state without automatic maturity changes.
+- Import mappers and issue-to-spec intake treat external workflows, agent
+  dialects, and tickets as untrusted draft inputs.
+- Lightweight episode retrieval over receipt/session summaries keeps digest
+  provenance and explicit `chainVerified` or `chainUnchecked` state.
+
+### Operations
+
+- Runner recovery receipts cover attempt snapshot, restore, abandon, selected
+  attempt, worker lease, and heartbeat state.
+- Read-only diagnostics, event feeds, managed lifecycle steps, progress watch
+  receipts, and change summaries inspect checkout and workflow state without
+  model calls.
+
+## Daily flow
+
+Spec -> frozen plan -> bounded work -> implementation audit -> final proof.
+Core commands cover specification, plan, workflow, audit, adapters, imports, metrics,
+policy, diagnostics, runner state, and adapter task intake. See [CLI reference](docs/reference/cli.md) and [Source of truth](docs/reference/source-of-truth.md).
+
+## Adapter maturity
+
+`EXPERIMENTAL` means offline checks exist; bounded live host conformance and
+usage/resource calibration are still required before `VERIFIED`. The verified
+claim is host-specific and also requires accepted redacted evidence and
+lifecycle final proof for the tested host range. New hosts can be added as
+adapters first and promoted only for the exact CLI/version/provider binding that
+has evidence. Monetary accounting is required only for metered modes.
+
+| Host | Current claim |
+| --- | --- |
+| Codex | `VERIFIED` for Codex CLI 0.145.0. Public Plugins Directory approval is not claimed. |
+| Claude Code | `VERIFIED` for Claude Code 2.1.220. Official directory approval is not claimed. |
+| OpenCode | `VERIFIED` for OpenCode CLI 1.18.9. npm publication is not claimed. |
+| Hermes | `VERIFIED` for Hermes Agent v0.19.0. Public directory approval is not claimed. |
+| Qwen Code | `VERIFIED` for Qwen Code 0.21.0 on the tested host-local provider/model binding. Public package approval is not claimed. |
+| Cursor | `EXPERIMENTAL`; local safe inspection passed, but accepted live receipts are incomplete. |
+| Gemini CLI | `EXPERIMENTAL`; local live canary is blocked by the current Gemini Code Assist tier. |
+| Goose | `VERIFIED` for Goose 1.45.0 on the tested host-local provider/model binding. Public directory approval is not claimed. |
+| Kimi Code | `EXPERIMENTAL`; live proof requires a configured provider and model alias. |
+| Grok Build | `VERIFIED` for Grok Build 0.2.117 on the tested host-local provider/model binding. Public directory approval is not claimed. |
+| OpenInterpreter | `VERIFIED` for `interpreter` 0.0.34 on the tested host-local provider/model binding. Public directory approval is not claimed. |
+| Pi | `VERIFIED` for Pi 0.83.0 on the tested host-local provider/model binding. Public directory approval is not claimed. |
+
+Adapter installation and maturity details live in [Adapter install](docs/adapters/install.md) and [Adapter support matrix](docs/adapters/support-matrix.md).
+
+## Contract map
+
+The public lifecycle surface is schema-backed. Full stable schema ids, compatibility rules, runner recovery, cross-check, Review Mesh, Bug Forensics and usage export details are listed in [Public contracts](docs/reference/public-contracts.md).
+
+## Design boundaries
+
+- The core stays provider-neutral. Concrete host commands and model bindings
+  belong to adapters or host-local profiles.
+- New CLIs are integrated through adapters: descriptor, command projection,
+  environment boundary, and verification evidence. The lifecycle schemas remain
+  stable while host support grows.
+- Small models get compact packets, deterministic checks, and explicit
+  next-action lists instead of long narrative state.
+- Larger models keep the same gates; better reasoning does not bypass evidence.
+- Public release claims are limited to tracked source files and redacted
+  evidence summaries.
+- External dialect imports and retrieved episodes are context aids only; they
+  do not replace reviewed ALK source-of-truth artifacts.
+- Optional cross-check, Review Mesh and runner recovery receipts add evidence
+  only when a task or plan requests them; they are not default multi-model execution.
+
+## Documentation
+
+- Start: [English documentation](docs/README.md), [Русская документация](docs/ru/README.md), [Quickstart](docs/guides/quickstart.md), [Lifecycle cookbook](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), [CLI reference](docs/reference/cli.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), [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: [Small-model packets](docs/reference/small-model-packets.md), [model routing](docs/reference/model-routing.md), [adaptive policy](docs/reference/adaptive-lifecycle-policy.md), [quality-cost learning](docs/reference/quality-cost-learning.md), [lifecycle cost accounting](docs/reference/lifecycle-cost.md), [Usage export](docs/reference/usage-export.md), and [Evidence integrity](docs/reference/evidence-integrity.md).
+- Profiles and operations: [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 recovery](docs/reference/runner-recovery.md), [Cross-check profile](docs/reference/cross-check-profile.md), [Review Mesh](docs/reference/review-mesh.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) and [Release security](docs/security/release-security.md).
+
+Apache-2.0. See [LICENSE](LICENSE).