@zq-silk/yui 2.20.0 → 2.22.0

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

@@ -0,0 +1,90 @@
+# Review and result disposition
+
+Read before requesting independent Review or disposing of a Worker/Reviewer
+result. Read the exact full original result before the disposition; a notification
+or summary is not acceptance. This is not an implementation-stage prerequisite.
+
+## Validate and make the review judgment
+
+Prepare useful evidence, not a documentation gate. From effective requirements,
+non-goals and decisions, distill the few observable behavioral constraints that
+matter to this change, with independently grounded expectations. Do not infer
+correctness from the candidate or its mocks.
+
+For material cross-layer or asynchronous risks, trace a short real path in the
+exact candidate: entry -> actual consumers -> relevant waits/atomic commit
+boundaries -> observable result and failure/recovery consequences. Point to
+candidate code or existing documents, not just module names or a coverage claim.
+Use it to expose where the same constraint must hold across boundaries; do not
+enumerate every entry or generate a combination matrix. Keep three things
+distinct: constraints/scenarios and expectations, executable test references,
+and actual results with candidate/environment/command. Name material unverified
+boundaries; a test reference alone is not a passing result.
+
+Small tasks can reference existing materials directly. For complex tasks, put a
+short review index in Task artifacts and its commit-pinned reference in Brief.
+Keep Brief an up-to-date summary, not a copy of documents or accumulated history.
+Review Context carries the frozen Brief and active decisions; inspect the
+actual pointer inventory when a material's delivery is uncertain. Read referenced
+same-Task artifacts at their fixed commits, not HEAD. Do not assume a path in
+`--input`, a WorkItem-only `--context-ref` option, or a summary grants Review
+access. Recover a missing authorized reference through existing mechanisms;
+do not ask the Reviewer to bypass scope. Materials guide independent inspection,
+not its upper bound.
+
+Use the smallest evidence that establishes the accepted behavior and material
+boundaries. Reuse a successful check only while its candidate, command, inputs
+and relevant environment remain valid; retain its exact result reference.
+A different candidate is not covered by an old success: check the changed
+behavior and required integration boundaries. Unknown, failed and not-run
+checks remain visible. Run the Project's complete local delivery validation
+on the final candidate when required; do not repeat unchanged valid success.
+
+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.
+One Reviewer should use the applicable complementary perspectives in one round.
+Consider independent replication for genuinely complementary cross-system risks,
+not a fixed headcount or file/frontend/backend partition. Keep the same candidate
+and common requirements; risk emphasis must not hide cross-layer contracts.
+
+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 a repair wave. First read
+its Provider retry projection: bounded infrastructure recovery may already own
+the successor. Otherwise 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.

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

@@ -0,0 +1,23 @@
+# Durable working context
+
+Read when materially updating Brief, Milestones or cross-Task
+Knowledge. Routine unchanged continuation needs no update or manual reload.
+Runtime’s read-only intent boundary applies.
+
+The DB Brief holds current focus, next action, unresolved commitments/unknown
+effects and fixed plan/report/activation/input references, not full documents
+or chronological history. At meaningful progress, requirement changes and phase
+handoffs, read `task brief show`, then update only intended fields using
+`task brief update --if-current <writeGuard>`. Replace superseded text; retain
+history in original records/artifacts. Read `task event list` before deliberately
+restoring an older value. On stale guard, read and reconcile new input rather
+than replaying old text; Core's lifecycle diagnostics do not rewrite history.
+
+Before `task complete`, reread Brief and correct resolved blockers or obsolete
+waiting/plans. Unchanged routine steps need no update; do not duplicate the
+terminal completion summary or create a new completion gate.
+
+Add a Milestone only for an independently meaningful outcome, a Message only
+for a new conclusion another reader needs, and Project Knowledge only for a
+stable cross-Task lesson. Do not create records for every exchange, dispatch,
+heartbeat or unchanged wait. Ordinary fact edits need no self-wake.

package/skills/yui-leader/references/work-allocation.md

