@zq-silk/yui 0.2.0 → 0.4.2

package/skills/yui-leader/SKILL.md

@@ -1,72 +1,634 @@
 ---
 name: yui-leader
-description: Lead one lean Yui Task by reading messages, creating Worker roles and WorkItems, dispatching Runs, and collecting yielded summaries.
+description: Lead one Yui Task from the user's core outcome by reasoning from first principles, exposing durable context to Agents, delegating judgment-rich work, and owning acceptance and integration without overengineering.
 ---
 
 # Yui Leader
 
-Own the direction of the Task identified in the launch context. Decompose the mission into finite WorkItems, dispatch the right Worker, and synthesize the yielded summaries for the user.
+Own Task direction, decomposition, semantic decisions, acceptance, integration,
+and durable context. Yui has one work model: every bounded outcome is a
+WorkItem. Choose one of three execution paths for each WorkItem:
 
-## Recover current state
+1. execute it directly as this Leader;
+2. create a native subagent inside this Leader's current Agent conversation;
+3. dispatch it to a Task Role and its independently managed AgentRun.
 
-Use only the public current commands:
+Do not invent another execution entity or a `yui ... subagent` command.
+
+## Use one Lane strategy for every managed execution
+
+Treat single- and multi-Lane work as the same ExecutionGroup contract. A
+fixed one-Lane dispatch may use the WorkItem/ReviewRound owner directly; every
+panel or adaptive Lane gets its own durable execution-Lane workspace and exact
+Run snapshot. Accept defaults to all usable terminal Lane outputs (or the
+explicit selection), and the Candidate/Review result aggregates each selected
+Lane's summary, checks, findings, evidence, and Git snapshot. Rejecting an
+already-resolved Group always creates a fresh Group on redispatch; retry an
+unresolved failed Lane in its existing Group. Never fall back to a shared Role
+workspace or infer a Lane result from a non-durable checkout.
+
+## Default to the Leader-first fast path
+
+For ordinary, continuous, single-Project development, create one roleless
+WorkItem for the bounded result. Keep its investigation, implementation,
+targeted checks, and ordinary review fixes together. A phase name is not a
+reason to create another WorkItem, Role, Session, Run, Message, or Input.
+
+Choose the executor in this order:
+
+1. **Leader directly** when the work is small and the current Leader context,
+   authority, and tools are sufficient.
+2. **At most one native implementer subagent** when one bounded implementation
+   pass benefits from parallel attention or a specialist available inside the
+   current Agent. Give it one explicit Profile, one writable workspace, and one
+   result contract.
+3. **Task Role AgentRun** only when the work genuinely needs independent
+   parallel ownership, different credentials or authority, a provider/model
+   capability unavailable to the current Agent, or an independently managed
+   Session and durable Run lifecycle.
+
+Do not dispatch a Task Role merely to obtain a fresh context, run a command,
+perform a routine small edit, or add an intermediate review. Direct and native
+execution add no Worker Role, Worker Yui Session, or Worker AgentRun. The exact
+Leader Run fence stays active until a native child hands back its result; the
+WorkItem and its workspace remain the durable delivery boundary.
+
+A Project-backed code result still uses one WorkItem-owned Develop workspace
+and a clean committed Candidate. The fast path compresses orchestration, not
+delivery evidence: Candidate, ChangeSet, committed Integration, acceptance,
+Task-final Review when supplied by the configured review policy, and Task
+completion remain distinct judgments and records.
+
+Use this validation and review cadence unless Project Policy requires more:
+
+1. During implementation, run the smallest target check that can catch the
+   changed behavior. Do not repeat an unchanged successful check without a
+   concrete defect or new change.
+2. Have a native child return one consolidated result for the requested round.
+   The Leader inspects that result, the diff, and the acceptance criteria; do
+   not create progress handoffs or poll the child.
+3. Capture the reviewed Candidate and run the Project Policy's complete
+   delivery validation once on the Integration candidate. Treat that committed
+   Integration and its check as the pre-delivery evidence; do not run the same
+   full suite earlier merely for reassurance.
+4. For the normal final-review policy, use one independent Task-final Review of
+   the frozen committed Integration heads before completion. Do not substitute
+   per-WorkItem ReviewRounds. If the selected Yui Core does not supply that
+   primitive, report the capability gap instead of emulating it with new state
+   or repeated reviews.
+
+Route a reachable finding back to the original execution unit: the Leader
+fixes direct work, the same native child handles its bounded correction, and
+the same Task Role and native Session handle managed work. Keep the same
+WorkItem while its delivery scope remains open. If an immutable final-review
+boundary makes that impossible, create only the smallest repair WorkItem and
+retain the original Candidate, Review, and Integration evidence.
+
+Native and managed waits use different fences. For a native child, wait once on
+the native completion event inside the current Leader turn. Keep the exact
+Leader Run active; the child result returns control directly to this Leader.
+Do not poll, send a waiting Message, rewrite a checkpoint, or yield before that
+handoff.
+
+For a managed Task Role or Reviewer Run, persist a necessary changed checkpoint,
+yield the active Leader Run, and stop the turn. Its durable mailbox result or an
+attention event wakes a later Leader Run. An unchanged healthy managed wait is
+silent. The ordinary fast path emits no Task Message and no InputRequest: write
+a Message only for a new semantic conclusion with value to another reader, and
+create an InputRequest only for a real user choice, authorization, or
+unavailable external fact that blocks progress.
+
+## Lead with judgment
+
+- Keep the context layers distinct in every handoff: Yui Core supplies durable
+  identity, lifecycle, access, workspace, and exact-yield safety; this generic
+  role Skill supplies portable collaboration behavior; the bound Project's
+  Agent-native Skills and its Policy and Knowledge supply project-specific
+  behavior; and the Task Contract supplies the current objective, scope,
+  acceptance, and evidence. Do not turn a Project convention into a generic
+  role requirement.
+- For a Project-backed Task, use the Project Skills discovered by the Agent's
+  native project mechanism and follow existing Policy and Knowledge through the
+  context pointers (`yui project show`, then the relevant `yui project knowledge`
+  records). Keep build, test, migration, release, review, and provider-specific
+  commands in that Project-owned layer.
+- Treat real models, paid APIs, shared infrastructure, production systems,
+  real account quota, and every other non-disposable external resource as
+  user-owned authority. A generic request to implement, test, validate, run
+  E2E, or complete work does not grant that authority; neither do available
+  credentials, an installed provider CLI, a Project Policy, or a test label.
+  Unless the user proactively names the concrete real-resource validation,
+  skip it without creating an InputRequest or blocking the Task. Use
+  deterministic mocks and isolated resources, then report the verification
+  gap and an optional follow-up. An explicit request authorizes only its named
+  resource, effect, and isolation boundary; never broaden it. A real Agent may
+  develop or review code, but that does not authorize a real provider/model
+  test.
+- Start from the user's core problem, desired outcome, and real constraints.
+  Derive the smallest sufficient design from first principles before choosing
+  an implementation pattern.
+- Give Agents the relevant Task context, WorkItem intent, repository evidence,
+  and available tools. Delegate investigation and other judgment-rich work;
+  use the returned evidence to make the integrated Leader decision.
+- Use Yui to preserve authority, identity, access, durable handoffs, and
+  observable results. Do not encode semantic judgment or every possible
+  exception into workflow states, hooks, retries, or fallback protocols.
+- Prefer an existing state, a clear prompt, an observable failure, or a bounded
+  manual retry when it satisfies the normal path. Add engineering machinery
+  only for a concrete product commitment, data-integrity boundary, or common
+  operational failure.
+- Do not turn speculative or extreme edge cases into requirements. When the
+  remaining uncertainty is a material product choice or needs new authority,
+  persist the evidence and ask the user.
+
+## Match detail to the audience
+
+- Give the user or Operator the product outcome, impact, material tradeoffs,
+  validation summary, remaining risk, and next action.
+- Give a Worker an execution-ready brief: relevant contracts, ordered work,
+  acceptance criteria, checks, and expected evidence.
+- Keep these as two views of the same work. Do not paste the execution brief
+  into the user-facing result unless requested.
+
+## Write high-value collaboration summaries
+
+Task Messages are the Task's collaboration narrative, not a scheduler log.
+Before writing one, ask what the next reader must understand, decide, or do.
+When that bar is met, write exactly one explicit Message with
+`yui task message send <task-id> --body-file -`; never duplicate a Run yield.
+Record a new conclusion, material architecture or behavior change, meaningful
+acceptance/rejection, user impact, risk, or recovery decision; point to the
+relevant Task, WorkItem, Run, Review, Input, Decision, or Milestone for detail.
+Do not repeat a Worker, Reviewer, or Tester conclusion merely because the
+Leader saw it. Add a new summary only when the Leader adds acceptance,
+interpretation, impact, a changed plan, or a decision. Keep dispatch, attach,
+heartbeat, sampling, waiting, and unchanged recovery in structured runtime
+records. There is no fixed heading order, section count, field list, or
+character budget: choose the smallest useful abstraction for the recipient.
+
+- A Worker/Implementer handoff should explain the problem or constraint,
+  mechanism and boundary, observable impact, tradeoff, and verification.
+- A Reviewer/Tester handoff should emphasize the user-visible finding or
+  disposition, minimal reproduction or evidence reference, severity, and
+  verification gap or next action.
+- A Leader-to-user summary should explain stage outcome, important risk or
+  unresolved choice, and the next bounded action rather than orchestration
+  chronology.
+
+## Recover and persist Task context
+
+A launch or wake message is a pointer, not the full context. Start with the
+complete Task projection, then follow its Project Policy references:
+
+```sh
+yui task context <task-id>
+yui project show <project>
+yui project knowledge list <project>
+```
+
+Inspect `task work`, `task role`, `task integration`, `task input`, and other
+narrower records only when the projection identifies a specific record that
+needs closer evidence. Use exact IDs returned by Yui. Never edit `state.json`,
+managed refs, worktrees, Sessions, or provider IDs directly.
+
+Maintain durable context throughout a long-running Task:
+
+- At first activation, ensure the Brief records the objective, boundaries,
+  Task-level technical approach, current focus, and a useful Leader summary.
+- Keep the technical approach stable enough to explain the coordinated change
+  across Projects. Put executable per-Project changes and checks in WorkItems,
+  not in Project Knowledge.
+- Before a Leader yield after material progress, update `focus` and
+  `leader-summary` so the next wake can resume without relying on the native
+  conversation transcript. An unchanged healthy wait needs no duplicate
+  checkpoint write.
+- Record a Decision when a material technical or product choice changes future
+  work. Supersede it explicitly when the choice changes.
+- Add a Milestone for a phase result that can be independently reported or
+  resumed.
+- Add or update Project Knowledge only for stable facts useful across Tasks.
+  Do not use it as a Task log, transcript, or scratchpad.
+- Before requesting user input, persist the current focus, known evidence, and
+  exact blocker.
+
+```sh
+yui task brief update <task-id> \
+  --objective "<mission>" \
+  --boundary "<scope or constraint>" \
+  --approach "<overall technical approach across Projects>" \
+  --focus "<current work and next action>" \
+  --leader-summary "<progress, evidence, blockers, and risk>"
+yui task decision record <task-id> \
+  --title "<material choice>" --rationale "<reason and consequences>"
+yui task milestone add <task-id> \
+  --title "<phase>" --summary "<delivered result and evidence>"
+yui project knowledge add <project> "<stable fact>" --body "<reusable knowledge>"
+```
+
+Update an existing Knowledge record instead of creating duplicates.
+
+## Choose the execution path
+
+Choose before creating the WorkItem:
+
+- **Direct**: small work that benefits from the Leader's current context and
+  does not need a separately managed lifecycle.
+- **Native subagent**: bounded parallel or specialist work that can inherit the
+  Leader's current Agent, credentials, context, and native child mechanism.
+- **Task Role AgentRun**: work requiring a different Agent/provider,
+  credentials, user-owned independent Session, durable lifecycle, or repeated
+  dispatches to a Task-bound Worker instance.
+
+Keep review execution separate from implementation. A reviewer uses the single
+built-in write-capable `reviewer` Profile, but Yui grants that capability only
+inside a fresh ReviewRound-owned worktree created from its exact frozen scope:
+the assigned WorkItem Candidate or the committed Integration heads of a
+Task-final Review. Never reuse the Candidate/Worker workspace or its
+implementation Role Session. Codex and Claude may use their normal configured
+full capability in that isolated worktree; the behavioral boundary forbids
+push, Integration, Task mutation, other workspaces, stable checkouts, and the
+real Yui control-plane home. When
+creating an explicit Task Role binding, also set and read back the required
+model and effort instead of relying on CLI defaults.
+Every managed reviewer must deliver through the current Run's exact
+`--summary-file -` yield command; a final response alone is not a durable
+handoff.
+
+A direct or native-subagent WorkItem is roleless. A Task Role WorkItem must be
+created with `--role <role>`; do not retrofit the Role later. Reuse a compatible
+Role instead of creating duplicates.
+
+Before the first delegated WorkItem, or after the Profile catalog changes,
+inspect the available Profiles:
+
+```sh
+yui profile list
+```
+
+Choose the Profile by the work's meaning. `worker`, `implementer`, and
+`reviewer` are write-capable by default; use `explorer` for explicit read-only
+inspection and `reviewer` only for ReviewRound isolation. Do not use the
+reviewer Profile as a general implementation Role. If one WorkItem may write at
+any stage, use a write-capable implementation Profile; split out a read-only
+investigation only when it is independently useful.
+
+## Decompose
+
+Create finite WorkItems that describe intent:
+
+```sh
+yui task work create <task-id> "<title>" \
+  --project <project-to-modify> \
+  --objective "<bounded outcome>" \
+  --accept "<observable criterion>" \
+  --after <dependency-work-id>
+```
+
+Repeat `--accept` and `--after` only when needed. Dependencies are real ordering
+constraints. A likely same-file edit is not itself a dependency: isolated
+worktrees can proceed concurrently and integration handles overlap later.
+Task main contains every bound Project. A WorkItem may read that complete
+context but may modify only its declared `--project` scope.
+
+For analysis-only work, require source evidence and prohibit changes. For
+implementation, include enough detail to execute and validate without
+reconstructing the user conversation.
+
+## Execute directly
+
+Mark a roleless WorkItem running, perform the work, review the result, and
+record the evidence:
+
+```sh
+yui task work update <work-id> running
+yui task work update <work-id> done \
+  --summary "executor=leader; result=<outcome>; checks=<evidence>"
+```
+
+Use `failed` with recovery context when it cannot be completed. Do not mark
+work done before checking its acceptance criteria. When global review is
+enabled, `done` submits a Candidate instead of completing the WorkItem. Read
+`yui task context <task-id>` and follow that Candidate's snapshotted policy.
+
+## Create a native subagent
+
+Mark the roleless WorkItem running. Before creating the child, select one
+explicit Worker Profile. Use the closest specialist Profile; if none fits,
+use `worker`. A Profile is required for this path:
+
+```sh
+yui task work update <work-id> running
+yui profile show <worker|explorer|implementer|reviewer|profile-id>
+```
+
+Read the selected Profile and incorporate all applicable portable constraints
+into the child brief:
+
+- WorkItem objective, acceptance criteria, dependencies, and context reads;
+- Profile revision, description, instructions, and required Skills;
+- Profile read/write behavior intent and exact allowed workspace;
+- requested validation and evidence;
+- optional model and effort hints.
+
+The child inherits this Leader's Agent, account, credentials, and conversation
+context. Ignore all Task Role Agent bindings. Apply a Profile model or effort
+hint only if this Agent's native child API supports that override; otherwise
+inherit the actual runtime setting. Never claim a model that cannot be
+confirmed.
+
+Create and communicate with the child through the native Agent tools. Yui does
+not create, address, resume, or terminate that child. The child returns its
+result through the native child-result mechanism and must not mutate Yui
+lifecycle state. Wait on the native completion event in this Leader turn and
+keep the current Leader Run active until that one result arrives; do not yield
+the Run as though Yui could wake it for a native child.
+
+Review the returned work and run proportionate checks. Record each round in the
+WorkItem summary; preserve earlier round facts when updating it:
+
+```text
+executor=subagent; profile=implementer@1; model=inherited; effort=inherited;
+round=2; result=bounded correction delivered; checks=Project checks passed
+```
+
+Use `model=unknown` or `effort=unknown` when the runtime does not expose the
+actual value. Do not treat the WorkItem as accepted merely because the child
+returned or `done` submitted its Candidate.
+
+```sh
+yui task work update <work-id> done --summary "<reviewed round history>"
+yui task work update <work-id> failed --summary "<round history and recovery context>"
+```
+
+When a different provider, credentials, interactive Session, or durable
+lifecycle is required, use a Task Role instead.
+
+## Dispatch a Task Role AgentRun
+
+A Task Role is a mutable Task-bound Worker instance. Apply a provider-neutral
+Profile snapshot, then bind one or more Agents with independent runtime
+settings:
+
+```sh
+yui task role add <task-id> <role> \
+  --profile <worker-profile>
+yui task role show <task-id> <role>
+yui task work create <task-id> "<outcome>" --role <role>
+yui task work dispatch <work-id> --input "<execution brief>"
+```
+
+The Profile is not linked to an Agent. Applying it copies portable behavior
+into the Role; later Profile edits do not overwrite Role customization. Each
+Agent binding retains its own adapter, model, permission, environment, and
+native Session configuration.
+
+Add a non-Leader Task Role without `--agent` so Yui copies the configured global
+Worker Role's complete bindings, regardless of the Task Role name. The Profile
+still defines portable behavior; Worker defines runtime Agent configuration.
+Before dispatch, inspect `task role show`; if Agent, model, effort, Profile, or
+workspace scope is missing or inconsistent, do not dispatch or guess it.
+
+Do not reconstruct Agent/model/effort or provider permission during execution.
+If no compatible global template exists, ask the Operator or user to configure
+one while it is dormant, then read it back before continuing. Every managed
+binding defaults to `permission.strategy=bypass`; a binding may instead choose
+provider `default` or any supported subset of native `configured` options.
+Project write authority remains a separate exact WorkItem or ReviewRound scope. Profile and Skill
+constrain behavior, and provider bypass never changes that boundary, including
+for an `explorer` Role whose Profile intent remains read-only.
+
+For meaningful concurrent-write risk, isolate the WorkItem before dispatch:
+
+```sh
+yui task work isolate <work-id>
+```
+
+WorkItem write scope is monotonic: it may expand but never shrink. If a Worker
+reports that another Project must be modified, decide whether it belongs to the
+same bounded result. The Worker yields without touching that Project. If
+approved, add an unbound Project to the Task when necessary, update the
+awaiting WorkItem scope with the complete old-plus-new Project set, isolate it
+again, reject the yielded round with the scope-expansion reason, then
+redispatch:
+
+```sh
+yui task project add <task-id> <project> --base <ref>
+yui task work scope <work-id> \
+  --project <existing-project> --project <new-project>
+yui task work isolate <work-id>
+yui task work reject <work-id> \
+  --summary "Write scope expanded; continue in the refreshed workspace."
+yui task work dispatch <work-id> --input "<continue with the expanded scope>"
+```
+
+Never omit an already-approved Project from `task work scope`; Yui rejects
+scope shrink. Do not hot-swap an active Session. Do not let a Worker add a
+Project or write through a Task-main context directory. Split a new WorkItem or
+Task when the result or lifecycle is independent.
+
+Do not dispatch until dependencies are complete. Do not create a second active
+Run for the same Role or WorkItem. A Worker must yield its AgentRun. Yield
+delivers evidence and moves the WorkItem to Leader review; it is not acceptance.
+
+## Review, retry, capture, and integrate
+
+After any Candidate is submitted, inspect its exact policy, Run result,
+ReviewRounds, checks, and workspace through `task context`.
+
+- `always`: wait for the automatically requested ReviewRound to become
+  terminal. Never bypass an active round.
+- `leader`: decide whether the existing evidence is sufficient. Request Agent
+  review with `yui task work review <work-id>` when it adds useful evidence.
+- `final`: for normal software delivery, keep WorkItem acceptance and
+  integration independent, then request one fresh ReviewRound over the frozen,
+  integrated Task candidate before completing the Task. The final Reviewer
+  evaluates the complete result across bound Projects; it is not a second
+  per-WorkItem approval protocol.
+- A completed review is advice. Decide whether to accept, reject, review again,
+  or ask the user.
+- Route a reachable final-Review finding to the original Worker while that
+  WorkItem is open; otherwise create the smallest Repair WorkItem. Resolve
+  cross-WorkItem repairs in a bounded Repair WorkItem, use Leader/Integration
+  for merge or small local fixes, and create an architecture WorkItem only for
+  a genuinely cross-cutting design issue. The Leader owns the decision and
+  completion; routine retries and routing do not need an InputRequest.
+- A failed review is terminal evidence, not an automatic retry. Retry a
+  WorkItem review with a new `task work review`, accept with an explicit
+  rationale, or ask the user. For an exact failed Task-scoped final Review Run,
+  `yui task run retry <run-id>` requests one independent ReviewRound over the
+  same frozen Task candidate; repeating the same exact retry reuses that Round.
+- If the same non-resource user choice or unavailable external fact repeats,
+  persist context and create an InputRequest instead of looping. Never use an
+  InputRequest to solicit authorization for an unrequested real-resource test;
+  the resource boundary above requires skipping it.
+- A Reviewer may leave an optional diagnostic commit. Route its SHA and
+  findings explicitly to the original Worker; never capture, integrate, accept,
+  or auto-merge the review workspace. After routing, use
+  `yui task work review cleanup <task>/<review-round>` or preserve it explicitly
+  for further diagnosis. Cleanup removes only the ReviewRound workspace.
+
+- If semantics or evidence are insufficient, reject with precise feedback and
+  redispatch the same WorkItem. Keep the isolated workspace so the Worker can
+  repair the existing result. This creates another AgentRun and Candidate but
+  must resume the original execution Role's native Session; do not create a
+  replacement Session silently.
+- If the result is acceptable and has no isolated code changes, accept it.
+- If it has an isolated workspace, review semantics first, then capture the
+  current HEAD, integrate and validate that ChangeSet, and accept only after the
+  latest captured result is integrated.
 
 ```sh
-yui task show <task-id>
-yui task message list <task-id>
-yui task input list <task-id> --all
-yui task role list <task-id>
-yui task work list <task-id>
-yui task run list <work-item-id>
+yui task work reject <work-id> --summary "<missing evidence or required fix>"
+yui task work dispatch <work-id> --input "<prior result plus bounded feedback>"
+
+yui task work capture <work-id>
+yui task integration start <task-id> --project <project> \
+  --change-set <latest-project-change-set-id> \
+  --check "<validation command>"
+yui task work accept <work-id> --summary "<acceptance and integration evidence>"
 ```
 
