@zq-silk/yui 0.15.7 → 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/integration.md

@@ -0,0 +1,39 @@
+# Integrate an isolated result
+
+Read this before integrating a WorkItem Candidate or handling an Integration
+notification. Inspect the original result, diff, checks and exact Candidate.
+If insufficient, return bounded feedback to the owning WorkItem/Role while
+its scope remains valid.
+
+For acceptable isolated Git changes, capture and integrate the latest Candidate
+before acceptance:
+
+```sh
+yui task work capture <work-id>
+yui task integration start <task> --project <project> \
+  --change-set <change-set-id> \
+  --check "<Project Policy command>"
+yui task work accept <work-id> --summary "<decision and evidence>"
+```
+
+These are distinct decisions; confirm Integration succeeded before acceptance.
+Preserve each managed workspace's owner and the Task's recorded base. Do not
+silently advance that base because a remote branch moved.
+
+## Finish the same attempt
+
+For direct Integration checks running as a DurableJob, Job success is not
+the final target update. Read the terminal result, then use:
+
+```sh
+yui task integration continue <task>/<integration>
+```
+
+This also applies when no manual conflict resolution was needed. Do not start
+a duplicate Integration or wait for an empty queue to finalize it.
+
+Resolve failures using the exact conflict or check evidence and the supplied
+Integration workspace. Never bypass compare-and-swap, update managed refs by
+hand, or create a replacement WorkItem for ordinary Integration correction.
+Recheck changed behavior or unresolved failures; do not rerun unchanged
+successful validation without a current reason.

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/replicated-execution.md

@@ -0,0 +1,42 @@
+# Replicated execution and synthesis
+
+Read this only when choosing replication or executing a Producer/main
+synthesis assignment. Ordinary assigned WorkItems and direct Reviews do not
+need an ExecutionGroup or Lane.
+
+## Leader selection
+
+Replication means independent attempts at the same frozen Assignment, not
+different WorkItems executing in parallel. Choose it only when the extra
+evidence repays comparison, coordination and Integration cost.
+
+Use at least two distinct Producer Lane Roles. Replicated Review also has a
+separate main Reviewer for authoritative synthesis. Automatic policy-triggered
+Candidate Review stays direct. Do not treat a success count or a majority vote
+as Core acceptance.
+
+Select the original source AgentRuns explicitly:
+
+```sh
+yui task review synthesize <task>/<round> --source-run <task>/<run> ...
+yui task work synthesize <task>/<work> --source-run <task>/<run> ...
+```
+
+Lane completion or settlement does not dispatch synthesis automatically.
+A Lane retry remains the same replica. On failure, choose whether to retry
+that Producer, settle the Lane, or synthesize selected available results.
+Retry main synthesis through its exact AgentRun, preserving the source snapshot.
+
+## Producer and main Agent responsibilities
+
+A Producer independently inspects or implements its exact frozen Assignment
+in the supplied Lane workspace and returns one complete original result.
+Its evidence does not authorize a Candidate, ChangeSet, Integration or
+acceptance decision outside the assigned protocol.
+
+The main synthesis Agent reads every selected source AgentRun's original
+result, checks it against the frozen sources, resolves disagreement through
+judgment, and returns one authoritative report. Do not mutate source results,
+omit selected evidence, rerun Producers, or substitute a winning Lane for
+synthesis. A Review report remains evidence for Task acceptance, not acceptance
+itself.

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

@@ -0,0 +1,37 @@
+# Task-local capabilities
+
+Read this before creating, validating or activating a Task-local plugin.
+Use the stable Session CLI's capability directory and read the exact schema
+before each unfamiliar operation. Prefer an existing tool, composition or
+one-off script unless a reusable named capability is useful.
+
+The authenticated Leader can create, scan, validate, activate and disable
+Task-local plugins through `plugin.*` in an adopted writable environment.
+`plugin.scan` reports the package digest without execution;
+`plugin.validation` reads saved evidence; `plugin.inspect` distinguishes
+persistent enable intent from the Host's loaded implementation.
+
+Management permission does not authorize execution. Trusted-local build,
+validation, activation or calls require an existing `plugin.execute` grant for
+the exact plugin id, digest, environment, trust and phase, within its remaining
+uses and validity. A source change cannot inherit an old digest's grant.
+Trusted-local subprocesses are not an OS sandbox.
+
+Never issue your own grants, impersonate Operator, change global configuration,
+or modify the core installation, namespace or carrying Endpoint to obtain a
+tool. Request only a genuinely missing resource or trust boundary, not authority
+already available. Plugin grants do not authorize unrelated external effects.
+
+Preserve validation failures and operation receipts. An unknown or partial
+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 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.