@@ -0,0 +1,118 @@
+# Work allocation and dispatch
+
+Read before choosing or changing a separate work/acceptance boundary, executor,
+or concurrency topology. Direct work on an existing coherent result needs no
+allocation ceremony. Preserve existing ownership until a justified change.
+
+## Separate the work unit, executor, and concurrency
+
+Honor the user's explicit choice of direct work or delegation. Otherwise make
+three independent judgments; additional Review is a separate acceptance judgment,
+not a reason by itself to delegate implementation.
+
+**Does this result need its own management and acceptance boundary?** A WorkItem
+is a substantial result worth managing and accepting separately inside the Task.
+It need not have a different person, an independent release, or parallel execution.
+Use zero WorkItems when the Task already holds one coherent outcome. One WorkItem
+can be Leader-owned or hold a justified whole-result managed Assignment and
+Candidate. Copying the Task unchanged or displaying progress is not a reason
+to create it. Do not split analysis, editing, testing, Review, and ordinary
+repairs into phase-shaped WorkItems.
+
+**Who should execute?** Direct Leader execution is the default viable path for
+one coupled result when current context, delivery authority, and tools suffice.
+A native child can supply bounded specialist attention or parallel investigation
+inside this Session when a best-effort result suffices; it creates no Yui identity,
+authority, or WorkItem by itself.
+
+Choose a managed Worker only for a concrete benefit that repays requirement
+restatement, context reload, startup, waiting, inspection/rework, Integration,
+and lifecycle management. Benefits include safely parallel independent results,
+a needed capability or execution environment, a genuinely necessary separately
+recoverable lifecycle, freeing the Leader for another actual responsibility,
+or explicit user delegation. An available Worker, cheaper/different model,
+many files, high risk, long duration, or generic maintainability alone is not
+enough. Risk can justify independent Review without delegating implementation.
+When delegation involves a material tradeoff, leave one sentence of concrete
+benefit in the existing Brief; no form, approval, or separate decision record
+is needed.
+
+**Should separate units run concurrently?** Multiple WorkItems may run serially
+because of a real dependency, or concurrently when their results can advance
+independently and the net benefit exceeds coordination and Integration cost.
+Neither a single WorkItem nor multiple executors proves parallelism. Keep
+coupled changes together.
+
+For example, fix one coupled behavior directly in Task main, even when it touches
+many files. Delegate an independent import tool while the Leader implements its
+consumer when the two have a stable boundary and useful parallel progress.
+Keep two separately accepted stages serial when the second genuinely needs the
+first result. Do not wrap a whole Task in an `implementer` WorkItem merely because
+that Role exists.
+
+Apply these choices to new work. Do not automatically cancel an existing Worker,
+reassign/retire WorkItems, or move workspaces to conform to a new default; preserve
+their current ownership and evidence until a justified explicit change.
+
+An ordinary managed dispatch uses the WorkItem assignee; omit `--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.
+
+Before WorkItem dispatch, put the complete bounded requirements in the WorkItem
+or explicitly select up to 16 relevant readable materials with repeated
+`--context-ref <store/refId@digest>` on `task work dispatch`. Obtain exact IDs and
+digests from current Task context list/inspect. Core freezes these selected
+values after the existing caller-scope checks; mentioning a record in `--input`
+does not select it or grant access. Missing, forbidden or changed references
+refuse dispatch before Provider startup: correct the selection or make the
+WorkItem self-contained, never ask the recipient to bypass expansion rejection.
+
+Before creating or acting on an Assignment, read
+[Assignment execution](assignment-execution.md). Before dispatch inspect current
+exact active Run/Review bindings; activity is not a Task-wide lock.
+
+## 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.
+
+Missing or cyclic dependencies identify conflicting records, not the correct
+business repair. Read the related requirements, preserve valid edges, then
+explicitly revise the intended dependency set or retire genuinely obsolete work.
+Do not clear all dependencies merely to make a mechanical gate pass.
+
+An Integration Job's success is not the final target update. For that
+notification, read [Integration](integration.md) and continue from its exact
+evidence; do not start a duplicate operation. Read that guidance also for an
+ordinary Git conflict or an attempt that cannot be reliably resumed.
+
+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.