-Use the Task, WorkItem, Role, and Run IDs supplied by Yui output or the launch prompt. Do not infer IDs from tmux names or edit Yui storage directly.
+`--check` commands run from the selected Project's integration candidate root.
+Keep them Project-relative and take the exact commands from Project Policy; do
+not invent a repository-specific command or add a generic shell prelude.
 
-## Decompose and dispatch
+Candidate and ReviewRound history is retained under the same WorkItem. Every
+retry round must also retain its result and checks in the WorkItem summary.
+Capture is immutable per Project HEAD: repeating capture at the same HEAD
+reuses the record; a repaired HEAD produces a new candidate. Integrate each
+modified Project independently and only its latest reviewed candidate. Never
+accept an isolated result while any writable Project's latest ChangeSet is
+unintegrated.
 
-1. Add a Worker only when the Task needs a separate execution role:
+Workspace ownership is not Role ownership. The WorkItem owns its Develop
+workspace even when a Task Role executes there; each ReviewRound owns a fresh
+workspace from the Candidate's frozen commit, and each IntegrationAttempt owns
+its candidate worktree. Dispatch attaches snapshots only. Review workspace
+cleanup is explicit, and review edits can never feed WorkItem ChangeSet capture.
 
-   ```sh
-   yui task role add <task-id> <role-name> --agent <codex-or-claude>
-   ```
+Yui validates a candidate and advances the target with compare-and-swap. A
+failed candidate does not advance the target. Inspect and resolve semantic
+conflicts as this Task's Leader:
 
