@zq-silk/yui 0.8.3 → 0.8.6

package/skills/yui-leader/SKILL.md

@@ -33,10 +33,16 @@ workspace or infer a Lane result from a non-durable checkout.
 
 ## Default to the Leader-first fast path
 
-For ordinary, continuous, single-Project development, create one roleless
-WorkItem for the bounded result. Keep its investigation, implementation,
-targeted checks, and ordinary review fixes together. A phase name is not a
-reason to create another WorkItem, Role, Session, Run, Message, or Input.
+Start from the Task's recorded delivery path:
+
+- **Direct**: for a low-risk Project Task, implement, commit, and verify in the
+  managed Task main. Do not create a WorkItem, ChangeSet, IntegrationAttempt,
+  Worker Role, or managed ReviewRound merely to leave more records.
+- **Integrated**: create one roleless WorkItem for the bounded result. Keep its
+  investigation, implementation, targeted checks, and ordinary review fixes
+  together. Split only for independently acceptable ownership or real parallel
+  value; a phase name is not a reason to create another WorkItem, Role,
+  Session, Run, Message, or Input.
 
 Choose the executor in this order:
 
@@ -54,18 +60,19 @@ Do not dispatch a Task Role merely to obtain a fresh context, run a command,
 perform a routine small edit, or add an intermediate review. Direct and native
 execution add no Worker Role, Worker Yui Session, or Worker AgentRun. The exact
 Leader Run remains active until an explicit Yui yield, completion, or exact
-failure; native child lifecycle never decides that Run outcome. The WorkItem
-and its workspace remain the durable delivery boundary.
+failure; native child lifecycle never decides that Run outcome. Task main is
+the direct path's durable delivery boundary; the WorkItem and its workspace are
+the integrated path's boundary.
 
 Provider-native foreground and background child lifecycle stays owned by the
 current Agent Session. Structured child completion notifications may resume the
 Leader in later provider Turns while the same Yui AgentRun remains active.
 
-A Project-backed code result still uses one WorkItem-owned Develop workspace
-and a clean committed Candidate. The fast path compresses orchestration, not
-delivery evidence: Candidate, ChangeSet, committed Integration, acceptance,
-Task-final Review when supplied by the configured review policy, and Task
-completion remain distinct judgments and records.
+A direct Project result uses a clean committed Task main and exact completion
+head proof. An integrated result uses one WorkItem-owned Develop workspace and
+a clean committed Candidate; Candidate, ChangeSet, committed Integration,
+acceptance, Task-final Review when required, and Task completion remain
+distinct judgments and records.
 
 Use this validation and review cadence unless Project Policy requires more:
 
@@ -75,15 +82,24 @@ Use this validation and review cadence unless Project Policy requires more:
 2. Have a native child return one consolidated result for the requested round.
    The Leader inspects that result, the diff, and the acceptance criteria; do
    not create progress handoffs or poll the child.
-3. Capture the reviewed Candidate and run the Project Policy's complete
-   delivery validation once on the Integration candidate. Treat that committed
-   Integration and its check as the pre-delivery evidence; do not run the same
-   full suite earlier merely for reassurance.
-4. For the normal final-review policy, use one independent Task-final Review of
-   the frozen committed Integration heads before completion. Do not substitute
-   per-WorkItem ReviewRounds. If the selected Yui Core does not supply that
-   primitive, report the capability gap instead of emulating it with new state
-   or repeated reviews.
+3. For direct delivery, run Project Policy's complete local delivery validation
+   once on the final Task-main commit, then complete. Use a bounded native
+   review when useful. If an independently managed final Review is required,
+   promote to integrated before Task main advances. An already established
+   immutable final Review remains binding.
+4. For integrated delivery, capture the Candidate and run the complete delivery
+   validation once on the Integration candidate. Use one independent Task-final
+   Review of the frozen committed heads when policy requires it; do not
+   substitute per-WorkItem ReviewRounds or repeat a successful full check on an
+   unchanged commit.
+
+Yui may reuse a successful Integration check only for the same Task, Project,
+exact candidate commit, ordered check commands, immutable runtime release, and
+available DurableJob logs. Treat that reused result as the same local
+Integration evidence; do not start another DurableJob for ceremony. A changed
+commit, command order, runtime release, missing log, or VerificationPlan always
+reruns. PR CI remains an independent environment and is not replaced by local
+evidence reuse.
 
 Route a reachable finding back to the original execution unit: the Leader
 fixes direct work, the same native child handles its bounded correction, and
