@zq-silk/yui 0.15.8 → 0.15.9

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

@@ -0,0 +1,303 @@
+# Active execution
+
+Read this after the [Leader stage entry](../SKILL.md) selects authorized
+delivery. These implementation, dispatch, review and acceptance instructions
+are not requirements for ending a planning discussion or answering a query.
+
+## Choose the simplest coherent result
+
+Start from the current Task Contract and trace the existing implementation,
+ownership and supported operating path before choosing a change. Establish
+whether a failure is reachable with the user's actual inputs and configuration;
+do not make a test fixture's accidental differences into new product policy.
+
+Choose the lowest total implementation, verification, coordination and
+maintenance cost that satisfies the contract. Reuse a coherent responsibility;
+redesign a misplaced boundary when that lowers the complete cost. Add a
+mechanism only for a demonstrated requirement or hard boundary that existing
+primitives cannot satisfy. Derived views must not become competing truth.
+
+Make routine legal choices yourself. Do not ask the user to choose among
+implementation patterns, scheduling options, review routing, or recoverable
+runtime actions. Create an InputRequest only for a real product choice, new
+authority, irreversible external effect, or unavailable external fact.
+
+## Choose execution topology from ownership
+
+A WorkItem is one substantial requirement with an independent owner and useful
+acceptance boundary. It is not a container for every phase, file, test,
+finding, repair, or progress update. Task type, risk labels, file count, and
+subsystem names do not determine topology.
+
+Choose the smallest useful executor:
+
+1. **Leader directly** when current context, authority, and tools are enough.
+2. **Native subagent** for bounded specialist attention or parallel
+   investigation inside the current Agent Session when a best-effort child
+   result is sufficient.
+3. **Task Role AgentRun** when work needs independent durable ownership, a distinct
+   Agent/provider or credential set, a managed workspace, or a separately
+   recoverable Session and AgentRun lifecycle.
+
+Create multiple WorkItems only when their requirements can make useful
+independent progress, normally in parallel, and the coordination and
+Integration cost is lower than keeping one coherent owner. Keep coupled
+changes together.
+
+An ordinary WorkItem uses its assignee directly; dispatch without `--lane-role`.
+Use [replicated execution](replicated-execution.md) only when
+independent attempts over the same frozen Assignment repay their coordination
+cost. Direct managed execution already provides durable ownership.
+
+## Give Agents outcomes, not premature implementations
+
+Make delegated work decision-complete:
+
+- objective and observable acceptance criteria;
+- relevant Task and Project context;
+- hard scope, authority, and workspace boundaries;
+- known constraints, risks, dependencies, and existing decisions; and
+- expected checks and evidence.
+
+Let the receiving Agent choose its implementation plan, internal structure, and
+tools unless a particular ordering or mechanism is itself part of the accepted
+contract. Do not encode the Leader's speculative design as mandatory Worker
+steps.
+
+For Project-backed work, use the Project Skills, Policy, and Knowledge exposed
+through current context. Keep repository-specific build, migration, release,
+and test rules in that Project-owned layer.
+
+## Inspect execution facts
+
+Use `yui task context <task-id>` and `yui task next-action <task-id>` as
+decision support. They expose current facts, exact refs, and legal
+alternatives; they do not replace Leader judgment.
+An empty WorkItem list does not mean the user requested direct execution.
+Honor explicit delegation and independent Review requirements in the user's
+messages and Task Brief. Neither `next-action` nor a disabled default review
+policy authorizes dropping them to make completion easier.
+
+An Integration Job's success is not the final target update. For that
+notification, read [Integration](integration.md) and finish the same
+attempt; do not start a duplicate operation.
+
+Before dispatch, Review, Integration, or completion, inspect
+`liveTaskState.activeRuns` and `liveTaskState.activeTaskReviews` in the current
+Context Pack. They report work in flight but gate nothing by themselves; reason
+from each exact binding and frozen candidate instead of treating activity as a
+global Task lock.
+
+## Execute the chosen path
+
+Dispatch establishes the first owner and frozen Assignment. 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.
+
+For direct work, change only Task main, keep it on its managed branch, commit
+the result, and leave it clean. Run the smallest check that can catch the
+changed behavior while implementing.
+
+For a substantial delegated requirement:
+
+```sh
+yui task work create <task-id> "<title>" \
+  --project <project-to-modify> \
+  --objective "<bounded outcome>" \
+  --accept "<observable criterion>"
+```
+
+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.
+
+For a Leader-owned WorkItem, mark it running, complete it directly, then record
+its actual result:
+
+```sh
+yui task work update <work-id> running
+yui task work update <work-id> done --summary "<result and evidence>"
+yui task work accept <work-id> --summary "<explicit acceptance and evidence>"
+```
+
+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 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.
+
+For a 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>
+yui task work dispatch <work-id> --input "<decision-complete brief>"
+```
+
+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
+`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.
+
+## Extend capabilities within this Task's authority
+
+Use `capability search`, `describe`, and `call` to inspect current tools.
+Prefer existing tools, composition or a one-off script when sufficient.
+For reusable Task-local capabilities, read [Task plugins](task-plugins.md)
+before creation, validation or activation. Plugin management permission does
+not grant code execution or broader external effects. Never issue your own
+grants, impersonate Operator, or modify the core installation to obtain a tool.
+
+## Validate and make the review judgment
+
+Use the smallest evidence that establishes the accepted behavior and material
+boundaries. Do not repeat a successful unchanged check. Run the Project's
+complete local delivery validation once on the final candidate when its Policy
+requires it.
+
+As part of accepting a WorkItem or completing a Task, decide whether additional
+review would add useful evidence:
+
+- inspect directly when the change is clear and existing evidence is enough;
+- use one independent Worker, native child, or Reviewer when independent
+  inspection materially reduces a reachable risk; or
+- rely on an already completed applicable Review.
+
+This is Leader judgment inside the acceptance decision, not a separate record,
+checklist, or workflow phase. A managed Reviewer is optional unless the user,
+Project or Task Contract requires it. Do not create a
+Reviewer Role or ReviewRound for ceremony. Honor an existing Candidate's
+snapshotted `always` policy and any immutable Task-final Review contract.
+Otherwise choose whether another review adds enough evidence to justify its
+cost.
+
+Use one direct main Reviewer by default. If independent replicas materially
+improve evidence, read [replicated execution](replicated-execution.md)
+before dispatch or synthesis. Honor required review contracts even when a
+cheaper execution path is otherwise available.
+
+When several WorkItems contribute to one outcome, prefer one independent
+Task-final Review after their accepted results are integrated over repeating a
+complete Review for every WorkItem. Request an earlier WorkItem Review only
+when that frozen Candidate has a specific risk that should be resolved before
+Integration.
+
+When a Worker or Reviewer result arrives, resolve its exact AgentRun and read the
+complete original `AgentRunResult.output` before starting new work or waiting
+again. Treat headings or JSON fields only as communication aids; never infer
+that Core parsed or accepted them. Decide whether to accept, repair, review
+again, retry execution, or ask for a genuinely user-owned decision. Route
+reachable issues to the original execution owner. Fix a small Task-main issue
+directly; create a Repair WorkItem only when the repair is itself a substantial
+independently owned requirement.
+
+A failed ReviewRound is an execution failure, not an automatic retry or repair
+wave. Inspect its exact Round, AgentRun, candidate, Core failure, and
+`task next-action` facts, then choose the smallest recovery that preserves the
+frozen boundary. Do not invent a retry loop or silently replace the Reviewer
+Session. For replicated execution, choose whether to retry a failed Producer,
+settle that Lane, or synthesize selected available results. Retry a failed
+main synthesis through its exact AgentRun, preserving its selected source snapshot.
+
+## Accept, integrate, and complete
+
+A Worker or Reviewer AgentRun result is evidence, not acceptance. Inspect the
+result, diff, checks, and current Candidate before deciding.
+
+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.
+
+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, but all
+required resources must be settled before user-authorized archive.
+
+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 Operator action.
+
+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.
+
+## Finish an active execution turn
+
+Before ending authorized execution:
+
+1. Inspect the wake delta, resolve every referenced Worker or Reviewer AgentRun
+   with `yui task run show`, read each original result in full, and make the
+   next decision.
+2. Persist actual WorkItem lifecycle and material Brief, Decision, Milestone,
+   Message, or Knowledge changes.
+3. Choose one truthful outcome: continue through an owned native child, complete
+   the Task, create a justified InputRequest, or leave the active Task waiting
+   for a real durable event.
+4. For an explicitly dispatched AgentRun, return its truthful original final
+   report with outcome, checks, remaining risk and bounded next action.
+   Direct conversation and notifications do not require a separate execution
+   report; use the [stage-specific close](../SKILL.md#close-the-current-turn).
+
+Do not claim completion only in prose when durable Task or WorkItem state still
+needs updating. Do not poll managed Roles or emit waiting Messages. Managed
+results enter a later Leader notification; that notification is not an implicit
+AgentRun and requires no separate execution report. An unchanged active Task remains quiet.
+
+Use the shared [runtime recovery](../../yui-runtime/references/recovery.md) contract
+for failed execution. Persist successor context before replacing yourself,
+then end this turn; engineering cleanup is not discarded Task intent.

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

@@ -0,0 +1,109 @@
+# Planning and activation handoff
+
+Use this for Draft discussion, planning-only Sessions and the boundary into
+delivery. The [Leader entry](../SKILL.md) owns shared context maintenance and
+turn reporting; [Runtime](../../yui-runtime/SKILL.md) owns authority.
+
+## Discuss and preserve the outcome
+
+If the user asked only to create/store a Task, preserve the requirements and
+stop: do not start a planning Session. Once discussion is authorized, clarify
+requirements, inspect authorized current facts, compare options and revise the
+technical approach as the conversation develops. Distinguish unresolved
+questions, recommendations and accepted decisions.
+
+Planning can include research explicitly authorized by the user and permitted
+by the Session, Project and resource boundaries. Discussion is not delivery
+authorization: do not modify Project code or run implementation tests merely
+to support a proposal. Keep full planning results in supported Task result
+storage and maintain the Brief's current summary and references. Planning
+storage and Project delivery workspaces have different purposes and authority.
+
+Saving a useful revision, reporting what changed and waiting for feedback is
+the normal end of a discussion. Do not create implementation WorkItems,
+dispatch, Review, acceptance or Task completion to make a planning turn look
+finished. An InputRequest is not required for ordinary continued discussion.
+
+## Hand off only through authorized activation
+
+User/Operator submissions use `--intent record|discuss|develop` on
+`operator submit` or an unaddressed `task message send`. The default is
+`discuss`; Core does not infer intent from message text.
+
+- `record` saves the message without waking the Leader.
+- `discuss` on an unplanned Draft records the planning route and wakes planning.
+- `develop` on an unplanned Draft saves the requirement and activation intent,
+  then enters delivery through formal activation, without first starting planning.
+- `develop` after planning has been entered saves the input but does not wake
+  or activate; the routing result is `planned-needs-manual-activation`.
+
+Read the returned routing/feedback and current context before taking the next
+action. Active submissions do not downgrade or reactivate the Task; terminal
+submissions do not reopen it. A stopped execution gate is not permission to
+resume. `--request-id <key>` on submissions preserves the original result on a
+matching retry, not permission to replay uncertain work or change its content.
+
+Once planning has been entered, starting delivery requires a distinct,
+explicit activation authorization. A development remark during discussion,
+the end or failure of a planning Run, or Session replacement is not that
+action and does not restore “blank Draft” status. Accepted planning routing
+and historical Runs/Sessions count even when no Session is currently busy.
+“Manual activation” means an explicit user action, not that the user must type
+CLI commands: an authorized Operator can perform the mechanical operation.
+
+With that authorization, use the formal supported activation operation
+(`task activate <task-id>`) within the caller's authority, or have the Operator
+perform it. Inspect the observable result. Preserve a busy or unknown
+operation's exact request and follow
+[Runtime recovery](../../yui-runtime/references/recovery.md); do not
+self-dispatch, interrupt, kill or replace a Session to bypass the handoff.
+New discussion during a pending handoff does not authorize a competing
+planning Session. A failure calls for an explicit diagnosis and authorized
+recovery, not automatic downgrade or replay.
+
+Continue the durable requirements once the Task is formally active and a
+delivery-authorized Session/workspace is ready. Do not demand another
+“continue.” An old planning Session remains planning-scoped: preserve its
+successor context and end its turn rather than promoting itself.
+
+## Task artifact operations
+
+These operations apply to planning and delivery results. The current Leader
+adopts contributions from other Agents' authorized workspaces; do not share
+an uncoordinated Git index or edit Yui storage directly.
+
+```sh
+yui task artifact list <task-id>
+yui task artifact save <task-id> plans/design.md "<UTF-8 content>" --message "Revise design"
+yui task artifact read <task-id> plans/design.md
+yui task artifact read <task-id> plans/design.md <full-commit>
+```
+
+`save` writes and locally commits exactly one relative path, creating the
+repository on first save. The `artifact.save` capability takes `taskId`,
+`relativePath`, `content`, optional `message` and optional `expectedHead`;
+the CLI equivalent is `--expected-head <commit>`. A head conflict leaves
+the save unapplied: re-read and reconcile the intended update, not overwrite
+blindly. The text interface accepts UTF-8 files up to 8 MiB, not arbitrary
+binary payloads or an invented directory-upload command.
+
+Current reads use Task and relative path at HEAD. Frozen Candidate, Review,
+Context and completion evidence use the returned `taskId + commit +
+relativePath`; do not replace a pinned read with a current read. For same-Task
+string reference lists, use `git:<full-commit>:<relativePath>`, including
+`task complete ... --artifact-ref "git:<full-commit>:plans/design.md"`.
+The commit must be the artifact repository's returned commit, not the Project
+code head. Preserve fixed old references when updating the current document.
+
+After a meaningful save, update the Brief's summary/reference; keep Decisions
+to the choice, reason and boundary. No document-body, HEAD or timestamp mirror
+is needed. The artifact repository has no remote or transport; this does not
+prohibit a Project code repository's legitimate remote. Saving in Draft grants
+no delivery authority; Session handoff and archive preserve the artifacts.
+Stored scripts/HTML remain data and are never implicitly executed or previewed.
+
+These commands describe this source version's interface. A managed Session
+still uses its authorized CLI and actual available capabilities. If an older
+installation lacks them, report that version boundary; do not switch it to
+an unapproved checkout CLI, migrate a shared Home, or upgrade the installation
+merely to save a result.

package/skills/yui-leader/references/task-plugins.md

@@ -27,7 +27,11 @@ external effect does not authorize rerunning the action chain. After activation,
 query the directory again and use the new capability through the same bridge
 and native Session; no native tool-schema change or Controller restart is needed.
 
-Save the actual business result through `artifact.save` and retain the reference
-in Task results. Plugin source or successful loading alone is not delivery.
-Historical Artifacts remain readable after disable or restart; saved enable
-intent does not automatically execute code on restart.
+Save the actual business result as a file artifact with `artifact.save`
+(`relativePath` plus `content`): it commits exactly that path into the Task's
+local Git repository and returns a self-certifying `commit + relativePath`
+reference to retain in Task results. Plugin source or successful loading alone
+is not delivery. Committed artifacts remain readable after disable or restart
+through `artifact.read` at HEAD or a pinned commit; saved enable intent does not
+automatically execute code on restart, and an artifact's script or HTML is data,
+not a program to run under Yui authority.

package/skills/yui-operator/SKILL.md

@@ -53,16 +53,29 @@ determine Task identity. They also do not determine WorkItem count. Let
 isolated workspaces and Integration handle independent Git changes.
 
 Keep the Task title concise and put detailed intent, constraints, and evidence
-in its description or routed Message:
+in its description or routed Message. The examples below are separate
+operations, not an automatic create/submit/activate sequence. For creation-only
+intent, save the Task without starting planning. Discussion does not authorize
+delivery; follow the Leader's [planning and activation boundary](../yui-leader/references/planning.md)
+before activation. Do not reopen terminal Tasks merely because new input arrives.
 
 ```sh
-yui operator submit "<related request and delta>" --task <task-id>
+yui operator submit "<related request and delta>" --task <task-id> --intent discuss
 yui task create "<independent outcome>" \
   --project <project> --base <project>=<ref>
-yui operator submit "<request and routing context>" --task <new-task-id>
+yui operator submit "<request and routing context>" --task <new-task-id> --intent develop
 yui task activate <new-task-id>
 ```
 
+Choose the submission intent explicitly; it is never inferred from the message
+text. `discuss` (the default, and what an old client sends) routes the Draft to
+planning; `record` saves the message without waking the Leader; `develop` asks an
+unplanned Draft to activate now, and reports the exact next step when it cannot
+(already planned → activate manually; execution stopped → start it first). Pass
+`--request-id <key>` to make a submission idempotent: retrying the same key
+returns the original message and routing instead of creating a duplicate, and the
+same key with different text is refused as a conflict.
+
 Resolve all known Projects before repository-backed execution. A stable Project
 checkout is read-only reference state, not the Task base authority. Yui records
 the Task's remote baseline when creating its managed workspace; do not route