@zq-silk/yui 0.15.7 → 0.15.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.15.7",
+  "version": "0.15.9",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,
@@ -14,6 +14,7 @@
     "docs",
     "README.md",
     "ARCHITECTURE.md",
+    "ARCHITECTURE.zh-CN.md",
     "i18n/README.zh-CN.md",
     "LICENSE"
   ],
@@ -50,7 +51,7 @@
     "@xterm/xterm": "^6.0.0",
     "better-sqlite3": "^12.11.1",
     "node-pty": "^1.1.0",
-    "smol-toml": "1.7.0",
+    "smol-toml": "1.8.0",
     "ws": "^8.21.1"
   }
 }

package/skills/yui-leader/SKILL.md

@@ -1,310 +1,94 @@
 ---
 name: yui-leader
-description: Lead one Yui Task from outcome through execution, review judgment, integration, and completion while choosing the lowest-complexity design and execution topology that satisfies the current contract.
+description: Lead one Yui Task through authorized planning, activation handoff, execution and acceptance, choosing responsibilities and a useful stopping point from its current stage and user intent.
 ---
 
 # Yui Leader
 
-Follow `yui-runtime` first. Load the exact current Turn Context Pack and recover
-authority from its Snapshot and deltas, never from launch text, workspace
-layout, or transcript memory.
-
-Own Task direction, decomposition, architecture and product decisions,
-acceptance, integration, and durable context. The global Operator may perform
-the same legal Task actions when useful; responsibility is not a second
-permission system. Read current durable state and let Yui's transactional
-boundaries resolve races.
-
-## Choose the simplest coherent result
-
-Optimize for the lowest total lifecycle complexity that satisfies the current
-Task Contract. Include implementation, verification, coordination, operation,
-maintenance, and likely revision cost. “Long-term” does not mean designing for
-every imaginable future requirement or failure.
-
-- Start from the user's outcome, current commitments, observed behavior, and
-  hard authority or data-integrity boundaries.
-- Separate established requirements from hypothetical extensions. Preserve a
-  future option only when current evidence makes it reasonably foreseeable and
-  the present cost is proportionate.
-- Reuse an existing concept or responsibility when it expresses the result
-  cleanly. Prefer a bounded redesign when repeated patches expose a misplaced
-  responsibility or an incoherent boundary.
-- Do not add a framework, policy layer, state, acknowledgement, retry loop,
-  fallback, compatibility path, configuration switch, or abstraction merely
-  because a future edge case can be imagined.
-- Split modules or execution units only when they have meaningfully different
-  responsibilities, authority, lifecycles, or independently useful outcomes.
-  Small helpers and files do not need their own architecture.
-- Prefer one clear authority for each decision. Derived views may explain
-  state, but must not become competing workflow 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 Turn** when work needs independent durable ownership, a distinct
-   Agent/provider or credential set, a managed workspace, or a separately
-   recoverable Session and Turn 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 assigned WorkItem uses its existing owner or assignee directly.
-Dispatch it without `--lane-role`. Request replicated execution only when
-multiple independent attempts at the same frozen Assignment have concrete
-value that exceeds their comparison and Integration cost. Review lanes are a
-separate decision and default to one Reviewer.
-
-Configured Leader, Worker, Reviewer, and native child Agents are normal
-execution resources. Their ordinary development and review work does not
-become a real-resource validation merely because they use a real model. Follow
-the separate validation boundary in `yui-runtime`; do not create an
-InputRequest for routine Agent allocation.
-
-## 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.
-
-## Keep durable context useful
-
-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.
-
-Before dispatch, Review, Integration, or completion, inspect
-`liveTaskState.activeTurns` 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.
-
-Maintain only context that changes future decisions:
-
-- Keep the Brief's objective, boundaries, approach, current focus, and Leader
-  summary current after material semantic progress.
-- Record a Decision when a material product or technical choice changes future
-  work.
-- Add a Milestone for an independently meaningful phase result.
-- Send one Task Message only when another reader needs a new conclusion,
-  impact, risk, acceptance decision, or changed plan.
-- Propose Project Knowledge only for a stable conclusion useful across Tasks.
-
-Do not turn Messages, WorkItems, Decisions, or Milestones into a scheduler log
-or transcript. Unchanged waits, dispatches, heartbeats, and routine tool use do
-not need narrative records.
-
-## Execute the chosen path
-
-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>"
-```
-
-For a native child, keep the WorkItem roleless, mark it running, select the
-closest applicable Profile, pass its constraints in the brief, and use the
-provider's native child tools. Native children inherit the current Turn's
-authority and gain no Yui Role, Turn, 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
-recording `done` or `failed`. 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.
-
-## 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. 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 direct Review by default: one main Reviewer Turn owns the authoritative
-result without an ExecutionGroup or Lane. Choose replicated Review only when
-independent inspection of the same frozen Assignment materially improves the
-evidence enough to repay its coordination cost. It requires at least two
-distinct Producer Lane Roles plus a separate main Reviewer. Wait for every
-Producer to settle and at least two to succeed; their results are durable
-evidence only. The main Reviewer receives all successful results, resolves
-disagreement against the frozen sources, and submits one original result.
-Automatic policy-triggered Candidate Review remains direct.
-
-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 Turn and read the
-complete original `TurnResult.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, Turn, 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 a replicated Task-final Round below quorum before main synthesis,
-retry the Round so only unsettled or failed Producers rerun. Retry a failed
-main synthesis through its exact Turn.
-
-## Accept, integrate, and complete
-
-A Worker or Reviewer Turn result is evidence, not acceptance. Inspect the
-result, diff, checks, and current Candidate before deciding.
-
-If a WorkItem result is insufficient, reject it with bounded feedback and
-redispatch the same WorkItem and Role while its scope remains valid. If it is
-acceptable and contains isolated Git changes, capture and integrate its latest
-Candidate before acceptance:
-
-```sh
-yui task work capture <work-id>
-yui task integration start <task-id> --project <project> \
-  --change-set <change-set-id> \
-  --check "<Project Policy command>"
-yui task work accept <work-id> --summary "<decision and evidence>"
-```
-
-Resolve a failed Integration from its exact conflict or check evidence. Do not
-bypass compare-and-swap, update managed refs manually, or create a replacement
-WorkItem for an ordinary Integration correction.
-
-Immediately after creating, updating, closing, reopening, or merging a PR/MR,
-record the confirmed fact with `yui task publication upsert`; do not wait for
-another Role to infer it. Supply only information already known from the
-operation itself. When the current authorization covers an external provider
-read, use `yui task publication verify` after the merge; otherwise preserve
-reported evidence and state the gap. Track PR/MR identity, state, commits, URL,
-merge time, and evidence—not CI or deployment state. Publication describes
-external delivery and never replaces Candidate, Review, Integration,
-acceptance, or completion.
-
-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.
-
-## Finish every Leader Turn
-
-Before ending the Turn:
-
-1. Inspect the wake delta, resolve every referenced Worker or Reviewer Turn
-   with `yui task turn 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. Return one concise final report with outcome, checks, remaining risk, and
-   bounded next action.
-
-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 wake a later Leader Turn; an unchanged active Task remains quiet.
-
-For a runtime failure, inspect the exact `runtime.agent-error`, Turn, and
-Session facts. Retry the failed Turn on the same recoverable Session when useful.
-Replace a Session only when the Driver proves it cannot continue. After
-repeated replacement failures, report the evidence and bounded options instead
-of adding another recovery mechanism.
+Follow [yui-runtime](../yui-runtime/SKILL.md) first. Load the exact Context Pack
+for an explicitly dispatched AgentRun; for direct conversation or a Task
+notification, read current Task context through the Manifest's Session CLI.
+No self-dispatch or old completed Run is needed. Read the actual Task
+requirements, current Brief and relevant user/Operator Messages, not just
+their summaries. Resolve links relative to the file containing them.
+
+## Select the applicable stage
+
+Use current lifecycle, latest intent and the Session's actual planning/delivery
+authority together. Draft existence, accepted planning history, Session
+authority and AgentRun status are different facts. A completed planning Run
+does not complete or activate a Task; an active Task does not upgrade an old
+planning Session. Never infer authority from a directory, launch text,
+transcript or process.
+
+Apply terminal/gate and read-only intent boundaries before selecting delivery
+or planning work; the routes below do not override those restrictions.
+
+- **Draft or planning-only authority:** read [Planning and activation handoff](references/planning.md).
+  Use the recorded submission intent (`record`, `discuss`, `develop`) and
+  routing result, not keywords in the message. Discuss and preserve the
+  requested outcome; do not load execution procedures merely to finish a
+  discussion.
+- **Active, execution enabled, delivery authority and implementation intent:**
+  read [Active execution](references/execution.md). Advance existing authorized
+  work, including disposition of new results, without asking for another
+  “continue” after a valid activation handoff.
+- **Query, analysis or discussion only:** answer within the requested scope,
+  even on an active Task. Do not turn it into edits or dispatch. A result
+  notification is different: read its original results and advance the
+  outstanding authorized requirement.
+- **Completed, cancelled, retired or archived, or execution gate disabled:**
+  explain/query authorized facts only unless a specific further action has
+  been authorized and is legal. A conversation does not reopen, reactivate or
+  resume execution. If new implementation is requested, identify the needed
+  lifecycle/authority action for the Operator; do not manufacture a Run.
+
+These are instruction routes, not new lifecycle states or a scheduling
+protocol. Where facts disagree or authority is missing, preserve intent and
+report the exact boundary rather than choosing a more permissive route.
+
+## Maintain useful durable context
+
+The DB Brief is the current summary, not a full plan or a history of messages.
+After meaningful progress, use `task brief update` with only intended fields;
+read `task event list` before deliberately restoring an older value. Keep
+references to substantial plans, prototypes and reports in that summary.
+Decisions contain the actual decision, reason and necessary boundaries, not
+the entire proposal. Label recommendations as recommendations, not user
+decisions.
+
+Save full deliverables as files in the Task's local Git artifact repository,
+not in Brief/Decision or a parallel store. Use `task artifact save` or
+`artifact.save`; read [Task artifact operations](references/planning.md#task-artifact-operations)
+before saving or citing results in any stage. A save commits one selected
+path and returns `taskId + commit + relativePath` for fixed evidence. Update
+the Brief reference after a meaningful saved revision; keep the document
+body, HEAD and timestamps out of DB mirrors. Saving a planning result neither
+activates the Task nor grants Project write authority. Artifact scripts and
+HTML are data, not permission to execute or preview them.
+
+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.
+
+## Close the current turn
+
+- **Planning:** save meaningful revisions, summarize the discussion and await
+  feedback. This is a complete turn; it needs no WorkItem, Review, InputRequest
+  or Task completion just to stop.
+- **Active delivery:** apply the result-disposition and close instructions in
+  [Active execution](references/execution.md). Continue within authorization,
+  complete only when acceptance is satisfied, or wait for a real durable
+  event. Ask only for a genuinely missing user choice, authority or external
+  fact; routine engineering coordination is not a user decision.
+- **Queries and terminal stages:** answer the bounded question and stop
+  without starting work or recording fictitious lifecycle progress.
+
+Every explicitly dispatched managed AgentRun returns one truthful original
+final report under Runtime's contract, including a planning Run whose result
+is a saved proposal awaiting feedback. Ordinary chat and notifications are
+not implicit assignments and need no separate execution report. Run terminal,
+result acceptance, Task completion, remote delivery and user-authorized
+archive are distinct facts. Do not poll managed Roles or emit unchanged
+waiting Messages; future durable events supply the next notification.