agent-lifecycle-kit 2.33.0__tar.gz → 2.35.0__tar.gz

{agent_lifecycle_kit-2.33.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.33.0
+Version: 2.35.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
@@ -33,16 +33,16 @@ Dynamic: license-file
 
 **Agent Lifecycle Kit (ALK)** coordinates coding-agent work through a verifiable finish. It keeps the requested outcome, reviewed plan, execution boundaries, evidence and acceptance decisions connected while the external agent changes the project.
 
-The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
+Release 2.35 documents the [external AI SDLC CLI contract](docs/guides/ai-sdlc-integration.md) and eight bounded consumer cases. Wheel/sdist include both guides and case JSON; the plugin ships the paired CLI contract. Native authority and release gates remain required.
 
-Release 2.33 simplifies selected internal boundaries and checks the release validators themselves. It removes two private-import allowances (83 to 81), reduces one final-evidence flow from 58 to 41 branches, and adds selected Ruff/strict-mypy checks without increasing runtime baselines. Existing architecture debt remains visible. See [the 2.33 scope](docs/reference/cli.md#release-233-selected-architecture-and-tooling-quality). Release 2.32 adds [advisory process observations and eight selected reading routes](docs/reference/cli.md#release-232-process-observations-and-reading-scope); missing whole-run evidence and provider usage remain null/UNAVAILABLE. ALK provides a verifiable finish for external-agent work with proportionate control. Release 2.31 strengthens supported-text secret checks, enforces global branch and critical-file coverage floors, and gives a bounded structural refusal for malformed legacy state. See [the 2.31 check boundaries](docs/reference/cli.md#release-231-bounded-quality-checks). See [workflow history and recovery](docs/reference/workflow-state-storage.md) for the earlier storage and renewal features. Install the Python package as well as the plugin for the new CLI commands.
+The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
 
 Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/performance-and-resource-budgets.md#release-228-lifecycle-and-accounting-baselines). Repository tools measure real read-only operations and separate fixture preparation from operation and subprocess time. The Windows fixture comparison observed a 13.08% median reduction in one six-sample experiment; it is not a universal speed promise. All security and platform checks remain required.
 
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. 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.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.33.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.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.35.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.33.0 → agent_lifecycle_kit-2.35.0}/README.md

@@ -10,16 +10,16 @@
 
 **Agent Lifecycle Kit (ALK)** coordinates coding-agent work through a verifiable finish. It keeps the requested outcome, reviewed plan, execution boundaries, evidence and acceptance decisions connected while the external agent changes the project.
 
-The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
+Release 2.35 documents the [external AI SDLC CLI contract](docs/guides/ai-sdlc-integration.md) and eight bounded consumer cases. Wheel/sdist include both guides and case JSON; the plugin ships the paired CLI contract. Native authority and release gates remain required.
 
-Release 2.33 simplifies selected internal boundaries and checks the release validators themselves. It removes two private-import allowances (83 to 81), reduces one final-evidence flow from 58 to 41 branches, and adds selected Ruff/strict-mypy checks without increasing runtime baselines. Existing architecture debt remains visible. See [the 2.33 scope](docs/reference/cli.md#release-233-selected-architecture-and-tooling-quality). Release 2.32 adds [advisory process observations and eight selected reading routes](docs/reference/cli.md#release-232-process-observations-and-reading-scope); missing whole-run evidence and provider usage remain null/UNAVAILABLE. ALK provides a verifiable finish for external-agent work with proportionate control. Release 2.31 strengthens supported-text secret checks, enforces global branch and critical-file coverage floors, and gives a bounded structural refusal for malformed legacy state. See [the 2.31 check boundaries](docs/reference/cli.md#release-231-bounded-quality-checks). See [workflow history and recovery](docs/reference/workflow-state-storage.md) for the earlier storage and renewal features. Install the Python package as well as the plugin for the new CLI commands.
+The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
 
 Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/performance-and-resource-budgets.md#release-228-lifecycle-and-accounting-baselines). Repository tools measure real read-only operations and separate fixture preparation from operation and subprocess time. The Windows fixture comparison observed a 13.08% median reduction in one six-sample experiment; it is not a universal speed promise. All security and platform checks remain required.
 
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. 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.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.33.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.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.35.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.35.0/docs/guides/ai-sdlc-integration.md

@@ -0,0 +1,164 @@
+# Integrate an external AI SDLC client
+
+An external client can invoke the installed `agent-lifecycle` CLI as a bounded
+subprocess and display its receipts. A task tracker, IDE, script or other client
+uses the same contract; no task-tracker service or private Python import is
+required. ALK owns workflow authority. The client owns process execution,
+presentation and reconciliation. The host owns model execution and genuine usage
+attestation; an independent reviewer owns review conclusions.
+
+This guide defines a provider-neutral CLI consumer contract for release 2.35.0.
+It adds no server, daemon, provider broker, runtime API or second state machine.
+The supported surface below is deliberately bounded. Other operations retain
+their [CLI contracts](../reference/cli.md).
+
+## Negotiate before mutation
+
+The client MUST run `agent-lifecycle version` and require
+`agent-lifecycle-version.v1`. It MUST compare `version` with its explicitly tested
+version mapping. The 2.35.0 contract does not qualify an earlier or later release
+merely because its version looks similar. The client MUST refuse mutations for
+an unknown version, unknown `schemaVersion`, unsupported action or incompatible
+required field. Read-only diagnostics can remain available, clearly labelled as
+unqualified. Do not guess flags, silently drop guards or downgrade a schema.
+
+Use `agent-lifecycle schema list --scope core` and
+`agent-lifecycle schema show <schema-id>` for the available descriptive contracts;
+use the installed command's `--help` for its arguments. The registry is not a
+universal wire protocol or authorization service. Runtime validators also check
+cross-file bindings. Keep a client-owned mapping of tested versions, operations,
+receipt/action schemas, required fields and refusal outcomes.
+
+Invoke an argument array with shell evaluation disabled. Use an explicit
+repository working directory, bounded input/output and timeout, and preserve
+stdout, stderr, exit code, timestamps and exact executable identity. On timeout,
+process failure, malformed/truncated output or an unknown receipt, record an
+unknown result and reconcile before another mutation. CLI argument errors can
+write parser diagnostics to stderr instead of JSON. A handled lifecycle error
+uses `agent-lifecycle-error.v1` and exit 2. Exit 0 alone does not prove success:
+`workflow continue` can return `INPUT_REQUIRED`, `WAITING` or `BLOCKED` with exit 0.
+
+## Bind one request to native authority
+
+The client MUST retain the repository, package ID, plan revision and full plan
+digest, reviewed manifest and lock identities, run ID/state path, current state
+revision, source revision, task ID and attempt when applicable. Bind all supplied
+result, review, audit, usage and proof artifacts to that same lineage. Paths for
+continuation inputs are repository-relative. Full digests are identities; a
+shortened display value is not an input substitute.
+
+The frozen manifest and `agent-plan-lock.v2` bind the reviewed plan. Freeze does
+not authorize execution. Native state and transitions govern authorization,
+dependency readiness, ownership, attempts, independent acceptance and completion.
+Current native state formats include `agent-workflow-state.v4` and
+`agent-workflow-state.v5`; support is an explicit client mapping, never permission
+to rewrite or migrate state automatically. Legacy migration uses its separate
+guarded command. A UI status is a projection of these facts, not authority.
+
+## Bounded operation map
+
+Each row names an existing command, its relevant schema/guard and its boundary.
+Optional receipt output files are evidence writes, not workflow authority writes.
+
+| Actor and operation | Existing command and schema/guard | Refusal and boundary |
+| --- | --- | --- |
+| Client: identify installation | `agent-lifecycle version`; `agent-lifecycle-version.v1`, `version` | Unknown version/schema refuses client mutation; no state transition. |
+| Client: verify plan inputs | `agent-lifecycle plan verify --manifest <manifest> --package-root <plan-root> --acceptance <checklist> --repository-root . --out <receipt>`; `agent-plan-verification-receipt.v1` | Inspect `status`, named checks and blockers. Missing/drifted lock, invalid traceability or ownership refuses readiness. Structural verification is not semantic review, authorization or acceptance. |
+| Client: project next action | `agent-lifecycle workflow continue` with the bindings below; `agent-workflow-continuation-receipt.v1`, nested `agent-workflow-continuation-action.v1` | Without `--apply`, no authority mutation. `requiredInputs`, blockers and route eligibility remain authoritative; projection launches no host or model. |
+| Authorized controller: apply one supported action | Same `workflow continue` request plus `--apply --projected-state-revision <n> --projected-action-digest <full-digest>`; same receipt/action schemas, existing transition validators | Requires current revision, exact action digest, source/plan/lock lineage and authentic route-specific inputs. Missing inputs, stale lineage, missing authorization, invalid ownership or independent review refuse the transition. Only `APPLIED` with matching committed state/event establishes application. |
+| Controller/host: select model class | `agent-lifecycle model route --profile <routing-profile> --host-profile <host-profile> --request <request>`; input `agent-lifecycle-model-route-request.v1`, output `agent-lifecycle-model-route-decision.v1` | Deterministic policy/capability/context/critical-review checks; unsuitable critical routes refuse. A decision launches no model and grants no workflow transition. |
+| Host/controller: validate usage | `agent-lifecycle model usage-check --receipt <usage> --route-decision <decision> --budget-targets <targets>`; input `agent-lifecycle-model-usage-receipt.v1` | Validates host attestation, route binding and budgets; invalid/unattested usage returns `model-usage-validation-failed`. Validation alone cannot accept a task. |
+
+The model route and usage commands accept some optional flags; this consumer
+contract supplies the explicit profiles, decision and budget targets so their
+identities are reviewable. Use [Model routing](../reference/model-routing.md)
+for existing role classes, quality floors, critical-review rules and host-local
+model mapping. Portable plans do not select concrete provider models. This guide
+does not replace that routing policy or qualify a new host.
+
+## Project, supply inputs, then apply
+
+This is a command template, not authorization to mutate a real run:
+
+```bash
+agent-lifecycle workflow continue \
+  --state work/run.state.json \
+  --manifest work/plans/release-x/plan.manifest.json \
+  --lock work/plans/release-x/plan.lock.json \
+  --operation-id client-start-WS-01-attempt-1 \
+  --expected-revision 7 \
+  --source-revision <source-sha> \
+  --reason "project a bounded task start" \
+  --task WS-01
+```
+
+For a qualified receipt, the client MUST check `mode: PROJECT`, `stateWritten:
+false`, `modelCallsStarted: false` and `hostLaunchStarted: false`, then inspect
+`status`, `plan`, `stateBefore`, `action`, `requiredInputs` and `blockers`.
+`READY` means that this action can be submitted to its guards. It does not mean
+the task has started or finished. When `nextAction.argv` is present, it contains
+argument tokens with `shell: false`; verify the executable, bindings and allowed
+route before invoking them. Never execute receipt content as a shell string.
+
+Supply the inputs requested by the actual route, then project again if the
+inputs changed. Preserve the operation identity. To apply, use the same request
+and inputs with `--apply`, the returned `action.stateRevision` as
+`--projected-state-revision`, and its full `action.actionDigest` as
+`--projected-action-digest`. Keep `--expected-revision` current. ALK recomputes
+the action and calls its existing transition; a cached projection cannot bypass
+the guards. An applied one-step receipt uses `mode: APPLY`, `status: APPLIED`,
+`stateWritten: true`, `stateAfter` and `appliedEvent` for the committed revision.
+
+| Projected route | Inputs and native boundary |
+| --- | --- |
+| Authorization / run start | `--authorization-receipt` when required; reviewed plan, matching lock and separate execution authorization. A draft or `PLAN_ONLY` is insufficient. |
+| Task start | Eligible `--task`; `--risk-profile` or strategy inputs when required by the selected route. Native dependency, ownership, attempt and budget guards still apply. Recording task start does not launch a host. |
+| Task result | `--result`, plus `--model-usage-receipt` and `--budget-targets` where required. Current source/change-set claims and authentic bound usage are checked before review. |
+| Task review outcome | `--review`, `--implementation-audit` where required, and `--finding-id` for applicable remediation. The independent reviewer supplies the conclusion; the controller applies it. |
+| Final audit outcome / finalization | `--final-audit` and outcome-specific `--verdict`, `--task-id`, `--finding-id`; finalization additionally consumes the required proof, integrity and completion-gate inputs. Follow the projected `requiredInputs` and the existing finalization gates. |
+
+See [Workflow continuation](../reference/workflow-continuation.md) for the full
+existing flag map and bounded bundle mode. The client MUST stop at host, model,
+reviewer, operator, plan-authority or resource boundaries. It MUST NOT create
+synthetic review/usage attestations, edit state/lock by hand or turn a local
+`done` boolean into native acceptance. Task acceptance, final independent audit,
+native finalization and downstream publication remain separate gates.
+
+## Reconcile an unknown result
+
+Before dispatch, retain one operation ID with the exact request, projected state
+revision/action digest and input identities. ALK's native operation ledger rejects
+an already-used operation ID; it is not a cached-response service. A retry with
+a new ID is not a safe way to discover whether the previous mutation happened.
+
+After a lost response, the client MUST stop mutation and read the canonical state,
+its declared event journal and any retained native receipt. Match run/package,
+operation ID, committed revision, event type/task/attempt and artifact bindings.
+Workflow events use `agent-workflow-event.v1`. If the matching event and state
+establish the intended transition, record that observed fact and project the next
+action without repeating it. Do not infer success from a later revision alone.
+
+If the operation is provably uncommitted and the state/journal agree, obtain a
+fresh projection and follow the existing unused-operation guards before retry.
+If evidence is missing, contradictory or indicates partial persistence, retain
+UNKNOWN and stop for the existing recovery/operator route. Do not repair history
+by writing a success event or replaying a host command. Native operation guards
+do not guarantee exactly-once execution of arbitrary host/model/external side
+effects; those require their own host-owned reconciliation evidence.
+
+## Keep usage and evidence honest
+
+Retain exact source, executable/configuration/input digests, command/exit/time,
+receipt and changed-file identities. Record genuine model usage through the
+existing host-attested receipt and qualified normalizer; a UI estimate, fixture
+or serialization helper cannot attest usage. Model-backed task results refuse
+missing, unattested or lineage-drifted usage. Unavailable tokens, provider cost
+and full host input remain `UNKNOWN`/null, not measured zero. Keep shell/process,
+validation, model invocation and physical CI counts separate, and retain prior
+costs, failed attempts and original clocks across retries.
+
+Disposable-fixture conformance is `UNIT_ONLY`. A deterministic consumer test can
+observe zero model calls; it proves neither live review, host enforcement nor
+production qualification. See [Host-local token accounting](../reference/host-local-token-accounting.md)
+and [Safe artifact authoring](../reference/safe-artifact-authoring.md). A valid
+JSON artifact does not make its claims true or complete a bound run.

agent_lifecycle_kit-2.35.0/docs/ru/guides/ai-sdlc-integration.md

@@ -0,0 +1,171 @@
+# Интеграция внешнего клиента AI SDLC
+
+Внешний клиент может вызывать установленный `agent-lifecycle` CLI как ограниченный
+subprocess и показывать receipts. Задачник, IDE, скрипт и другой клиент используют
+один контракт; отдельный сервис задачника и private Python imports не требуются.
+ALK владеет workflow authority. Клиент отвечает за запуск процесса, отображение
+и сверку результата. Host отвечает за выполнение модели и подлинную usage
+attestation; независимый reviewer — за выводы review.
+
+Руководство задаёт provider-neutral контракт CLI-потребителя для release 2.35.0.
+Оно не добавляет server, daemon, provider broker, runtime API или вторую state
+machine. Описанная поверхность намеренно ограничена. Остальные операции сохраняют
+свои [CLI-контракты](../reference/cli.md).
+
+## Согласовать совместимость до mutation
+
+Клиент MUST выполнить `agent-lifecycle version` и потребовать
+`agent-lifecycle-version.v1`. Он MUST сравнить `version` с явно протестированной
+таблицей версий. Контракт 2.35.0 не квалифицирует более ранний или поздний release
+только по сходству номера. Клиент MUST отказать в mutation при неизвестной версии,
+неизвестной `schemaVersion`, неподдерживаемом action или несовместимом обязательном
+поле. Read-only диагностика может оставаться доступной с явной пометкой об
+отсутствии квалификации. Нельзя угадывать flags, молча удалять guards или понижать
+версию schema.
+
+Используйте `agent-lifecycle schema list --scope core` и
+`agent-lifecycle schema show <schema-id>` для доступных описательных контрактов;
+аргументы проверяйте через `--help` установленной команды. Registry не является
+универсальным wire protocol или сервисом авторизации. Runtime validators также
+проверяют межфайловые bindings. Клиент хранит свою таблицу проверенных версий,
+операций, receipt/action schemas, обязательных полей и исходов отказа.
+
+Передавайте массив аргументов с отключённым shell evaluation. Задавайте явный
+рабочий каталог repository, пределы input/output и timeout; сохраняйте stdout,
+stderr, exit code, timestamps и точную identity executable. При timeout, отказе
+процесса, повреждённом/усечённом output или неизвестном receipt фиксируйте неизвестный
+результат и сверяйте факт до следующей mutation. Ошибки аргументов CLI могут выводить
+parser diagnostics в stderr вместо JSON. Обработанная lifecycle error использует
+`agent-lifecycle-error.v1` и exit 2. Exit 0 сам по себе не доказывает успех:
+`workflow continue` может вернуть `INPUT_REQUIRED`, `WAITING` или `BLOCKED` с exit 0.
+
+## Привязать запрос к native authority
+
+Клиент MUST сохранять repository, package ID, plan revision и полный plan digest,
+identities проверенного manifest и lock, run ID/state path, текущую state revision,
+source revision, task ID и attempt, когда применимо. Все result, review, audit,
+usage и proof artifacts связываются с той же lineage. Пути continuation inputs —
+repository-relative. Полные digests являются identities; сокращённое отображение
+не заменяет входное значение.
+
+Frozen manifest и `agent-plan-lock.v2` связывают проверенный план. Freeze не
+авторизует исполнение. Native state и transitions определяют authorization,
+готовность зависимостей, ownership, attempts, независимую acceptance и completion.
+Текущие native state formats включают `agent-workflow-state.v4` и
+`agent-workflow-state.v5`; поддержка задаётся явной таблицей клиента и не разрешает
+автоматически переписывать или мигрировать state. Legacy migration использует
+отдельную guarded command. Статус UI — проекция этих фактов, а не authority.
+
+## Ограниченная карта операций
+
+Каждая строка называет существующую команду, её schema/guard и boundary.
+Необязательные output-файлы receipts являются evidence writes, а не workflow
+authority writes.
+
+| Actor и операция | Существующая команда и schema/guard | Отказ и boundary |
+| --- | --- | --- |
+| Клиент: определить установку | `agent-lifecycle version`; `agent-lifecycle-version.v1`, `version` | Неизвестная version/schema запрещает mutation клиента; state transition отсутствует. |
+| Клиент: проверить входы плана | `agent-lifecycle plan verify --manifest <manifest> --package-root <plan-root> --acceptance <checklist> --repository-root . --out <receipt>`; `agent-plan-verification-receipt.v1` | Проверить `status`, именованные checks и blockers. Отсутствующий/изменённый lock, некорректная traceability или ownership запрещают готовность. Структурная проверка не является semantic review, authorization или acceptance. |
+| Клиент: спроецировать следующий action | `agent-lifecycle workflow continue` с bindings ниже; `agent-workflow-continuation-receipt.v1`, вложенный `agent-workflow-continuation-action.v1` | Без `--apply` нет authority mutation. `requiredInputs`, blockers и допустимость route остаются определяющими; projection не запускает host или модель. |
+| Авторизованный controller: применить один поддерживаемый action | Тот же запрос `workflow continue` плюс `--apply --projected-state-revision <n> --projected-action-digest <full-digest>`; те же receipt/action schemas и существующие transition validators | Требуются текущая revision, точный action digest, source/plan/lock lineage и подлинные route-specific inputs. Отсутствующие inputs, устаревшая lineage, отсутствие authorization, некорректная ownership или независимое review запрещают transition. Только `APPLIED` с совпадающими committed state/event устанавливает факт применения. |
+| Controller/host: выбрать model class | `agent-lifecycle model route --profile <routing-profile> --host-profile <host-profile> --request <request>`; вход `agent-lifecycle-model-route-request.v1`, выход `agent-lifecycle-model-route-decision.v1` | Детерминированные policy/capability/context/critical-review checks; неподходящий critical route получает отказ. Decision не запускает модель и не разрешает workflow transition. |
+| Host/controller: проверить usage | `agent-lifecycle model usage-check --receipt <usage> --route-decision <decision> --budget-targets <targets>`; вход `agent-lifecycle-model-usage-receipt.v1` | Проверяются host attestation, route binding и budgets; некорректная/unattested usage возвращает `model-usage-validation-failed`. Одна validation не принимает task. |
+
+Некоторые flags model route и usage необязательны; этот контракт потребителя
+передаёт явные profiles, decision и budget targets, чтобы их identities можно было
+проверить. Существующие role classes, quality floors, critical-review rules и
+host-local mapping моделей описаны в [Model routing](../reference/model-routing.md).
+Portable plans не выбирают конкретные provider models. Это руководство не
+заменяет routing policy и не квалифицирует новый host.
+
+## Projection, входы, затем apply
+
+Это шаблон команды, а не разрешение изменять настоящий run:
+
+```bash
+agent-lifecycle workflow continue \
+  --state work/run.state.json \
+  --manifest work/plans/release-x/plan.manifest.json \
+  --lock work/plans/release-x/plan.lock.json \
+  --operation-id client-start-WS-01-attempt-1 \
+  --expected-revision 7 \
+  --source-revision <source-sha> \
+  --reason "project a bounded task start" \
+  --task WS-01
+```
+
+Для квалифицированного receipt клиент MUST проверить `mode: PROJECT`,
+`stateWritten: false`, `modelCallsStarted: false` и `hostLaunchStarted: false`,
+затем изучить `status`, `plan`, `stateBefore`, `action`, `requiredInputs` и
+`blockers`. `READY` означает возможность передать этот action его guards. Это
+не означает, что task начат или завершён. Если есть `nextAction.argv`, это tokens
+аргументов с `shell: false`; до вызова проверьте executable, bindings и допустимый
+route. Нельзя исполнять содержимое receipt как shell string.
+
+Передайте входы, запрошенные фактическим route, и повторите projection, если входы
+изменились. Сохраните operation identity. Для apply используйте тот же запрос
+и inputs с `--apply`, вернувшимся `action.stateRevision` как
+`--projected-state-revision` и полным `action.actionDigest` как
+`--projected-action-digest`. `--expected-revision` должен оставаться текущим.
+ALK пересчитывает action и вызывает существующий transition; cached projection
+не обходит guards. Применённый one-step receipt использует `mode: APPLY`,
+`status: APPLIED`, `stateWritten: true`, `stateAfter` и `appliedEvent` для committed
+revision.
+
+| Projected route | Inputs и native boundary |
+| --- | --- |
+| Authorization / run start | `--authorization-receipt`, когда требуется; проверенный план, совпадающий lock и отдельная execution authorization. Draft или `PLAN_ONLY` недостаточны. |
+| Task start | Допустимый `--task`; `--risk-profile` или strategy inputs, когда выбранный route их требует. Native dependency, ownership, attempt и budget guards сохраняются. Запись task start не запускает host. |
+| Task result | `--result`, а также `--model-usage-receipt` и `--budget-targets`, когда требуются. Текущие source/change-set claims и подлинная bound usage проверяются до review. |
+| Task review outcome | `--review`, `--implementation-audit`, когда требуется, и `--finding-id` для применимой remediation. Независимый reviewer предоставляет вывод; controller применяет его. |
+| Final audit outcome / finalization | `--final-audit` и соответствующие outcome `--verdict`, `--task-id`, `--finding-id`; finalization дополнительно потребляет обязательные proof, integrity и completion-gate inputs. Следуйте projected `requiredInputs` и существующим finalization gates. |
+
+Полная существующая карта flags и bounded bundle mode приведены в
+[Workflow continuation](../reference/workflow-continuation.md). Клиент MUST
+останавливаться на host, model, reviewer, operator, plan-authority и resource
+boundaries. Он MUST NOT создавать синтетические review/usage attestations,
+редактировать state/lock вручную или превращать локальный boolean `done` в native
+acceptance. Task acceptance, final independent audit, native finalization и
+последующая publication остаются отдельными gates.
+
+## Сверить неизвестный результат
+
+До dispatch сохраняйте один operation ID с точным запросом, projected state
+revision/action digest и identities inputs. Native operation ledger ALK отклоняет
+уже использованный operation ID; это не сервис cached responses. Retry с новым
+ID не является безопасным способом узнать, произошла ли предыдущая mutation.
+
+После потери ответа клиент MUST остановить mutation и прочитать canonical state,
+объявленный в нём event journal и сохранённый native receipt, если он есть.
+Сверьте run/package, operation ID, committed revision, event type/task/attempt и
+artifact bindings. Workflow events используют `agent-workflow-event.v1`. Если
+совпадающие event и state устанавливают нужный transition, запишите наблюдаемый
+факт и спроецируйте следующий action без повтора transition. Одна более поздняя
+revision не доказывает успех.
+
+Если достоверно установлено, что operation не committed, а state/journal
+согласованы, получите свежую projection и соблюдайте существующие guards
+неиспользованной operation до retry. Если evidence отсутствует, противоречит
+друг другу или указывает на partial persistence, сохраните UNKNOWN и остановитесь
+для существующего recovery/operator route. Нельзя исправлять историю записью
+успешного event или повтором host-команды. Native operation guards не гарантируют
+exactly-once исполнение произвольных host/model/external side effects; для них
+нужны собственные host-owned evidence сверки.
+
+## Сохранять подлинные usage и evidence
+
+Сохраняйте exact source, digests executable/configuration/inputs, command/exit/time,
+identities receipts и изменённых файлов. Настоящая model usage передаётся через
+существующий host-attested receipt и квалифицированный normalizer; оценка UI,
+fixture или serialization helper не создают attestation. Model-backed task results
+отказывают при отсутствующей, unattested или lineage-drifted usage. Недоступные
+tokens, provider cost и полный host input остаются `UNKNOWN`/null, а не измеренным
+нулём. Считайте shell/process, validation, model invocations и physical CI отдельно;
+сохраняйте прежние расходы, failed attempts и исходные часы через retries.
+
+Conformance на disposable fixture имеет статус `UNIT_ONLY`. Детерминированный
+consumer test может наблюдать ноль model calls; он не доказывает live review,
+host enforcement или production qualification. См.
+[Host-local token accounting](../reference/host-local-token-accounting.md) и
+[Safe artifact authoring](../reference/safe-artifact-authoring.md). Корректный
+JSON artifact не делает его утверждения истинными и не завершает bound run.

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.33.0"
+version = "2.35.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.16"
@@ -42,9 +42,9 @@ dependencies = []
 
 [dependency-groups]
 quality = [
-  "ruff==0.17.1",
+  "ruff==0.17.3",
   "mypy==2.4.0",
-  "coverage==7.16.2",
+  "coverage==7.17.0",
   "jsonschema==4.26.0",
 ]
 
@@ -104,3 +104,7 @@ check_untyped_defs = true
   "benchmarks/reference-tasks/rt05-s2-evidence-task/task.md",
   "benchmarks/reference-tasks/rt05-s2-evidence-task/oracle.json",
 ]
+
+"share/agent-lifecycle-kit/integration/en" = ["docs/guides/ai-sdlc-integration.md"]
+"share/agent-lifecycle-kit/integration/ru" = ["docs/ru/guides/ai-sdlc-integration.md"]
+"share/agent-lifecycle-kit/integration" = ["tests/cli/fixtures/external-consumer-cases.json"]

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.33.0"
+__version__ = "2.35.0"

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0}/src/agent_lifecycle/accounting/declared_ledger.py

