@zq-silk/yui 0.8.2 → 0.8.6

package/ARCHITECTURE.md

@@ -5,13 +5,20 @@ runtimes. The user talks to one Operator. The Operator routes each request to
 the right Project and Task; that Task's Leader owns decomposition, execution
 choice, review, integration, and completion.
 
-## One work model
+## One outcome model, two delivery paths
 
-`WorkItem` is the only bounded unit of work. It holds the objective, acceptance
-criteria, dependencies, assigned Task Role when applicable, lifecycle, and a
-compact reviewed result.
+`Task` is the bounded user outcome. Its delivery path is derived from existing
+fields rather than stored as another state machine: no Project bindings means
+`no-project`; a Project-backed Task without `requireIntegration` is `direct`;
+and `requireIntegration=true` is `integrated`.
 
-A Leader chooses one of three execution paths for each WorkItem:
+Direct delivery lets the Leader implement and verify a low-risk result in the
+managed Task main without creating a WorkItem. Integrated delivery uses
+`WorkItem` as its only bounded execution unit; it holds the objective,
+acceptance criteria, dependencies, assigned Task Role when applicable,
+lifecycle, and compact reviewed result.
+
+For each integrated WorkItem, a Leader chooses one of three execution paths:
 
 1. **Direct**: the Leader executes a roleless WorkItem.
 2. **Native subagent**: the Leader creates a child through its current Agent
@@ -19,8 +26,9 @@ A Leader chooses one of three execution paths for each WorkItem:
 3. **Task Role AgentRun**: Yui dispatches a Role-bound WorkItem to a
    Task-managed native Agent Session.
 
-There is no Yui subagent launcher, child-session record, or second bounded-work
-model. Direct work and native subagents use the WorkItem lifecycle. Managed
+There is no Yui subagent launcher or child-session record. A native child on
+direct delivery remains inside the Leader Session and Task-main boundary; a
+native child implementing integrated work uses the WorkItem lifecycle. Managed
 independent execution additionally records an AgentRun.
 
 ## Profiles, Roles, and Agents
@@ -57,7 +65,7 @@ effort, round, result, and checks.
 
 ## Lifecycle and acceptance
 
