@zq-silk/yui 2.20.0 → 2.22.0

package/skills/yui-leader/references/assignment-execution.md

@@ -0,0 +1,140 @@
+# Assignment execution and input timing
+
+Read before creating/acting on an Assignment or sending its continuation/control.
+Ordinary direct implementation does not require this manual or the other
+[execution operations](execution.md).
+
+### Choose input timing without changing intent
+
+Submission intent (`record`, `discuss`, `develop`) and delivery timing are
+different facts. Input controls do not activate a Task, expand an Assignment,
+or elevate a planning Session. Keep the submission contract when using `send`;
+choose queue, steer or interrupt from the user's intent and current facts:
+
+```sh
+yui task message queue <task> "<continuation>" --request-id <id> --to <role> --work-item <work-id>
+yui task message steer <task> "<current-turn correction>" --request-id <id> --to leader --expected-target <turn>
+yui task role interrupt <task> <role> --expected-target <turn> [--then-message <task/message>] [--request-id <id>]
+```
+
+Queue waits for the next legal opportunity. Steer addresses only the exact
+current native Turn; Worker/Reviewer steer also needs its existing WorkItem or
+ReviewRound. Bare interrupt stores a control request, not a new Message.
+`interrupt-requested` is not a terminal or proof that background resources
+stopped. Then names an already-saved input and reserves its next opportunity
+only within the original Session/writer boundary.
+
+Read `task role session inspect` first. Unsupported and proven-unsubmitted
+steer may be composed with interrupt when the user's intent permits stopping;
+accepted, pending or unknown steer must not be resent through another action
+or request id. Never silently cancel, replace a Session or downgrade to queue.
+
+Global inputs use `role message queue|steer <role>` and `role interrupt <role>`
+with their own owner, not a fabricated Task/Run. See
+[Runtime](../../yui-runtime/SKILL.md) for scope and controlled-console boundaries.
+
+Managed dispatch freezes the Assignment for its assignee. For ordinary
+clarification, feedback or a continuation of that same work, send a Message:
+
+```sh
+yui task message send <task> "<clarification or continuation>" --to <role> --work-item <work-id>
+yui task message send <task> "<review clarification>" --to <role> --review-round <round-id>
+```
+
+Busy execution queues the Message. Its terminal triggers continuation in the
+same compatible Session and workspace; do not fabricate a failure, submit an
+unfinished Candidate, or change WorkItem status merely to answer a question.
+Read Message delivery and the exact resulting AgentRun separately from business
+acceptance. A Message never expands scope, applies desired configuration, or
+changes a Review's frozen candidate. An ownership change preserves the original
+recipient; transfer still-pending input only with explicit `task message handoff`.
+Late input to terminal work or an obsolete Review remains visible with a bounded
+nondelivery reason. Use the existing formal operation for new scope or Review.
+
+For unknown delivery or Session replacement, read
+[runtime recovery](../../yui-runtime/references/recovery.md). Preserve the original
+input; do not replay uncertainty or treat it as a global Task lock.
+
+### Leader-owned WorkItem
+
+Use this only when the result merits separate management/acceptance. Omit
+`--role` for direct execution: the Leader owns coordination and performs the
+work without a managed executor Assignment. `--role leader` instead selects the
+Leader Role as a **managed AgentRun executor**; it is not how to label direct
+ownership. Do not self-dispatch merely to gain execution authority.
+
+For a writable Project result, create and inspect its WorkItem-owned workspace
+before editing. The Leader can work there directly; isolation does not require a
+Worker. Task main, WorkItem Develop, and Review workspaces remain distinct owners.
+
+```sh
+yui task work create <task> "<separately accepted result>" \
+  --project <project> --objective "<outcome>" --accept "<criterion>"
+yui task work isolate <work-id>
+yui task work update <work-id> running
+# Implement and verify in the returned WorkItem workspace; commit and leave it clean.
+yui task work update <work-id> done --summary "<result and evidence>"
+```
+
+`done` freezes a direct Candidate, not an AgentRun result or acceptance.
+Inspect it, then integrate the exact isolated result before acceptance:
+
+```sh
+yui task integration start <task> --work-item <work-id> \
+  --project <project> --strategy <ff|cherry-pick|merge|manual>
+# Inspect the attempt and finish it through Integration's normal checks/continuation.
+yui task work accept <work-id> --summary "<decision and evidence>"
+```
+
+Read [Integration](integration.md) for checks, continuation, and recovery.
+Keep the same unit through ordinary fixes.
+A read-only or Gitless result with no writable Projects needs no Git isolation;
+submit its actual evidence and accept it explicitly. Existing exact Task-final
+metadata-only Candidates retain their contract; do not establish a special Review
+contract merely to avoid the ordinary writable WorkItem isolation boundary.
+
+For a native child, pass a bounded brief and applicable Profile constraints
+through the provider's child tools. A small investigation needs no synthetic
+WorkItem. If the child implements an existing Leader-owned WorkItem, keep that
+WorkItem roleless, supply its exact workspace and scope, and mark it running.
+Native children inherit only current parent authority and gain no Yui Role,
+AgentRun, Session or broader workspace. Their
+results are best-effort until Yui externalizes them; use a managed Task Role
+when independent durability matters. Inspect the returned result before
+submitting `done` or recording failure progress. `done` creates a Candidate;
+`work accept` records the separate acceptance. WorkItem responsibility remains
+open through execution failure and becomes accepted only on that decision.
+A Profile's runtime source applies when
+materializing a Task Role, not when launching a native child. The child
+inherits the Leader Agent; apply a Profile model or effort only when the native
+tool actually supports and confirms that override.
+
+### Managed Task Role
+
+```sh
+yui task role add <task-id> <role> --profile <profile>
+yui task role show <task-id> <role>
+yui task work create <task-id> "<outcome>" --role <role> \
+  --project <project> --objective "<bounded outcome>" --accept "<criterion>"
+yui task work dispatch <work-id> --input "<decision-complete brief>"
+```
+
+Add `--after` only for a real dependency. Likely file overlap is not by itself
+a dependency. A Worker may read the complete authorized Task context but may
+write only its WorkItem Projects and workspace. Dispatch prepares that isolated
+workspace and freezes the Assignment; inspect the completed original AgentRun
+result before submitting its exact Candidate, integrating, and accepting.
+
+Profiles carry portable behavior plus either a dynamic Global Worker runtime
+source or an explicit Agent with optional model and effort. Applying a Profile
+to a Task Role resolves and freezes the complete binding; later Profile or
+Global Worker changes do not rewrite that Role. Before dispatch, use
+`config profile show` and `task role show` to read the exact behavior, Agent, model,
+effort, Profile, and workspace. Do not reconstruct or guess launch
+configuration. Use the WorkItem assignee directly unless replicated execution
+was deliberately selected.
+
+Managed Task main, WorkItem, ReviewRound, and Integration workspaces have
+different owners. Never edit stable Project checkouts, managed refs, Yui state
+files, or another owner's workspace. A Task's recorded base is durable; do not
+silently replace it merely because its remote branch later moves.