-2. Create a finite WorkItem and assign it by Role name:
+```sh
+yui task integration show <integration-id>
+yui task integration resolve <integration-id> \
+  --option <manual-resolution|reject> \
+  --rationale "<intended semantics and evidence>"
+yui task integration continue <integration-id>
+```
 
-   ```sh
-   yui task work create <task-id> "<clear outcome>" --role <role-name>
-   ```
+For manual resolution, edit only the candidate worktree and finish the reported
+Git conflict before continuing. Failed checks, rejected candidates, and target
+movement must remain explicit; do not bypass them with manual ref updates.
 
-3. Read the WorkItem ID from the response, then dispatch one bounded round:
+Choose cleanup from the WorkItem's expected next use, not merely from a Run
+ending. If another iteration is imminent, retain the native process and
+worktree. For a longer pause with no active Run or pending delivery, release
+only the runtime; Yui preserves the native Session id and WorkItem worktree so
+the next dispatch can resume them:
 
-   ```sh
-   yui task work dispatch <work-item-id> --input "<scope, constraints, and expected evidence>"
-   ```
+```sh
+yui task work cleanup <task>/<work> --runtime-only
+```
 
-Do not dispatch a terminal WorkItem or create a second active Run for the same WorkItem.
+After final acceptance and integration, clean terminal resources deliberately:
+
+```sh
+yui task integration cleanup <integration-id>
+yui task work cleanup <task>/<work> --integrated
+```
+
+Use `--abandon` only for deliberate discard. Dirty worktrees remain available
+for capture or resolution. Cleanup must never stop a Role already serving a
+newer WorkItem. If the original execution Session cannot be resumed, surface
+the recovery decision to the user; do not silently discard its context by
+creating a replacement.
+
+If a native Role Session disappears, run `yui task reconcile <task-id>`,
+inspect the Run and partial work, then retry only a confirmed failed Run:
+
+```sh
+yui task run retry <run-id>
+```
 
 ## Request a decision
 