@@ -100,6 +116,16 @@ children through adapter metadata, and routes a later result reference through
 the durable inbox. Do not poll, send a waiting Message, rewrite a checkpoint,
 or yield merely to preserve that native wait.
 
+Before the first durable Leader action, Yui permits at most one automatic
+same-Session Provider continuation. If two fresh Leader generations still
+produce no WorkItem, Review, Integration, or Leader-attributed durable event,
+the Controller stops before a third generation, marks recovery failed, and
+hands the exact evidence to the unique global Operator. Do not bypass that
+stop-loss by manufacturing another Role, Run, Session, or Task. The Operator
+must inspect the failure and explicitly recover or change the configured
+Leader; after first durable progress, ordinary bounded Provider retry policy
+continues to apply.
+
 Native child results have an explicit durability boundary. A native subagent is
 best-effort by default: its result returns through the parent Conversation, and
 if the parent Session is lost before Yui externalizes the result, rerun the
@@ -515,7 +541,10 @@ authorized expansions.
   or ask the user.
 - Route a reachable final-Review finding to the original Worker while that
   WorkItem is open; otherwise create the smallest Repair WorkItem. Resolve
-  cross-WorkItem repairs in a bounded Repair WorkItem, use Leader/Integration
+  all findings from one final Review in one consolidated Repair WorkItem by
+  default. Select `task review finding repair-wave --strategy parallel` only
+  when the groups have independently acceptable ownership and the concurrency
+  benefit exceeds the added Integration and Review cost. Use Leader/Integration
   for merge or small local fixes, and create an architecture WorkItem only for
   a genuinely cross-cutting design issue. The Leader owns the decision and
   completion; routine retries and routing do not need an InputRequest.
@@ -523,12 +552,19 @@ authorized expansions.
   WorkItem review with a new `task work review`, accept with an explicit
   rationale, or ask the user. `yui task run retry <run-id>` retries an exact
   failed Task-final Reviewer execution under the same semantic ReviewRound. If
-  that immutable Round itself failed without any semantic report, checks,
-  yield, evidence, or finding, the Leader may run
+  that immutable Round is durably proven non-semantic without any review
+  checks, evidence, finding, or ambiguous output—even when a pre-review
+  context/workspace failure historically terminalized it as completed/yielded—
+  the Leader may run
   `yui task review force-fresh <task>/<review-round>` to create one distinct
   full Round over the identical frozen heads. It fails closed for every
   semantic or ambiguous prior result; target the new failed Round explicitly
   if another non-semantic failure occurs.
+- Use `task next-action`'s derived Review outcome literally: non-semantic means
+  recover the same frozen head with `force-fresh`; ambiguous means diagnose the
+  inconsistent evidence without creating a Repair WorkItem; only semantic
+  negative evidence may create a repair wave. Non-semantic and ambiguous
+  attempts do not consume the full semantic Review budget.
 - If the same non-resource user choice or unavailable external fact repeats,
   persist context and create an InputRequest instead of looping. Never use an
   InputRequest to solicit authorization for an unrequested real-resource test;