-Direct and native-subagent work follows:
+Integrated Leader-direct and native-subagent WorkItem execution follows:
 
 ```text
 todo -> running -> done | failed
@@ -78,16 +86,22 @@ then accepts or rejects with bounded feedback. A rejected isolated WorkItem
 keeps its workspace so the next Run can repair the same result.
 
 An optional global review rule names one existing Global Role and chooses
-`always`, `leader`, or `final`. It is a live default for every Task; each
+`always`, `leader`, or `final`. Candidate rules remain live defaults; each
 WorkItem Candidate snapshots the effective legacy rule when submitted.
 Every result awaiting acceptance is stored as an explicit WorkItem candidate.
 `always` dispatches a review AgentRun for every candidate, whether it comes
 from a yielded execution Run or a Leader-managed direct result; `leader`
 leaves every candidate for the Leader to accept directly or review explicitly.
-`final` keeps WorkItem acceptance and Integration independent, then `task
-complete` queues one fresh Task-scoped ReviewRound over the frozen committed
-heads of every bound Project. A changed integrated head queues a new round;
-the previous report remains evidence. This final Reviewer evaluates the whole
+`final` applies automatically only to integrated delivery: it keeps WorkItem
+acceptance and Integration independent, then `task complete` queues one fresh
+Task-scoped ReviewRound over the frozen committed heads of every bound Project.
+A direct Task may use a bounded native review. When a managed final Review is
+required, it must be promoted before Task main advances; promotion fails after
+a commit or delivery evidence exists so earlier work cannot lose ChangeSet
+provenance.
+Any established immutable Task-final contract or Round remains an obligation.
+A changed integrated head queues a new round; the previous report remains
+evidence. This final Reviewer evaluates the whole
 Task, so normal delivery does not pay for a complete review of every WorkItem.
 Review Runs complete only their exact ReviewRound, leave the WorkItem awaiting
 acceptance, and never trigger another review or append a Candidate. Successful
@@ -133,8 +147,9 @@ Projects and Task-main context for the rest. The managed dispatch and
 writable set. Provider permission is binding configuration: every managed Role
 defaults to `bypass`, while `default` and `configured` preserve provider-native
 behavior. Provider permission and Profile access intent do not grant Project
-writes. A normal source write requires an exact WorkItem write scope and
-matching managed workspace; a review write instead
+writes. A direct source write requires the exact Leader Task-main owner. An
+integrated source write requires an exact WorkItem write scope and matching
+managed workspace; a review write instead
 requires an exact ReviewRound owner and frozen Candidate base. Profiles and
 Skills constrain behavior even when provider prompts are bypassed. Provider
 permissions remain Session-wide rather than Project-specific, so the durable
@@ -152,8 +167,8 @@ An isolated result is handled in this order:
 5. configured checks run;
 6. compare-and-swap advances the target only if its HEAD is unchanged;
 7. the Leader accepts the WorkItem;
-8. clean Integration, ReviewRound, and WorkItem resources are explicitly
-   removed.
+8. terminal Integration, ReviewRound, and WorkItem resources become cleanup
+   advisories and are explicitly removed before archive.
 
 The context contract is layered: Yui Core owns durable identity, lifecycle,
 access, and workspace safety; generic role Skills own portable orchestration;
@@ -162,15 +177,18 @@ project-specific engineering rules; and the Task Contract owns the requested
 outcome. Yui injects only its own generic Role Skills. It never scans or copies
 Project Skills into managed context; the selected Agent discovers them through
 its native project mechanism. Execution and review select their generic Skill
-by durable Run purpose. A Reviewer finding routes to the original
-Worker while open, a small Repair WorkItem when closed, Leader/Integration for
+by durable Run purpose. A Reviewer finding routes to the original Worker while
+open, one consolidated Repair WorkItem when closed, Leader/Integration for
 merge or local fixes, and an architecture WorkItem only for a genuinely
-cross-cutting design change.
+cross-cutting design change. Parallel repair is explicit and requires
+independently acceptable ownership.
 
 Capture at the same HEAD reuses the existing ChangeSet. A repaired HEAD creates
 a new candidate; only the latest reviewed candidate may satisfy acceptance.
-An isolated WorkItem cannot be accepted or a Task completed while any writable
-Project's latest result is uncaptured or unintegrated. Workspace roots are
+An isolated WorkItem cannot be accepted, or an integrated Task completed, while
+any writable Project's latest result is uncaptured or unintegrated. Direct
+completion instead requires a clean committed exact Task-main snapshot.
+Workspace roots are
 multi-Project; ChangeSets and Integration Attempts remain single-Project Git
 boundaries.
 

package/README.md

@@ -250,7 +250,8 @@ yui project update app --alias app-cli
 yui project refresh app
 yui project list
 
-yui task create "Ship CSV export" --project app
+yui task create "Fix CSV escaping" --project app --delivery direct
+yui task create "Ship CSV export" --project app --delivery integrated
 yui task update <task-id> --priority high --tags release,csv --due-at 2026-08-01T00:00:00Z
 yui task update <task-id> --clear-priority --clear-tags --clear-due-at
 yui task show <task-id>
@@ -258,6 +259,19 @@ yui task context <task-id>
 yui task activate <task-id>
 ```
 
+Project delivery is explicit but uses the existing Task schema. `direct` means
+the Leader implements and verifies one low-risk result on clean committed Task
+main; it needs no WorkItem, IntegrationAttempt, or policy-created final
+ReviewRound. `integrated` requires WorkItem, ChangeSet, and committed Integration
+evidence and remains the path for guarded, cross-Project, migration,
+authorization, concurrency/recovery, destructive, and release changes. Global
+final-review policy applies automatically only to integrated delivery. A direct
+Task can use a bounded native review. If an independently managed final Review
+is required, promote before Task main advances; promotion fails closed after a
+commit or delivery evidence exists so earlier work cannot lose ChangeSet
+provenance. Legacy `--require-integration` is an alias for
+`--delivery integrated`, and integrated delivery cannot be downgraded.
+
 `project refresh` is the explicit network operation for a stable Project checkout. It fetches the
 configured stable branch directly from the Project remote URL and advances only through a clean,
 verified fast-forward. Refresh requires matching stable and development branches, treats untracked
