@zq-silk/yui 0.15.6 → 0.15.8

package/docs/release-workflow.md

@@ -0,0 +1,303 @@
+# Authorized release operations
+
+A release workflow is an explicitly chosen, authorized sequence of
+external release effects — pull requests, CI confirmation, merges, version
+tags, npm publishes, fresh-install smoke tests, CLI updates, Controller
+replacements, Project migrations, and post-verification. It is a specialized
+external-effect facility, not Yui's Task planning or Agent execution model.
+The Agent selects a predeclared plan, and the facility drives that plan
+from durable state: every transition is persisted before the next external
+call, so a crash, timeout, or revoked grant never leaves the release guessing.
+
+Two task-level record families back it:
+
+- **CapabilityGrant** (`capability-grant-N`) — the authority. A named granter
+  scopes a grant to actions, parameter bounds, an expiry, a use count, and an
+  irreversibility ceiling.
+- **ReleaseWorkflow** (`release-workflow-N`) — the plan and its progress: an
+  exact source (repository + pinned commit, optionally an artifact), an
+  immutable ordered step plan, and one persisted record per step.
+
+The engine (`src/release/releaseWorkflowEngine.ts`) is a pure library; the
+`yui task workflow` and `yui task grant` commands drive it. Every external
+system sits behind `ReleaseWorkflowPorts`
+(`src/release/releaseWorkflowPorts.ts`), so the whole workflow is testable
+with deterministic fakes and no real GitHub, npm, git, Controller, or process
+side effect.
+
+## Authorization model
+
+Every (re)submission of a step passes `checkGrant(grant, request, now)`
+(`src/grant/capabilityGrant.ts`) **before** the external call. The step kind
+is the grant action: a grant lists the step kinds it authorizes, for example
+`--action npm-publish --action version-tag`. The decision is fail-closed —
+every denial carries a machine-readable reason and stops the run:
+
+| Reason | Meaning |
+| --- | --- |
+| `grant-missing` | No grant record is bound to the workflow (engine-level). |
+| `grant-revoked` | The grant was revoked by an operator. |
+| `grant-expired` | The wall clock passed the grant's `expiresAt`. |
+| `grant-uses-exhausted` | The grant's `maxUses` has been consumed. |
+| `grant-action-not-allowed` | The step kind is not in the grant's actions. |
+| `grant-parameter-missing` | A bounded parameter is absent from the step. |
+| `grant-parameter-value-not-allowed` | A bounded parameter has an out-of-bounds value. |
+| `grant-irreversibility-exceeds-ceiling` | The step is more irreversible than the grant's ceiling. |
+
+Additional rules:
+
+- **One use per authorized submission.** The engine records a grant use
+  between the successful decision and the external call, so a `maxUses` grant
+  fails closed on the attempt that would exceed it.
+- **Irreversible steps need a confirmed prefix.** A step marked
+  `irreversible` additionally requires every earlier step to be `succeeded`;
+  otherwise the step fails with `prerequisite-not-confirmed` and the run
+  stops. This is what keeps an `npm-publish` from running behind a failed PR.
+- **Denials are recorded.** When a pending step is denied, the engine starts
+  and fails the step with the denial in its log, so `workflow status` shows
+  exactly where authorization stopped.
+- **Rebinding.** A revoked, expired, or too-narrow grant does not dead-end
+  the workflow. Issue a new grant and resume with
+  `yui task workflow resume <task> <workflow> --grant <new-grant>`; the plan,
+  source, and all confirmed step evidence are immutable across the rebind.
+
+## Stable Task-final Review contract
+
+Compatible CLI package updates and Controller replacements do not change an
+active Task's final-review capability. Managed Sessions use the ordinary
+`yui` command, compatibility is checked by protocol and storage identity, and
+a replacement Leader presents the contract already established by durable Task
+evidence. No version-aware Operator action is required.
+Candidate and Task-final ReviewRound records must all carry that one contract.
+Conflicting records fail closed; there is no rebind event, recovery command, or
+second contract state machine.
+
+## CLI and Controller release boundary
+
+The global `yui` command is the stable user and managed-Session interface. It
+does not follow `runtime/active-release.json` for ordinary commands: that
+pointer selects the Controller release, not the CLI package. This keeps CLI,
+Operator Session, and Controller replacement compatible without pinning every
+command to one immutable build.
+
+A source-checkout or otherwise unverified local CLI is not this published
+interface. When `YUI_HOME` already names an active release, such a CLI fails
+before opening storage and reports its build/source, the durable Home identity,
+and its invocation class. `make install-local` continues to default to the
+checkout's isolated `output/dev/home`; explicitly pointing that launcher at a
+release-owned Home is rejected.
+
+An explicit `yui release activate <release-id|build-id>` is the one exception.
+The global CLI verifies the installed target release and its matching smoke
+receipt, then delegates the unchanged activation arguments to that target's
+`dist/cli.js`. The target release therefore owns the complete handover protocol
+and timeout hierarchy. A no-target activation, help, `--json`, and every other
+command remain on the global CLI. Activation does not add another ordinary CLI
+routing path.
+
+## Step catalog
+
+The plan is a fixed, predeclared subset of operations. Each plan entry has an
+id (unique within the workflow), a kind, optional params, and an optional
+irreversibility level (`none` | `reversible` | `irreversible`).
+
+| Kind | External effect | Authoritative identity |
+| --- | --- | --- |
+| `pr-create-or-reuse` | Creates the release PR, or reuses an open one for the head. | `pull-request` number |
+| `ci-confirm` | Reads the CI conclusion for the source ref; succeeds only on `success`. | — |
+| `merge` | Merges the named PR (squash by default). | — |
+| `version-tag` | Creates and pushes the annotated version tag. | `git-tag` name |
+| `npm-publish` | Publishes the tarball to the registry. | `npm-package` version |
+| `fresh-install-smoke` | Installs and runs the published package from the registry. | — |
+| `cli-update` | Updates the Yui CLI/Controller home via the existing update orchestrator. | `controller-home` |
+| `controller-replace` | Stops and restarts the file-task Controller. | — |
+| `project-migrate` | Runs the Project migration through the existing project command. | — |
+| `post-verify` | Runs an arbitrary verification command. | — |
+
+Steps may reference earlier evidence: a param value of
+`$externalId:<step-id>` resolves to the referenced step's confirmed external
+id at run time, so a `merge` step can consume the PR number the `pr` step
+produced without the operator knowing it in advance. A reference to an
+unconfirmed step fails the run rather than guessing.
+
+## Recovery and resume semantics
+
+A run always starts from the **resume cursor**: the first plan step whose
+status is not terminal (`succeeded` or `skipped`). There is no "start over" —
+confirmed steps are never re-run.
+
+Because every state transition is persisted before the next external call, a
+process exit at any point is recoverable: re-invoke `run` (or `resume`) and
+the engine continues from the first unconfirmed step. `--max-steps <n>` bounds
+a single run; a run that exhausts its budget mid-workflow returns
+`budget-exhausted` and the next invocation continues.
+
+In-flight steps are resolved by **authoritative identity query**, never by
+blind re-submission:
+
+- A step left `running` or `unknown` is queried first by its recorded
+  `externalIdentity`.
+  - `exists` → the step reaches `succeeded` **without a second submission**
+    (`unknown` is confirmed, `running` is completed).
+  - `unknown` → the run stops with outcome `unknown`; the step is never
+    re-submitted while its fate is unknowable.
+  - `absent` → the effect never landed, so the step is re-attempted (a
+    `running` step records the recovery attempt).
+- A `running` step **without** an external identity crashed before recording a
+  submission result. An irreversible step is queried through the port anyway
+  (the adapter consults its durable idempotency store): `exists` confirms the
+  step without a second submission, `unknown` stops as `unconfirmed`, and only
+  an authoritative `absent` re-attempts the step exactly once. A reversible
+  step always falls through and re-attempts under the same idempotency key.
+- A timeout **without** an external identity marks the step as `unknown`
+  (unconfirmed) so it is never re-submitted blindly; on resume it fails closed
+  as `unconfirmed`.
+- A `failed` step is retried on the next run; its `attempts` counter and logs
+  grow per attempt.
+
+Run outcomes: `succeeded`, `failed`, `unknown`, `unauthorized`,
+`unconfirmed`, `budget-exhausted`. Each carries a machine-readable
+`stopReason` (for example `unknown:publish`, `unauthorized:grant-revoked`,
+`budget-exhausted:verify`) and the list of step ids attempted that run.
+
+## Idempotency key contract
+
+Each step's idempotency key is **predeclared at create time** and never
+changes:
+
+```text
+<taskId>/<workflowId>/<stepId>
+```
+
+The key is passed to every `executeStep` call for that step, including
+retries after a confirmed-absent timeout. The port contract requires
+`executeStep` to be idempotent under the same key: a retried attempt must not
+produce a second side effect. The engine side of the contract is stricter
+still — it never calls `executeStep` for a step it has marked `unknown`; it
+re-queries by the recorded identity instead. The fakes record every key, so
+the test suite proves at-most-once execution directly.
+
+## Operator guide
+
+Session authority is checked against current durable bindings. Telemetry is
+grouped by Role/AgentRun, and process owners use PID/start identity. Storage
+changes follow the [single explicit upgrade boundary](sqlite-control-plane-design.md);
+ordinary commands never rewrite the Home schema.
+
+Grant issue and revoke are irreversible-authority operations. They require
+the current registered global Operator conversation. Its native session ID
+must match the durable live session binding: Codex commands use `CODEX_THREAD_ID`
+when present, otherwise `YUI_NATIVE_SESSION_ID`; Claude uses `YUI_NATIVE_SESSION_ID`.
+Host generation and launch-time Agent labels are not caller identity. Resuming
+the same conversation through another entry point does not revoke its authority.
+An unregistered, replaced, or ended conversation has no such authority.
+A managed Task Agent cannot self-issue or
+self-revoke a grant, and clearing the child-process environment does not
+confer user authority. The recorded granter/revoker is bound to that
+Operator session (`operator:<agent-id>`); there is no `--granter`/`--by`
+label to spoof.
+
+```sh
+# 1. The Operator session issues the authority for the release chain.
+yui task grant issue task-15 \
+  --action pr-create-or-reuse --action npm-publish --action post-verify \
+  --irreversibility-ceiling irreversible
+
+# 2. Create the workflow against an exact source and a predeclared plan.
+#    An npm-publish step requires a content-addressed source artifact: the
+#    immutable workflow source can never gain one later, so a plan without
+#    --source-artifact is rejected at creation.
+yui task workflow create task-15 \
+  --grant capability-grant-1 \
+  --source-repo acme/widget --source-commit abc1234deadbeef0000000000000000000000000 \
+  --source-artifact widget-1.0.0.tgz@sha512-<base64-integrity> \
+  --step pr:pr-create-or-reuse \
+  --step publish:npm-publish --step-irreversibility publish=irreversible \
+  --step-param publish:tarball=./dist/widget-1.0.0.tgz \
+  --step verify:post-verify --step-param verify:command='yui --version'
+
+# 3. Run (or resume) and inspect.
+yui task workflow run    task-15 release-workflow-1
+yui task workflow resume task-15 release-workflow-1 [--grant capability-grant-2] [--max-steps 1]
+yui task workflow status task-15 release-workflow-1
+
+# 4. Revoke authority at any time; the next step stops unauthorized.
+yui task grant revoke task-15 capability-grant-1
+```
+
+`workflow status` renders each step's status, attempt count, and confirmed
+external id, so an operator can see exactly where a release stopped and why.
+
+## Real-resource boundary
+
+Real execution happens only through the `yui` CLI, which wires the real
+adapter (`createReleaseWorkflowPorts`). The adapter is a thin shell over
+existing atomic operations — `gh`, `npm`, `git`, the CLI update orchestrator,
+Controller stop/restart, and `project migrate` — and it runs only when a human
+granter has issued an explicit CapabilityGrant that passes `checkGrant` for
+each step. A local test request never substitutes for that authority.
+
+The tag-triggered `publish.yml` workflow is the only maintained release smoke.
+It reuses the exact commit that passed core CI and adds only artifact assembly,
+fresh installation, and provenance checks required to publish.
+
+That workflow authenticates through npm Trusted Publishing (OIDC), so the
+release identity lives in two places outside the tag: `repository`, `bugs`, and
+`homepage` are copied verbatim from the source `package.json` into the published
+manifest by `assemble-runtime-package.mjs`, and the package's npm Trusted
+Publisher entry names the GitHub owner, repository, workflow file, and
+environment. npm compares `repository.url` against the building repository
+case-sensitively before accepting provenance. Renaming or transferring the
+GitHub repository therefore has to update those URLs and the npm Trusted
+Publisher entry together with the rename; otherwise the next tag reaches
+`npm publish` and fails there, after the tag and the gated build already
+succeeded.
+
+## Adapter security hardening
+
+The real adapter (`createReleaseWorkflowPorts`) applies additional safeguards
+beyond the engine's grant checks:
+
+- **Tarball option injection.** An option-looking tarball path (one starting
+  with `-`) is rejected before any subprocess — both the `tar -xOf` manifest
+  inspection and `npm publish` — sees it, so a crafted path can never be
+  interpreted as a flag.
+- **Tarball TOCTOU.** After the frozen `source.artifact.integrity` is verified,
+  the verified bytes are snapshotted to a workflow-private, read-only temp
+  file. Both the `tar -xOf` manifest inspection and `npm publish` read the
+  snapshot, never the live tarball path, so a replacement of the original file
+  after verification cannot change what is published. The snapshot is removed
+  when the step completes.
+- **Pinned external commands.** The adapter resolves the external commands it
+  shells out to (`gh`, `git`, `npm`, `tar`, `sh`) to absolute paths at
+  construction time via `resolveExecutable`, walking the caller's `PATH`
+  once. Every subprocess invocation uses the resolved path, so a later `PATH`
+  change (or a manipulated working directory) cannot redirect a release effect
+  to a different binary. An unresolvable command returns a synthetic failure
+  (exit 127) without invoking any binary.
+- **Pinned cli-update activation target.** Before the irreversible update
+  effect, the adapter persists the exact activation target — the Home plus the
+  global npm prefix (`bin/yui`) — to a durable file under the Home
+  (`release/cli-update-identity/<idempotency-key>.json`). A hard-exit recovery
+  query (a step with no recorded identity) reads this file and invokes that
+  pinned target; if the file is absent (the process exited before the
+  pre-effect persistence), the query returns `unknown` rather than deriving
+  the target from the resume caller's `npm prefix --global` or `PATH`, so a
+  different installation in the resume environment cannot attest the step.
+- **Controller lifecycle verification.** A `cli-update` recovery query proves
+  the replacement Controller actually owns the target Home: it runs
+  `yui --json controller status` (with `YUI_HOME` pinned to the recorded Home)
+  and requires a `current` controller resource whose `yuiHome` resolves to
+  that Home, then `yui --json controller identity` and requires the
+  authenticated Controller identity to match the activated artifact: the
+  Node.js executable path, the exact Controller entrypoint derived from the
+  pinned global binary, and the package version. Binary health alone (doctor,
+  `--version`) never confirms the handoff, and any unprovable state returns
+  `unknown`. This applies to both the identity-bearing query and the
+  hard-exit query (a step with no recorded identity).
+- **npm integrity comparison.** An `npm-publish` recovery query does not stop
+  at the published version: it fetches `dist.integrity` via
+  `npm view <pkg>@<version> dist.integrity` and compares it byte-for-byte with
+  the frozen `source.artifact.integrity`. A match confirms the step; the same
+  version with different bytes is a conflict and returns `unknown` (never a
+  confirmation, never a re-publish); a missing version is `absent`.

