@zq-silk/yui 0.8.3 → 0.8.7

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" \
@@ -613,6 +633,21 @@ and `task work retire <task>/<work> --summary "..."` to retire obsolete work,
 optionally naming a replacement. WorkItem and Integration
 worktrees and check logs remain available as evidence until explicit cleanup.
 
+Incorrect historical directives and execution attempts can be removed from
+operational projections without deleting their audit records:
+
+```sh
+yui task message retire <task>/<message> --reason "Superseded instruction"
+yui task run retire <task>/<agent-run> --reason "Invalid launch record"
+```
+
+These commands append a retirement fact. Lists and audit views retain the
+original Message, WorkItem, or AgentRun and mark it retired; managed Run context,
+actionability, recovery, review evidence, and scheduling ignore it. Retiring
+an active AgentRun first terminalizes that exact Run, and retirement is
+idempotent. Only the user or global Operator may retire Messages or AgentRuns;
+WorkItems may also be retired by their Task Leader.
+
 For long-running Tasks, the Leader keeps Yui—not a native transcript—as the
 recovery authority. The Task Brief owns the overall technical approach,
 including how coordinated Project changes fit together. WorkItems own the
@@ -660,9 +695,8 @@ yui task reopen <task-id>
 ```
 
 When a verified squash-merge Publication records a remote commit that is
-ancestry-divergent from the unchanged, frozen Task-final Review head, a user or
-global Operator may explicitly authorize completion against its identical Git
-tree:
+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 \
@@ -671,17 +705,28 @@ yui task complete <task-id> --summary-file delivery.txt \
 
 This does not weaken normal freshness checks. Yui requires the current,
 unsuperseded Publication to be merged and verified, its local commit to equal
-the reviewed physical Task head, its remote commit to be ancestry-divergent,
-and both commits to resolve to the same exact tree. `--refresh-remote` fetches
+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, 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. 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.
+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
@@ -736,9 +781,11 @@ running AgentRun and its native Session continue under their immutable
 effective snapshot even if the Role is edited or switched. Resume is allowed
 only when the complete effective snapshot and workspace remain compatible;
 otherwise Yui starts a new Session after the old process has stopped and keeps
-the terminal Session's immutable effective snapshot in history. Until that
-process terminates, exact control-plane wakes continue through its actual
-snapshot instead of applying desired drift as a hot change.
+the terminal Session's immutable effective snapshot in history. Managed
+Sessions invoke the ordinary `yui` command; their Manifest and durable
+Role/Run fences authenticate scope while protocol and storage compatibility
+allow a CLI package or Controller upgrade in place. Exact internal callbacks
+remain fenced to their originating runtime snapshot.
 
 Use `yui config role unbind <global-role> <agent-id>` or `yui task role unbind <task-id> <role> <agent-id>` to retire a dormant binding. The active binding and any non-stopped native session are rejected; a stopped session record is removed atomically with the binding.
 

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,13 +266,16 @@ 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>" },
     {
@@ -359,7 +363,7 @@ const taskChildren = [
     {
         name: "message",
         summary: "Manage durable Task messages.",
-        sections: [{ id: "manage", title: "Commands", entries: ["send", "list"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["send", "list", "retire"] }],
         children: [
             {
                 name: "send",
@@ -377,6 +381,12 @@ const taskChildren = [
                 summary: "List Task messages.",
                 usage: "yui task message list <id> [--after <timestamp>] [--limit <n>]",
                 options: ["--after", "--limit"]
+            },
+            {
+                name: "retire",
+                summary: "Retire an incorrect historical Task Message without deleting its audit record.",
+                usage: "yui task message retire <task>/<message> --reason <text>",
+                options: ["--reason"]
             }
         ]
     },
@@ -685,7 +695,7 @@ const taskChildren = [
     {
         name: "run",
         summary: "Inspect and control Task Role Agent Runs.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint", "retire"] }],
         children: [
             { name: "list", summary: "List Runs for a work item.", usage: "yui task run list <task>/<work>" },
             {
@@ -745,13 +755,19 @@ const taskChildren = [
                 options: ["--note", "--note-file"],
                 fileOptions: ["--note-file"],
                 hidden: true
+            },
+            {
+                name: "retire",
+                summary: "Retire an incorrect historical Agent Run without deleting its audit record.",
+                usage: "yui task run retire <task>/<run> --reason <text>",
+                options: ["--reason"]
             }
         ]
     },
     {
         name: "review",
         summary: "Control Task-final ReviewRounds.",
-        sections: [{ id: "manage", title: "Commands", entries: ["request", "force-fresh", "group", "retry", "finding"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["request", "rebind", "force-fresh", "group", "retry", "finding"] }],
         children: [
             {
                 name: "request",
@@ -759,9 +775,15 @@ 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 non-semantic failed Task-final Review with a distinct full Round.",
+                summary: "Replace one exact terminal non-semantic Task-final Review with a distinct full Round.",
                 usage: "yui task review force-fresh <task>/<review-round>"
             },
             {
@@ -804,9 +826,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",
@@ -1185,10 +1208,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.",
@@ -1393,7 +1417,7 @@ export const ROOT_COMMAND = buildNode({
             sections: [{
                     id: "callbacks",
                     title: "Callbacks",
-                    entries: ["session-notify", "runtime-hook", "agent-host"]
+                    entries: ["session-notify", "runtime-hook", "agent-host", "session-cli-refresh"]
                 }],
             children: [
                 {
@@ -1410,6 +1434,11 @@ export const ROOT_COMMAND = buildNode({
                     name: "runtime-hook",
                     summary: "Record a managed Agent Driver observation from stdin.",
                     usage: "yui internal runtime-hook"
+                },
+                {
+                    name: "session-cli-refresh",
+                    summary: "Refresh legacy managed Session CLI wrappers after an update.",
+                    usage: "yui internal session-cli-refresh"
                 }
             ]
         }

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] };

package/dist/cli/updatePorts.js

@@ -199,6 +199,12 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                     + `but the staged/verified artifact was ${staged.version}. Refusing to trust a `
                     + "different build than the one that passed preflight.");
             }
+            // Existing managed Sessions may have been created by a release that
+            // embedded an exact CLI path/version in its wrapper. Convert those
+            // authenticated, Manifest-referenced wrappers before the replacement
+            // Controller starts so the update cannot strand a live Session.
+            const sessionCliRefresh = run(activeBinary, ["--json", "internal", "session-cli-refresh"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
+            assertSpawnOk(sessionCliRefresh, "refresh managed Session CLI wrappers");
             // Retain the exact path used by both doctor and version verification. The
             // replacement start must not resolve UPDATE_CLI_PATH or npm again.
             verifiedActivatedBinary = activeBinary;