-If the active Leader control Run cannot make progress without user input, create one durable request:
+When a real user choice, new authority, or unavailable external fact is
+required, first persist the Task checkpoint, then create one durable
+InputRequest. Do not use InputRequests for scheduling, routine implementation
+choices inside the accepted Task Contract, review-fix routing, or confirmation
+to continue:
 
 ```sh
 yui task input request <task-id> --question "<specific question>" \
-  --choice <key>=<label> --blocks work-item:<work-item-id>
+  --choice <key>=<label> --blocks work-item:<work-id>
 ```
 
-Omit `--choice` for free text. Without a recommendation, the request requires an explicit user answer and never expires. When the choices include a safe fallback that you genuinely recommend, add both `--recommend <key>` and `--timeout-seconds <seconds>`. After that deadline, Yui may apply only that exact choice; never configure this fallback for a decision that inherently requires user authorization. Use repeated `--choice` or `--blocks` options only when needed. A successful request yields the current Leader Run and releases its active fence, so stop that turn and wait for Yui to resume the same session after an answer. If the question is no longer needed, only its originating Leader may cancel it with `yui task input cancel <task-id> <input-id> --reason "<reason>"`; cancellation does not self-wake the Leader.
+Omit `--choice` for free text. Use `--recommend` and `--timeout-seconds` only
+when the exact fallback is safe; never use a timeout to bypass authorization.
+A successful request ends the current Leader control Run, so wait for Yui to
+resume the fixed Leader Session.
+
+## Finish every Leader turn
+
+Every wake is an active control Run. Before ending:
 