package/docs/roles-and-configuration.md

@@ -0,0 +1,113 @@
+# Roles, Profiles and execution configuration
+
+## Responsibilities
+
+Agent selects an execution component, connection plan and launch environment.
+Role selects an active Agent binding and portable behavior. Each binding retains
+independent runtime options. A Role can keep multiple bindings without creating
+parallel writers or sharing one binding's credentials/configuration with another.
+
+Task Roles are Task-local; global Roles provide configured defaults and global
+conversations. Role identity/configuration is not a writable runtime status.
+Session and Provider observations describe actual activity.
+
+An explicit Task-final Review uses an existing Task-local Reviewer Role without
+requiring a same-named global Role. A global Role is a creation template only
+when the requested Task Role does not exist. Availability, producer separation
+and the frozen review candidate still apply.
+
+## Profiles
+
+An Agent Profile combines portable behavior—instructions, Skills and access
+intent—with runtime intent. Runtime either follows the current Global Worker
+binding or explicitly selects an Agent with optional model and effort.
+`config profile reset` supplies `worker`, `explorer`, `implementer` and `reviewer`.
+
+Creating a Task Role from a Profile freezes its resolved behavior and binding.
+Later Profile or Global Worker edits do not rewrite existing Task Roles.
+Reapplying a Profile is an explicit configuration change. The selected Agent
+must match the target binding; explicit Role options override the corresponding
+template fields. A Profile is not a Session, workspace owner or resource grant.
+
+Native children inherit their parent Agent and authority. A Profile can guide
+their behavior; model/effort overrides require actual native tool support.
+They do not acquire Yui Roles, independent Assignments or broader scope.
+
+## Desired, effective and observed
+
+Desired settings are next-launch intent. An AgentRun and Session capture the
+effective launch: Agent/component, protocol, model, effort, permission strategy,
+workspace/environment, Role context and planning/delivery authority.
+
+Live run-configuration inspection separately reports what the Agent actually
+states. Unsupported and unknown are explicit; an accepted setter without a
+reported current value is not an observed match. Configuration reads do not
+modify the Agent to make the observation agree with desired settings.
+
+Worker binding changes preserve an active Assignment's Agent and effective
+snapshot; subsequent explicit dispatch uses the current selection. Leader
+replacement revokes the previous management entry without rewriting Worker
+Assignments. Changing desired configuration does not hot-mutate the native
+Session. An explicit `task role session new` request handles old runtime
+cleanup before selecting a fresh Session; it does not require manually settling
+Run status first. A useful Session may be reused, but it is never the only
+holder of Task context.
+
+## Permissions and Project context
+
+Provider permission strategy, Profile access intent and Project write scope are
+different contracts. Provider bypass does not grant writes to another Project.
+Managed workspace owner, exact Assignment and resource grants enforce Yui
+operations; broad native permissions are not an OS sandbox.
+
+Yui supplies its generic Role Skills and Context pointers. Project Skills remain
+ordinary Project files discovered natively by the Agent. Project Knowledge is
+maintained under `YUI_HOME`; copying repository material into a prompt does not
+make it authoritative Knowledge.
+
+## Native authentication
+
+Account configuration outlives a Session. Yui preserves `HOME` and the selected
+`CLAUDE_CONFIG_DIR`; new/resumed Sessions do not copy, clear, or fabricate native
+login, key-approval, or onboarding records.
+
+For Claude Code, standard API-key, base-URL, bearer/OAuth, model-alias and native
+provider-selection environment variables are forwarded only to Claude. Values
+remain in the Controller's replaceable runtime environment and the child process,
+not in Task/Role records. Unsetting a source and refreshing the Controller
+environment removes it for subsequent launches. Other custom credential variables
+still use explicit Agent environment bindings or native user settings; Yui does
+not inherit the whole shell environment or infer cloud credentials.
+
+Claude itself loads native settings and chooses between API keys, existing
+helpers, login credentials, profiles and cloud authentication according to its
+effective configuration. Yui does not inject `apiKeyHelper`, copy credential
+files, or override the native authentication priority. Explicit `--settings`
+paths and settings-source selections are passed through unchanged.
+
+Fresh native configuration can still require Claude's initialization, key,
+workspace and security confirmations, including access to initialization
+services. Isolating `YUI_HOME` or replacing a Session does not require a fresh
+native account directory. Managed Task execution uses Claude's non-interactive
+stream-json path with the same native configuration ownership.
+
+## Commands
+
+```sh
+yui config agent capabilities <agent-id>
+yui config role show <global-role>
+yui config profile show <profile>
+yui task role add <task> <role> --profile <profile>
+yui task role show <task> <role>
+yui task role update <task> <role> --environment <preparation-id>
+yui task role update <task> <role> --managed-environment
+yui task role session inspect <task> <role>
+yui task role session new <task> <role> --reason "<why a fresh Session is useful>"
+```
+
+On Role creation, explicit Agent settings require `--agent`. On update, omitted
+`--agent` targets the active binding; a named binding is updated without being
+activated. `task role bind` changes selection. A live Session requires the
+command's explicit confirmation before desired settings are changed.
+
+For native configuration and implementation limits, see [Provider runtime](provider-runtime.md).