package/skills/yui-leader/references/completion.md

@@ -0,0 +1,79 @@
+# Acceptance and completion
+
+Read before accepting a Candidate or attempting Task completion, not on every
+execution turn. Read [Review](review.md) when a managed result actually requires
+disposition, and [Integration](integration.md) before integrating isolated Git
+changes; neither is mandatory for unrelated direct implementation.
+
+## Accept, integrate, and complete
+
+A Worker or Reviewer AgentRun result is evidence, not acceptance. Inspect the
+result, diff, checks, and current Candidate before deciding.
+
+Group confirmed findings by root cause. Use the traced paths to check other
+reachable consumers/boundaries within scope and repair affected instances
+together, not just the reported checkpoint. Refresh the short material index
+and repair evidence where they changed, without accumulating round-by-round
+history. For ordinary full re-review, preserve the current complete
+candidate and requirements; add repair delta, prior finding dispositions and
+still-valid evidence. Delta is an attention aid, not the full-review boundary.
+Do not conflate this with an explicitly authorized equivalence Delta Recheck.
+Neither finding counts, fixed round counts nor a majority vote decides acceptance.
+
+If a result is insufficient, reject it with bounded feedback and redispatch
+the same WorkItem and Role while scope remains valid. Before accepting isolated
+Git changes, read [Integration](integration.md) to capture and
+integrate the latest Candidate. Do not edit managed refs or bypass Yui's
+compare-and-swap boundary.
+
+After an authorized PR/MR operation, follow
+[publication recording](../../yui-runtime/references/publication.md).
+External delivery and Task completion remain separate facts.
+Keep authorized follow-up delivery of this result in this Task and its legal
+managed workspace: synchronize, resolve necessary conflicts, validate, perform
+only the authorized external operations, and record their exact evidence.
+Do not refer ordinary delivery to a new Task. When remote delivery is part of
+the current requirement, a local commit or completed Run does not satisfy it;
+report a real blocker rather than declaring that requirement complete.
+
+After a ReviewRound is terminal, the Leader or authorized Operator owns
+`task work review cleanup <task>/<round>`. Preserve dirty diagnostic evidence
+and resolve it explicitly; do not ask a Reviewer to clean its own runtime
+after its final report. Cleanup can remain advisory at completion. Ordinary
+archive requires settled business and stopped execution, not complete physical
+release; safe resource retention is reported separately. Explicitly authorized force archive preserves
+unresolved resources and diagnostics under the shared
+[archive contract](../../yui-runtime/references/archive.md). The Leader
+does not gain independent archive authorization. An original explicit user
+archive request can authorize the Controller-owned ordinary archive described
+in [source-authorized capabilities](authorization.md).
+
+Complete only when the Task outcome is satisfied, required checks and review
+contracts are settled, WorkItems are accepted or deliberately retired, latest
+isolated results are integrated, and user inputs are resolved:
+
+```sh
+yui task complete <task-id> \
+  --summary "<outcome, validation, and remaining risk>"
+```
+
+Completion records the exact Project heads. Archive is a separate,
+user-authorized action, never an implication of completion or publication.
+
+Completion is offline by default. `--refresh-remote` only refreshes remote
+freshness observations; neither path rebases or starts Integration checks.
+For observation alone use `task base status <task> [--refresh]`. If upstream
+changes need integration, choose it explicitly before completion:
+`task upstream integrate <task> (--latest|--project <project>)` requests rebase
+and the configured checks/CAS. Consume its exact Integration/Job and partial
+results; a prepared candidate is not an advanced Task HEAD.
+An established final Review is still prepared/dispatched by completion without
+renewed approval. Inspect the returned stage and exact ReviewRound/Run: a
+Review-pending, running or blocked result is not Task completion.
+
+If completion reports `pending-user-input`, new user intent has not yet reached
+the current notification window. End this native turn so the next notification
+can be delivered, then read the original messages and reassess the outcome.
+Do not spin on completion, drop messages, or manufacture another Run to proceed.
+A current Leader Session can create a formal InputRequest during an ordinary
+notification; no active AgentRun is required.