@@ -370,7 +384,8 @@ expands:
 ```sh
 yui task create "Update authentication" \
   --project backend --project frontend \
-  --base backend=develop --base frontend=main
+  --base backend=develop --base frontend=main \
+  --delivery integrated
 yui task project add <task-id> shared-sdk --base main
 ```
 
@@ -444,6 +459,7 @@ Submit information through Operator:
 ```sh
 yui operator submit "Compare CSV and JSON compatibility" --task <task-id>
 yui operator submit "Investigate a smaller cache design"
+yui operator status
 yui operator list
 yui operator resume
 yui operator resume --last
@@ -472,13 +488,15 @@ bounded outcome stay in that Task even when they involve multiple Projects.
 A distinct outcome, ownership boundary, or lifecycle creates a separate Task.
 Features, bugs, and questions use the same
 Task/WorkItem model rather than separate workflow types.
-`operator list` shows recent conversations in fixed most-recently-updated order using
+`operator status` shows exactly one GlobalRole-selected writer separately from
+retained historical conversations. `operator list` shows recent conversations in fixed most-recently-updated order using
 their Agent and readable title or preview; native provider session IDs remain
 internal. Until an adapter supplies that metadata, Yui shows the provider plus
 a stable short Yui reference so untitled conversations remain distinguishable.
-`operator resume` opens the same lightweight numbered list, while
-`--last` resumes the newest entry directly. `operator new` starts a clean
-conversation and preserves the previous one in history.
+`operator resume` opens the lightweight numbered history list, while `--last`
+resumes the newest entry directly. Starting a conversation is never a resume
+choice: the explicit `operator new` command starts a clean conversation and
+preserves the previous one in history.
 
 Create a Task-bound Worker instance from the configured global Worker, apply a
 Profile, and dispatch a WorkItem:
@@ -547,8 +565,10 @@ bounded next options. Yield records immutable Run/Candidate or Review evidence
 only; it does not imply acceptance, WorkItem completion, ChangeSet capture,
 Integration, or Task completion.
 
-For bounded work, the Leader owns a roleless WorkItem and may execute it
-directly or create a native subagent through the current Agent conversation:
+For integrated bounded work, the Leader owns one roleless WorkItem and may
+execute it directly or create a native subagent through the current Agent
+conversation. Direct delivery operates on Task main without creating this
+WorkItem:
 
 ```sh
 yui task work create <task-id> "Review the implementation" \