package/docs/sqlite-control-plane-design.md

@@ -0,0 +1,76 @@
+# SQLite control-plane storage
+
+Yui has one authoritative product Store: `YUI_HOME/yui.db` in WAL mode. The
+highest contiguous, checksummed row in `schema_migrations` is the one Home
+storage version accepted by the running release.
+
+## Authority
+
+- `yui.db` owns Tasks, WorkItems, AgentRuns, Messages, Decisions, results, Project
+  Knowledge references, managed workspace records, runtime bindings, mailboxes,
+  durable events, and configuration.
+- Provider Sessions, transcripts, processes, caches, telemetry, and runtime
+  observations support execution and diagnosis; they do not replace durable
+  Task facts.
+- Configuration and diagnostics outside the database do not define another
+  storage version or permit rebuilding Task truth heuristically.
+
+## Admission
+
+Ordinary commands open a Home only when all of these are true:
+
+1. `yui.db` exists and its migration ledger is a valid immutable prefix.
+2. The ledger head exactly matches the running CLI's current storage version.
+3. Current record validation and reference integrity succeed.
+
+An older Home inside the CLI's supported range fails ordinary admission but is
+classified as upgradeable. `yui doctor` and `yui upgrade --dry-run` report the
+ordered path without changing the Home. Explicit `yui upgrade` is the only
+standalone mutation boundary: it quiesces the Controller, backs up `yui.db`,
+applies all missing migrations transactionally, and validates the current
+model. A newer, below-minimum, incomplete, or malformed Home fails closed.
+There is no runtime normalization, repair worker, file-Store fallback, dual
+read/write path, or second migration authority.
+
+## Write and concurrency contract
+
+- Each mutation is one SQLite transaction.
+- WAL plus `synchronous=FULL` provides the durable commit boundary.
+- `home_meta.revision` is the Home-wide CAS/revision used by callers that need
+  a frozen read/modify/write boundary.
+- Typed columns support indexed identity and status queries; the full validated
+  record payload remains the durable domain representation.
+- Mailbox claim, exact AgentRun terminalization, active-pointer removal, result
+  persistence, and downstream wake creation are transactionally coupled where
+  they form one product fact.
+- Idempotency keys and unique constraints protect repeatable external-effect
+  acknowledgements; they do not form a second workflow state machine.
+
+## AgentRun and Session boundary
+
+An AgentRun is an explicitly requested execution. It records associated visible
+inputs and the original result, not hidden reasoning or the full tool trace.
+A Provider Session can contain multiple Runs, ordinary native chat and
+notifications. Native chat and notifications do not automatically create Runs.
+Only an exactly correlated native terminal settles the Run; the Leader remains
+the authority for WorkItem and Task acceptance.
+
+## Update behavior
+
+`yui update` stages an exact package and asks that staged binary to classify the
+Home as current, migration-ready, or blocked. It then stops the exact
+Controller, activates the same package, runs the staged release's complete
+migration chain when required, verifies the installed binary and current Home,
+and starts the replacement Controller.
+
+Every persistent schema or payload change appends one immutable, contiguous
+storage migration. The CLI publishes both `storageVersion` and
+`minimumStorageVersion`; every valid Home in that inclusive range can upgrade
+directly to the current version without installing intermediate releases.
+The current source declares storage version **18**, with minimum supported
+migration version **1**, in `src/storage/storageVersions.ts`. Homes below that
+floor are not migration inputs and remain untouched.
+The target binary's `upgrade --update-preflight` and `--update-apply` result
+shapes and parent-owned handover-lock proof remain backward compatible with
+every updater released from storage version 1 onward, so an old source CLI can
+still drive a much newer target's complete migration chain.