@@ -21,7 +21,11 @@ from agent_lifecycle.accounting.declared_ledger_records import (
     _r11_role_prefix_record,
 )
 from agent_lifecycle.contracts import LifecycleError, canonical_bytes, canonical_digest
-from agent_lifecycle.contracts.authority_io import normalize_authority_path, read_authority_bytes
+from agent_lifecycle.contracts.authority_io import (
+    normalize_authority_path,
+    read_authority_bytes,
+    replace_authority_bytes,
+)
 from agent_lifecycle.contracts.bounded_json import load_bounded_json as _r11_json
 from agent_lifecycle.contracts.errors import require_condition as _require
 
@@ -615,7 +619,8 @@ def advance_coordinator_cost_head(project_root: Path, *, source_path: str) -> di
         _sync_directory(archive)
     exclusive(temporary, canonical_bytes(head))
     _sync_directory(path.parent)
-    temporary.replace(path)
+    replace_authority_bytes(path, canonical_bytes(head), root=primary)
+    temporary.unlink()
     _sync_directory(path.parent)
     pending.unlink()
     _sync_directory(path.parent)

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0}/src/agent_lifecycle/accounting/declared_ledger_legacy.py

@@ -45,9 +45,15 @@ def _read_private(
 
 
 def _r11_git(root: Path, *args: str) -> bytes:
+    executable = os.environ.get("ALK_ACCOUNTING_GIT_EXECUTABLE")
+    _require(
+        executable is None or (bool(executable) and "\0" not in executable and Path(executable).is_absolute()),
+        "r11-source-unavailable",
+        "configured Git executable must be a nonempty absolute path",
+    )
     try:
         result = subprocess.run(
-            ["git", *args],
+            [executable if executable is not None else "git", *args],
             cwd=root,
             capture_output=True,
             timeout=15,

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0}/src/agent_lifecycle/changesets/git.py

@@ -63,12 +63,24 @@ def changed_files(cwd: Path, *, base: str | None = None) -> list[str]:
 def resolve_revision(cwd: Path, revision: str, *, label: str = "revision") -> str:
     value = normalize_git_revision(revision, label=label)
     try:
-        completed = run_bounded_command(
-            ["git", "rev-parse", "--verify", "--end-of-options", f"{value}^{{commit}}"],
-            cwd=cwd,
-            timeout_seconds=GIT_TIMEOUT_SECONDS,
-            max_stdout_bytes=128,
-        )
+        # Retry only the observed Windows ownership refusal, once, for this
+        # read-only lookup through the same bounded owner.
+        for attempt in range(2):
+            try:
+                completed = run_bounded_command(
+                    ["git", "rev-parse", "--verify", "--end-of-options", f"{value}^{{commit}}"],
+                    cwd=cwd,
+                    timeout_seconds=GIT_TIMEOUT_SECONDS,
+                    max_stdout_bytes=128,
+                )
+                break
+            except LifecycleError as exc:
+                if (
+                    attempt != 0
+                    or exc.code != "bounded-process-group-unavailable"
+                    or exc.message != "Cannot own the Windows child group"
+                ):
+                    raise
     except (OSError, LifecycleError) as exc:
         raise LifecycleError("invalid-git-revision", f"{label}: revision cannot be resolved") from exc
     resolved = completed.stdout.strip().splitlines()

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0}/src/agent_lifecycle/changesets/git_io.py