package/skills/yui-leader/references/delivery-scope.md

@@ -0,0 +1,26 @@
+# Adjust Project delivery scope without erasing work
+
+When explicit user intent or an original delegation allows a Project to leave
+the final delivery, read that original Message and `task remote-delivery`.
+Record the bounded decision with
+`task project delivery <task> <project-id> --requirement excluded --reason <reason>
+--source-message <message-id> --purpose <verbatim-authorization>
+--if-current <scopeDecision.id|none>`.
+Interpret whether the original really authorizes this scope change; a matching
+quote alone is not semantic permission. Do not exclude a Project to conceal an
+unmet commitment. Ask only for a genuinely missing scope decision, not a second
+approval when existing user intent or delegated judgment already covers it.
+Use the same operation with `--requirement required` and the latest decision ID
+to restore normal checks. Reconcile a stale guard instead of overwriting newer
+intent. These append-only decisions also work on completed, unarchived Tasks
+without reopening, rewriting acceptance, or rerunning work.
+
+Unchanged Projects need no exclusion. Required changed/unknown Projects still
+need exact verified delivery. Excluded Projects retain their binding, code
+changes and Publication facts and are not counted as merged or verified merely
+because they are excluded. Scope is not execution, write, archive or deletion
+authority: open commitments and unknown execution still need settlement, and
+unique commits or dirty resources remain protected. With separate archive
+authorization, use ordinary archive/preflight and report retained resources;
+do not recommend force merely because an authorized Project is excluded.
+