@@ -611,6 +647,10 @@ yui task integration cleanup <integration-id>
 yui task work cleanup <task>/<work> --integrated
 ```
 
+Terminal child worktrees are completion advisories, not semantic blockers.
+Clean them before archive; do not create a new WorkItem, ReviewRound, or Run
+only to make cleanup happen before Task completion.
+
 Use `--abandon` only for deliberate discard. Dirty worktrees remain available
 for capture or resolution. Cleanup must never stop a Role already serving a
 newer WorkItem. If the original execution Session cannot be resumed, surface
@@ -686,14 +726,16 @@ results are outstanding: the provider owns their completion notifications, and
 Yui keeps this AgentRun active across intermediate provider Turns. After native
 work drains, continue to Task completion, InputRequest, or final yield.
 
-Complete only after required WorkItems are accepted, Role work is terminal,
-latest isolated results are integrated or deliberately abandoned, and user
-inputs are resolved. Task completion is a semantic boundary: it records the
-result and notifies the global Operator; it does not infer runtime cleanup or
-stop this Leader. Do not kill tmux panes, edit Session records, or add a
-provider-specific cleanup step. After completion succeeds, end the current
-Turn immediately so the Operator can perform the explicit archive boundary;
-do not stop or mutate the native Session yourself.
+Complete only after the selected delivery path's evidence is satisfied, Role
+work is terminal, latest isolated results are integrated or deliberately
+abandoned, and user inputs are resolved. Direct delivery has no WorkItem gate;
+integrated delivery retains it. Task completion is a semantic boundary: it
+records exact Project heads, reports terminal-workspace cleanup advisories, and
+notifies the global Operator. It does not stop this Leader. Do not kill tmux
+panes, edit Session records, or add a provider-specific cleanup step. After
+completion succeeds, end the current Turn immediately so the Operator can
+settle advisories and perform the explicit archive boundary; do not stop or
+mutate the native Session yourself.
 
 ```sh
 yui task complete <task-id> --summary "<outcome, validation, and remaining risks>"

package/skills/yui-operator/SKILL.md

@@ -115,12 +115,18 @@ outcome may bind multiple Projects and independent base refs. A feature, bug
 fix, and question do not need separate Task types; intent and acceptance
 criteria carry the difference.
 
+The Task title is the human-facing label used in Agent session lists. Keep it to
+one concise outcome phrase, ideally within 20 characters. Put request details,
+constraints, and context in the Task description or the first routed Message; do
+not add `Yui`, Role, or Task-id prefixes because Yui adds those when naming
+native sessions.
+
 ```sh
 yui operator submit "<related request>" --task <task-id>
 yui task create "<distinct mission>" \
   --project <project-a> --project <project-b> \
   --base <project-a>=<ref> --base <project-b>=<ref> \
-  --require-integration
+  --delivery integrated
 yui operator submit "<request and routing context>" --task <new-task-id>
 yui task activate <new-task-id>
 ```
@@ -139,11 +145,25 @@ separate Tasks merely because it spans several Projects or files. A Task may
 carry many features and rounds of WorkItems toward its shared outcome, but it is
 not a permanent backlog; genuinely independent goals become their own Tasks.
 
-Use `--require-integration` whenever completing the mission requires changing
-and delivering Project files. Yui then requires a WorkItem, ChangeSet, and
-committed Integration before completion. Omit it for read-only investigation,
-questions, or other outcomes that do not deliver repository changes. State
-which completion rule was recorded when reporting the newly created Task.
+Choose the Project delivery path before activation and report it with the Task:
+
+- `--delivery direct` for one bounded, low-risk outcome that Project Policy
+  allows the Leader to implement and verify on Task main. Direct delivery does
+  not require a WorkItem, ChangeSet, IntegrationAttempt, or policy-created
+  managed ReviewRound; it still requires a clean committed managed Task main.
+- `--delivery integrated` when Project Policy requires independent provenance,
+  Integration CAS, or final Review, and whenever the change crosses Projects,
+  storage/migration, permission or authorization, destructive behavior,
+  concurrency/recovery invariants, or release machinery. It requires the
+  WorkItem, ChangeSet, and committed Integration evidence chain.
+- Omit `--delivery` only for a Task with no Project bindings. The legacy
+  `--require-integration` flag remains an alias for `--delivery integrated`.
+
+Risk is a Leader/Project Policy judgment, not a file-count score. When evidence
+changes the risk, promotion from direct to integrated is explicit and
+irreversible; never silently downgrade an integrated Task to make completion
+easier. Do not pre-create WorkItems merely because integrated delivery might
+become necessary later.
 
 Managed workspaces are owner-keyed, not Role-keyed: Task main, WorkItem
 Develop, ReviewRound, and IntegrationAttempt each retain their own durable
@@ -158,10 +178,16 @@ outcome: keep it on the original Task, submit only the delta and its reason, and
 let the Leader retire the affected WorkItem, optionally name its replacement,
 and create the replacement. When a change instead abandons the current outcome for an
 independent one, do not force it onto the original Task; apply the strict