@@ -46,10 +46,20 @@ def _windows_cleanup(process: subprocess.Popen[bytes]) -> Callable[[], None] | N
     kernel.CloseHandle.restype = wintypes.BOOL
     handle = kernel.CreateJobObjectW(None, None)
     if not handle:
-        raise LifecycleError("bounded-process-group-unavailable", "Cannot own the Windows child group")
+        native_error = vars(ctypes)["get_last_error"]()
+        raise LifecycleError(
+            "bounded-process-group-unavailable",
+            "Cannot own the Windows child group",
+            {"nativeStage": "CreateJobObjectW", "winError": native_error},
+        )
     if not kernel.AssignProcessToJobObject(handle, getattr(process, "_handle", None)):
+        native_error = vars(ctypes)["get_last_error"]()
         kernel.CloseHandle(handle)
-        raise LifecycleError("bounded-process-group-unavailable", "Cannot own the Windows child group")
+        raise LifecycleError(
+            "bounded-process-group-unavailable",
+            "Cannot own the Windows child group",
+            {"nativeStage": "AssignProcessToJobObject", "winError": native_error},
+        )
 
     def cleanup() -> None:
         terminated = kernel.TerminateJobObject(handle, 1)

{agent_lifecycle_kit-2.33.0 → agent_lifecycle_kit-2.35.0/src/agent_lifecycle_kit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.33.0
+Version: 2.35.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
@@ -33,16 +33,16 @@ Dynamic: license-file
 
 **Agent Lifecycle Kit (ALK)** coordinates coding-agent work through a verifiable finish. It keeps the requested outcome, reviewed plan, execution boundaries, evidence and acceptance decisions connected while the external agent changes the project.
 
-The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
+Release 2.35 documents the [external AI SDLC CLI contract](docs/guides/ai-sdlc-integration.md) and eight bounded consumer cases. Wheel/sdist include both guides and case JSON; the plugin ships the paired CLI contract. Native authority and release gates remain required.
 
-Release 2.33 simplifies selected internal boundaries and checks the release validators themselves. It removes two private-import allowances (83 to 81), reduces one final-evidence flow from 58 to 41 branches, and adds selected Ruff/strict-mypy checks without increasing runtime baselines. Existing architecture debt remains visible. See [the 2.33 scope](docs/reference/cli.md#release-233-selected-architecture-and-tooling-quality). Release 2.32 adds [advisory process observations and eight selected reading routes](docs/reference/cli.md#release-232-process-observations-and-reading-scope); missing whole-run evidence and provider usage remain null/UNAVAILABLE. ALK provides a verifiable finish for external-agent work with proportionate control. Release 2.31 strengthens supported-text secret checks, enforces global branch and critical-file coverage floors, and gives a bounded structural refusal for malformed legacy state. See [the 2.31 check boundaries](docs/reference/cli.md#release-231-bounded-quality-checks). See [workflow history and recovery](docs/reference/workflow-state-storage.md) for the earlier storage and renewal features. Install the Python package as well as the plugin for the new CLI commands.
+The provider-neutral workflow works with Codex, Claude Code, Qwen Code, Goose, OpenInterpreter, Pi, Grok Build, or another CLI. Provider commands, model choice and secret handling stay in adapters or host-local profiles.
 
 Release 2.28 adds [bounded lifecycle and accounting baselines](docs/reference/performance-and-resource-budgets.md#release-228-lifecycle-and-accounting-baselines). Repository tools measure real read-only operations and separate fixture preparation from operation and subprocess time. The Windows fixture comparison observed a 13.08% median reduction in one six-sample experiment; it is not a universal speed promise. All security and platform checks remain required.
 
 ## Quick start
 Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.23 adds [compact S0/S1 authoring](docs/reference/tier-proportional-plan-packages.md) with explicit checklist completion and unchanged approval gates. Release 2.22 adds [conservative plan-review reuse](docs/reference/conservative-delta-review.md) with independent current applicability and no automatic full reruns. Release 2.21 adds [command accounting, bounded preparation and response recovery](docs/reference/source-native-workflow-accounting.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. 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.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.33.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.15, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.35.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.33.0 → agent_lifecycle_kit-2.35.0}/src/agent_lifecycle_kit.egg-info/SOURCES.txt

@@ -14,6 +14,8 @@ benchmarks/reference-tasks/rt04-s1-managed-task/oracle.json
 benchmarks/reference-tasks/rt04-s1-managed-task/task.md
 benchmarks/reference-tasks/rt05-s2-evidence-task/oracle.json
 benchmarks/reference-tasks/rt05-s2-evidence-task/task.md
+docs/guides/ai-sdlc-integration.md
+docs/ru/guides/ai-sdlc-integration.md
 src/agent_lifecycle/__init__.py
 src/agent_lifecycle/__main__.py
 src/agent_lifecycle/_version.py
@@ -535,4 +537,5 @@ src/agent_lifecycle_kit.egg-info/PKG-INFO
 src/agent_lifecycle_kit.egg-info/SOURCES.txt
 src/agent_lifecycle_kit.egg-info/dependency_links.txt
 src/agent_lifecycle_kit.egg-info/entry_points.txt
-src/agent_lifecycle_kit.egg-info/top_level.txt
+src/agent_lifecycle_kit.egg-info/top_level.txt
+tests/cli/fixtures/external-consumer-cases.json

agent_lifecycle_kit-2.35.0/tests/cli/fixtures/external-consumer-cases.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "external-consumer-cases.v1",
+  "evidenceBoundary": "UNIT_ONLY",
+  "testedVersions": ["2.34.0", "2.35.0"],
+  "versionSchema": "agent-lifecycle-version.v1",
+  "continuationSchema": "agent-workflow-continuation-receipt.v1",
+  "actionSchema": "agent-workflow-continuation-action.v1",
+  "cases": [
+    {"id": "readonly-projection", "outcome": "READY"},
+    {"id": "guarded-action", "outcome": "APPLIED"},
+    {"id": "stale-guards", "codes": ["continuation-projection-state-mismatch", "continuation-projection-action-mismatch"]},
+    {"id": "missing-input", "outcome": "INPUT_REQUIRED"},
+    {"id": "unattested-usage", "code": "model-usage-validation-failed"},
+    {"id": "critical-route", "code": "model-route-unsupported"},
+    {"id": "lost-reply", "outcome": "RECONCILED"},
+    {"id": "incompatible-contract", "outcome": "CONSUMER_REFUSED"}
+  ]
+}