@@ -659,7 +679,39 @@ yui task complete <task-id> --summary-file delivery.txt --refresh-remote
 yui task reopen <task-id>
 ```
 
-Completed Tasks reject messages, dispatch, Provider authority changes, retry, and late yields until explicitly reopened, while retaining Task main for inspection or integration. Every isolated WorkItem worktree must be explicitly cleaned as integrated or abandoned before archive; that cleanup also removes its managed branch. Archive requires `--integrated` or `--abandon` to state the Task main outcome and is allowed only after Task main is clean. It removes managed worktrees but retains Task and WorkItem records. The Task main branch is retained as a recovery artifact instead of being silently deleted.
+When a verified squash-merge Publication records a remote commit that is
+ancestry-divergent from the unchanged local Task head, a user or global Operator
+may explicitly authorize completion against its identical Git tree:
+
+```sh
+yui task complete <task-id> --summary-file delivery.txt \
+  --accept-published-tree <publication-id>
+```
+
+This does not weaken normal freshness checks. Yui requires the current,
+unsuperseded Publication to be merged and verified, its local commit to equal
+the physical Task head, its remote commit to be ancestry-divergent, and both
+commits to resolve to the same exact tree. Integrated delivery also requires
+the latest completed Task-final Review; direct delivery does not invent one.
+`--refresh-remote` fetches
+the remote object graph before resolving that Publication commit. For a Task
+governed by a durable exact final-review contract, the user/Operator command
+persists the exact authorization tuple and wakes the Task Leader; only that
+contract-capable Leader may consume it and complete the Task. Tasks without
+that contract retain the one-step explicit completion path. The Task event
+audit records the authorization and, on completion, the accepted Project,
+Publication, optional ReviewRound, both commits, and tree.
+
+Completed Tasks reject messages, dispatch, Provider authority changes, retry,
+and late yields until explicitly reopened, while retaining Task main for
+inspection or integration. Terminal WorkItem, Review, Integration, and Lane
+worktrees are non-blocking completion advisories, but they must be settled
+before archive. Every isolated WorkItem worktree is explicitly cleaned as
+integrated or abandoned; that cleanup also removes its managed branch. Archive
+requires `--integrated` or `--abandon` to state the Task main outcome and is
+allowed only after Task main is clean. It removes managed worktrees but retains
+Task and WorkItem records. The Task main branch is retained as a recovery
+artifact instead of being silently deleted.
 Task lifecycle completion/selection only suggests valid source states: Draft for activate, active for complete, and completed for reopen.
 
 ## Sessions and tmux

package/dist/cli/commandCatalog.js

@@ -241,8 +241,9 @@ const taskChildren = [
     {
         name: "create",
         summary: "Create a Draft Task.",
-        usage: "yui task create <title> [--project <project> ...] [--base <project>=<ref> ...] [--require-integration]",
-        options: ["--project", "--base", "--require-integration"]
+        usage: "yui task create <title> [--project <project> ...] [--base <project>=<ref> ...] [--delivery <direct|integrated>] [--require-integration]",
+        options: ["--project", "--base", "--delivery", "--require-integration"],
+        optionValues: { "--delivery": ["direct", "integrated"] }
     },
     {
         name: "project",
@@ -265,20 +266,23 @@ const taskChildren = [
     {
         name: "update",
         summary: "Update Task metadata.",
-        usage: "yui task update <id> [--title <text>] [--description <text>|--clear-description] [--priority <low|medium|high|urgent>|--clear-priority] [--tags <comma-separated>|--clear-tags] [--due-at <RFC3339>|--clear-due-at] [--require-integration]",
+        usage: "yui task update <id> [--title <text>] [--description <text>|--clear-description] [--priority <low|medium|high|urgent>|--clear-priority] [--tags <comma-separated>|--clear-tags] [--due-at <RFC3339>|--clear-due-at] [--delivery <direct|integrated>] [--require-integration]",
         options: [
             "--title", "--description", "--priority", "--tags", "--due-at",
             "--clear-description", "--clear-priority", "--clear-tags", "--clear-due-at",
-            "--require-integration"
+            "--delivery", "--require-integration"
         ],
-        optionValues: { "--priority": ["low", "medium", "high", "urgent"] }
+        optionValues: {
+            "--priority": ["low", "medium", "high", "urgent"],
+            "--delivery": ["direct", "integrated"]
+        }
     },
     { name: "activate", summary: "Activate a Draft Task.", usage: "yui task activate <id>" },
     {
         name: "complete",
         summary: "Complete an active Task and stop automatic wakeups.",
-        usage: "yui task complete <id> (--summary <text>|--summary-file <path|->) [--refresh-remote]",
-        options: ["--summary", "--summary-file", "--refresh-remote"],
+        usage: "yui task complete <id> (--summary <text>|--summary-file <path|->) [--refresh-remote] [--accept-published-tree <publication-id>]",
+        options: ["--summary", "--summary-file", "--refresh-remote", "--accept-published-tree"],
         fileOptions: ["--summary-file"]
     },
     {
@@ -727,8 +731,8 @@ const taskChildren = [
                     {
                         name: "expand",
                         summary: "Expand one authorized Run context reference.",
-                        usage: "yui task run context expand <task>/<run> <ref-id> [--mode full]",
-                        options: ["--mode"]
+                        usage: "yui task run context expand <task>/<run> <ref-id> [--store <store>] [--mode full]",
+                        options: ["--store", "--mode"]
                     },
                     {
                         name: "delta",
@@ -751,7 +755,7 @@ const taskChildren = [
     {
         name: "review",
         summary: "Control Task-final ReviewRounds.",
-        sections: [{ id: "manage", title: "Commands", entries: ["request", "group", "retry", "finding"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["request", "rebind", "force-fresh", "group", "retry", "finding"] }],
         children: [
             {
                 name: "request",
@@ -759,6 +763,17 @@ const taskChildren = [
                 usage: "yui task review request <task> --role <global-role> [--strategy fixed:<count>|adaptive:<max>] [--lane-role <role> ...] [--delta-recheck]",
                 options: ["--role", "--strategy", "--lane-role", "--delta-recheck"]
             },
+            {
+                name: "rebind",
+                summary: "Explicitly rebind a frozen Task-final contract after a verified immutable release handover.",
+                usage: "yui task review rebind <task> --from-control <digest> --to-control <digest> --from-release <release-id> --to-release <release-id>",
+                options: ["--from-control", "--to-control", "--from-release", "--to-release"]
+            },
+            {
+                name: "force-fresh",
+                summary: "Replace one exact terminal non-semantic Task-final Review with a distinct full Round.",
+                usage: "yui task review force-fresh <task>/<review-round>"
+            },
             {
                 name: "group",
                 summary: "Resolve a Reviewer ExecutionGroup after its Lanes finish.",
@@ -799,9 +814,10 @@ const taskChildren = [
                     },
                     {
                         name: "repair-wave",
-                        summary: "Group open P1/P2 findings into parallel repair groups by overlap.",
-                        usage: "yui task review finding repair-wave <task> [--create]",
-                        options: ["--create"]
+                        summary: "Consolidate open P1/P2 findings, or explicitly plan parallel repair groups.",
+                        usage: "yui task review finding repair-wave <task> [--strategy <consolidated|parallel>] [--create]",
+                        options: ["--strategy", "--create"],
+                        optionValues: { "--strategy": ["consolidated", "parallel"] }
                     },
                     {
                         name: "extract",
@@ -1180,10 +1196,11 @@ export const ROOT_COMMAND = buildNode({
             sections: [{
                     id: "workflow",
                     title: "Commands",
-                    entries: ["enter", "new", "list", "resume", "submit"]
+                    entries: ["enter", "status", "new", "list", "resume", "submit"]
                 }],
             children: [
                 { name: "enter", summary: "Enter the Operator's native session." },
+                { name: "status", summary: "Show the unique active writer and retained conversation history." },
                 {
                     name: "new",
                     summary: "Start a new Operator session.",

package/dist/cli/operatorWizard.js

@@ -28,30 +28,20 @@ export async function resolveOperatorWizardArguments(commandArgs, role, sessions
             : { kind: "resolved", args: [...args, "--agent", selected] };
     }
     if (args[1] === "resume" && args.length === 2) {
-        const newSession = "__operator_new_session__";
-        const selected = await choose("Resume an Operator session", [
-            ...sessions.map((session) => ({
-                value: session.ref,
-                cells: [
-                    formatRelativeTimestamp(session.updatedAt, now),
-                    adapterLabel(session.adapterId),
-                    session.displayTitle,
-                    session.state
-                ]
-            })),
-            {
-                value: newSession,
-                cells: ["", "", "Start a new session", "new"]
-            }
-        ], [
+        const selected = await choose("Resume an Operator session", sessions.map((session) => ({
+            value: session.ref,
+            cells: [
+                formatRelativeTimestamp(session.updatedAt, now),
+                adapterLabel(session.adapterId),
+                session.displayTitle,
+                session.state
+            ]
+        })), [
             { header: "Updated", minWidth: 7, maxWidth: 12 },
             { header: "Agent", minWidth: 6, maxWidth: 12 },
             { header: "Conversation", minWidth: 20, maxWidth: 64 },
             { header: "State", minWidth: 7, maxWidth: 10 }
-        ], io, sessions[0]?.ref ?? newSession, "session");
-        if (selected === newSession) {
-            return resolveOperatorWizardArguments(["operator", "new"], role, sessions, io, now);
-        }
+        ], io, sessions[0]?.ref, "session");
         return selected === undefined
             ? { kind: "cancelled", args }
             : { kind: "resolved", args: [...args, selected] };