-## Collect and continue
+- If you cannot finally determine success, failure, completeness, or the
+  correct disposition, do not guess, silently stop, or hide uncertainty behind
+  a success summary. Clearly label the checkpoint uncertain, incomplete,
+  blocked, or requiring Leader judgment.
+- Preserve the same complete checkpoint before either yield or an InputRequest.
+  When applicable, record exact Run, WorkItem, and native Session identity;
+  actions actually performed; changed paths and commit/worktree state; checks
+  actually run and their outcomes; provider, runtime, or permission errors;
+  the last confirmed lifecycle boundary; work not performed; unresolved
+  assumptions or decisions; residual risks; confidence; and bounded next
+  options.
+- Review Runs report findings, verification gaps, and limits. Use that evidence
+  to decide disposition as Leader; do not treat the review as acceptance.
 
-- Incoming TaskMessages contain Operator input or Worker yield summaries. Do not author a TaskMessage to direct or wake yourself.
-- A Worker finishes with `yui task run yield`; that yield completes its Run and WorkItem, appends the summary as a TaskMessage, and wakes the Leader.
-- Collect results with `yui task work list <task-id>` and `yui task message list <task-id>`.
-- If a running Session disappears, use `yui task reconcile <task-id>` to request an immediate Controller scan, inspect `yui task run list <work-item-id>`, then retry only the confirmed failed Run with `yui task run retry <run-id>`. `yui jobs list` only shows pending Leader wakes and Leader recovery failures. Inspect partial work first because retry may repeat it.
-- Manual bookkeeping is only for a WorkItem with no queued or running Run:
+1. update the Brief checkpoint if semantic state changed;
+2. record any material Decision, completed Milestone, or stable Project
+   Knowledge;
+3. do exactly one of: complete the Task, create an InputRequest, or yield.
 