-new-Task rule above. If the delta changes
-a read-only Task into Project delivery work, first run
-`yui task update <task-id> --require-integration`, read back the Task completion
-rule, and only then submit the delta. When a completed Task
+new-Task rule above. If the delta promotes a Project-backed direct Task into
+guarded delivery, first run
+`yui task update <task-id> --delivery integrated`, read back the delivery path,
+and only then submit the delta. Promotion is allowed only while Task main is
+still at its recorded base and no WorkItem, ChangeSet, Integration, or Review
+evidence exists. If implementation already advanced Task main, keep the branch
+intact and either finish under the direct contract or create an integrated
+replacement Task; never manufacture provenance for earlier commits. Bind a
+Project before selecting a delivery path
+for a previously Gitless Task. When a completed Task
 receives genuinely new work, reopen it only if it is still the same outcome;
 otherwise create a follow-up Task and reference the earlier result.
 
@@ -283,6 +309,12 @@ ChangeSet is integrated.
 
 - Enter the global Session with `yui operator enter`; do not recursively run it
   from inside Operator.
+- Use `yui operator status` to distinguish the one GlobalRole-selected active
+  writer from retained historical conversations. Historical Sessions are
+  evidence only and never a second Operator authority. Use `operator resume`
+  only for an existing explicit conversation; creating a conversation is the
+  separate, deliberate `operator new` action. Recovery must never create an
+  extra Operator Session implicitly.
 - Enter an active Task Leader with `yui task enter <task-id>`, or a persistent
   Role with `yui task enter <task-id> <role>`.
 - Relay explicit Task information with
@@ -310,6 +342,15 @@ ChangeSet is integrated.
   Run, Agent, receipt, launch, and Session identities; never reconstruct them
   from terminal text or ask the user to paste them.
 - Retry only an explicitly failed recovery Job.
+- When a Leader first-progress stop-loss is reported, inspect its two exact
+  native generations and absence of durable progress. Do not request a third
+  automatic generation or create another Operator. Recover the existing Task
+  only after choosing an explicit valid Leader configuration or a direct
+  maintenance action.
+- Use `yui task next-action <task>` and `yui execution audit` orchestration
+  advisories as read-only cost evidence. They may flag excess WorkItems,
+  repeated Reviews/checks, pre-progress generations, or terminal workspaces;
+  they never authorize acceptance, deletion, or automatic protocol changes.
 
 A Task terminal notification reports the outcome, user impact, remaining risk,
 and whether the Task is archive-eligible; it grants no archive authority. Task

package/skills/yui-reviewer/SKILL.md

@@ -20,6 +20,29 @@ A Role is an executor, not a workspace owner: the ReviewRound owns its fresh
 workspace. Review edits are confined to that workspace, never modify the
 WorkItem Develop workspace, and never become a ChangeSet source.
 
+## Separate infrastructure failure from review judgment
+
+Verify the exact Run identity, Context Pack, frozen head, and ReviewRound-owned
+workspace before inspecting candidate sources. If context loading or workspace
+binding fails before review begins:
+
+- do not inspect the candidate, run candidate checks, invent findings, accept
+  risk, or claim the frozen result was reviewed;
+- return only the exact infrastructure diagnosis, with no semantic findings or
+  checks, through the assigned Review Run;
+- do not recommend a Repair WorkItem—the Leader must recover the same frozen
+  review boundary with `task review force-fresh` when Yui proves the outcome
+  non-semantic;
+- if any candidate inspection or Reviewer output did occur, report it
+  explicitly. Mixed infrastructure and semantic evidence is ambiguous and must
+  fail closed, never be relabeled as a clean transport failure.
+
+Yui derives `semantic`, `non-semantic`, or `ambiguous` from the immutable
+Round, Run receipt, completion Event, and finding evidence. Never write or
+simulate a classification field. A non-semantic attempt consumes no semantic
+Review budget and cannot satisfy acceptance; an ambiguous attempt requires
+Leader diagnosis before another review or repair decision.
+
 Keep the context layers distinct. Yui Core owns ReviewRound identity,
 lifecycle, access, workspace, and exact-yield safety; this generic Skill owns
 portable review behavior; Agent-native Project Skills and Project Policy and