package/docs/task-dag-semantics.md

@@ -0,0 +1,57 @@
+# Task 依赖与 WorkItem 语义
+
+## 需求与执行分离
+
+Task 是一个有界结果，WorkItem 是其中可独立验收的需求。Task type 不决定
+执行拓扑；Leader 可以直接工作，也可以创建独立负责人交付的 WorkItem。
+实现步骤、一次测试、审查发现或小修补不因此成为新 WorkItem。
+
+WorkItem 持久状态仅为 `open / accepted / retired`：
+
+- `open`：需求仍在处理；可能尚未执行、正在执行、等待验收或需要重试。
+- `accepted`：Leader 已显式接受当前交付。
+- `retired`：需求已显式退役，保留记录和原因。
+
+执行状态归 AgentRun，Candidate 记录当前待接受的结果。提交、拒绝或执行失败
+不把 WorkItem 变成另一套运行状态。接受撤回是显式动作。
+
+## 唯一依赖权威
+
+`WorkItem.dependsOn` 是同一 Task 内的直接依赖列表。前置项 A → 下游 B
+表示 B 的 `dependsOn` 包含 A。保存时检查同 Task 引用、存在性和无环约束。
+它不表达 Provider 并发、Session 占用或文件锁。
+
+派发时，每个直接依赖必须存在且为 `accepted`。Open、retired 或 missing
+均不能满足依赖，错误返回具体 ID 和当前状态。Run 成功、Candidate 存在、
+Review 完成或 Git 已集成都不能代替 WorkItem 接受。
+
+退役的 replacement 字段只解释替代关系，不重定向或重写依赖。
+Leader 必须显式修订需求或依赖；Controller 不沿替换链自动释放下游，
+不级联取消、不自动跳过，也不把依赖列表变成调度计划。
+
+## 修改与恢复
+
+Open WorkItem 的合法定义编辑保存前后值，保留身份和执行证据。已经启动的
+Run 仍使用冻结 Assignment；修改当前需求不追溯改写其 Context 或权限。
+已接受和退役的定义不能借普通编辑覆盖。负责人与资源范围变更受各自边界检查。
+
+执行失败时，Leader 检查原始结果、Session、依赖与工作区，决定续作、重试、
+退役或修改计划。退役后迟到消息保留来源和未投递原因，不自动重开。
+InputRequest 表示待决问题；回答不自动接受 WorkItem 或改写依赖。
+
+## 接受、集成与 Task 完成
+
+Direct 和 replicated 共享一个 Leader 接受边界。Replicated Producer 不形成
+Candidate；只有显式综合的 main Run 结果进入候选路径。Leader 直接管理的
+交付也必须满足适用的 Candidate、ChangeSet 和 Integration 边界。
+
+隔离代码结果按 Project 捕获固定 ChangeSet，检查后 CAS 集成；未捕获、未集成
+或失效的最新结果不能满足交付。Review 依适用规则和 Task 合同检查。
+Leader 自己交付的 Task main 需要干净、已提交的精确快照。
+
+Task lifecycle 是 `draft / active / completed / cancelled / archived`。
+Draft 先规划再显式采用工作区；completed/cancelled 不接收隐式新执行，
+reopen 不重放旧请求；archived 不可重开。Archive 还要求资源静止、干净可移除，
+不因依赖图或完成状态自动删除工作区。
+
+CLI/Web 从这些事实派生展示和建议，不维护第二套可写 DAG、验收状态或计划。