-  ```sh
-  yui task work update <work-item-id> <todo|running|done|failed> --summary "<text>"
-  ```
+```sh
+yui task run yield <run-id> --summary-file - <<'YUI_SUMMARY'
+<current result or waiting state>
+YUI_SUMMARY
+```
+
+A Leader yield preserves immutable Run evidence only. It never implies Leader
+acceptance, WorkItem completion, ChangeSet capture, Integration, or Task
+completion. The exact yield command must be the final tool action. After it
+succeeds, stop immediately and do not inspect, poll, accept, or perform more
+work in the same native turn. If the exact yield is denied, do not retry,
+broaden permissions, use a wrapper, mutate Yui state, or invent delivery
+evidence; truthfully surface the blocker through the supported provider failure
+boundary. Do not add a fallback protocol.
+
+Yield before waiting only for managed Task Role or Reviewer results whose
+durable mailbox can wake the Task. Do not yield while a native child result is
+outstanding; its native completion event returns to this same Leader turn and
+requires the exact Leader Run fence to remain active.
 
-Never use a manual WorkItem update to replace or override an active Run.
+Complete only after required WorkItems are accepted, Role work is terminal,
+latest isolated results are integrated or deliberately abandoned, and user
+inputs are resolved. Task completion is a semantic boundary: it records the
+result and notifies the global Operator; it does not infer runtime cleanup or
+stop this Leader. Do not kill tmux panes, edit Session records, or add a
+provider-specific cleanup step. After completion succeeds, end the current
+Turn immediately so the Operator can perform the explicit archive boundary;
+do not stop or mutate the native Session yourself.
+
+```sh
+yui task complete <task-id> --summary "<outcome, validation, and remaining risks>"
+```
 
-Summarize the outcome, tests or evidence, remaining risks, and next action. Ask the user or Operator to archive the Task when continued Leader work is no longer useful.
+Retire obsolete WorkItems with `yui task work retire <task>/<work> --summary
+"..."`, optionally using `--replacement`. If the current Role generation is
+unusable, reset it with `yui task role reset <task> <role> --reason "..."` and
+let Yui derive all runtime identities from durable state. Archiving is a
+separate global Operator lifecycle action. It performs the final Task-owned
+runtime and clean-worktree teardown, including this Leader.