package/docs/task-delivery.md

@@ -0,0 +1,103 @@
+# Task delivery and resource lifecycle
+
+## Lifecycle and planning
+
+Task lifecycle is `draft / active / completed / cancelled / archived`. A Draft
+stores intent, Project bindings, planning discussion and mutable requirements.
+It does not adopt a writable delivery workspace at creation.
+
+Activation validates current Roles, dependencies, Project scope and resources,
+prepares physical workspaces, and adopts status/ownership atomically. Failed
+preparation leaves the Task Draft with a failed request and a diagnosis delivered
+to the Leader. Deferred activation retains the exact intent and waits for native
+quiescence, whether requested in a planning Run or subsequent discussion.
+
+Task type describes the requested outcome, not the mandatory executor.
+Leader owns bounded work directly or assigns substantial independent WorkItems.
+Direct execution has no Group. Replication is explicitly requested for independent
+attempts at the same frozen Assignment, followed by Leader-selected synthesis.
+
+## Managed workspaces
+
+Stable Project checkouts are read-only references. Task main is a logical
+multi-Project root with per-Project Git worktrees. For one Project, the Agent's
+normal cwd is its managed Git root; for multiple Projects, the root and native
+additional-directory mechanism expose the explicit Project set.
+
+An isolated WorkItem has independent worktrees for writable Projects and
+Task-main context for the others. Write scope is explicit and can only be
+expanded by the authorized owner. Review owns a separate frozen workspace and
+cannot become a Develop or Integration source.
+Acceptance or retirement does not release a WorkItem's durable workspace.
+Task-main preparation preserves a Role's retained WorkItem/Review cwd until
+explicit cleanup or reassignment. Decision-support reads observe current Git
+heads without preparing workspaces or migrating Sessions.
+
+Before launch, actual Git lineage must descend from the recorded base. A reset
+outside that lineage is physical drift, not a reason to guess or repair ownership.
+An explicitly adopted environment can select a different native cwd while the
+managed workspace remains the Git/control ownership record.
+
+## Candidate, Review and Integration
+
+Provider terminal saves the exact original Run result. It does not accept the
+WorkItem. The Leader evaluates the result and captures immutable per-Project
+ChangeSets for isolated code. The governing Candidate supplies provenance for
+Review and Integration; Producers do not independently enter either path.
+
+Integration applies the fixed ChangeSet in a candidate worktree, runs configured
+checks, then advances the target only if its head still matches. Conflict,
+failed checks, target movement or rejection retain evidence and never advance
+the target. The Agent chooses retry or manual resolution within the retained
+workspace.
+
+When checks are a DurableJob, the Integration retains that exact jobId while
+running. Once the Job settles, `task integration continue <task>/<integration>`
+consumes its result and performs the guarded finalization. The direct operation
+does not depend on entries in the separate integration queue.
+
+Review follows the applicable Candidate rule or Task-final contract and frozen
+heads. The exact main Reviewer Run holds the report; successful execution is
+not a semantic pass. Acceptance belongs to the Leader.
+An explicit user requirement to delegate or obtain independent Review remains
+part of acceptance even if the default review policy is disabled. `next-action`
+reports stored facts and alternatives; it cannot weaken the Task Contract or
+infer that unrecorded WorkItems mean direct execution was requested.
+
+## Completion and remote delivery
+
+Completion checks the current WorkItems, latest captured/integrated results,
+applicable Review contract and exact clean committed Task-main snapshot.
+It also refuses completion while a new user/Operator message is still awaiting
+Leader delivery. The current native turn must end so the pending notification
+can arrive; the Leader then reads the original message and reassesses completion.
+This derives from existing Messages and mailbox delivery, not a second
+acknowledgement or workflow state.
+Terminal workspace cleanup can remain an advisory at completion, but not at
+archive. Artifacts selected as results must be fixed, present and Task-local.
+
+Publication records a remote PR/MR reference. Reported merge, independently
+verified merge and exact Task-head coverage are separate facts. Task completion
+does not prove any of them. Remote delivery is read from exact publication/head
+evidence, not inferred from a title or branch name.
+
+Cancelled intent does not prove the runtime stopped. User/Operator may reopen
+cancelled Tasks; Leader may reopen completed Tasks. Reopening requires fresh
+explicit input/work selection and never replays previous delivery requests.
+
+## Archive
+
+Archive is a separate authorized action after active work is settled and
+resources are clean and removable. Choose integrated delivery or deliberate
+abandonment explicitly. Integrated archive requires exact merged heads and
+verified publication evidence. An explicitly authorized verification override
+cannot bypass missing or stale heads or an unmerged result.
+
+Managed WorkItem resources must be integrated or deliberately abandoned before
+cleanup. Review, Lane and Integration resources must be settled. Dirty worktrees
+remain for the Agent to resolve; no implicit reset or force deletion occurs.
+Task main branches and durable Task records retain recovery information.
+Archived Tasks cannot reopen.
+
+Use each command's `--help` to inspect its exact authority and options before
+cleanup; reading a lifecycle document does not authorize an external write.