@zq-silk/yui 0.15.7 → 0.15.8

package/dist/workItem/workItem.js

@@ -5,8 +5,7 @@ import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 import { assertWorkItemExecutionGroupTransition, validateWorkItemExecutionGroup as validateExecutionGroupRecord, workItemExecutionGroupSettled } from "../execution/workItemExecution.js";
 const TERMINAL_STATUSES = [
-    "completed",
-    "failed",
+    "accepted",
     "retired"
 ];
 export function createWorkItem(id, taskId, input, now) {
@@ -31,21 +30,18 @@ export function createWorkItem(id, taskId, input, now) {
         ...(input.assignee === undefined
             ? {}
             : { assignee: requireIdentity(input.assignee, "Work item assignee") }),
-        status: "pending",
+        status: "open",
         candidates: [],
         createdAt: timestamp,
         updatedAt: timestamp
     });
 }
-/** Replace the mutable definition of an execution-free Draft WorkItem. */
-export function editDraftWorkItemDefinition(workItem, update, now) {
+/** Edit current open-work requirements; frozen Assignments are separate records.
+ * The command boundary owns Task authority and workspace/assignee constraints. */
+export function editWorkItemDefinition(workItem, update, now) {
     validateWorkItem(workItem);
-    if (workItem.status !== "pending"
-        || workItem.executionGroups.length > 0
-        || workItem.candidates.length > 0
-        || workItem.disposition !== undefined
-        || workItem.workspaceDisposition !== undefined) {
-        throw new Error(`Work Item has execution or retirement facts: ${workItem.id}.`);
+    if (workItem.status !== "open") {
+        throw new Error(`Only open Work Item definitions may change: ${workItem.id} (${workItem.status}).`);
     }
     const next = {
         ...workItem,
@@ -87,7 +83,7 @@ export function editDraftWorkItemDefinition(workItem, update, now) {
 }
 export function submitWorkItemCandidate(workItem, input, now) {
     validateWorkItem(workItem);
-    if (workItem.status !== "running") {
+    if (workItem.status !== "open") {
         throw new Error(`Work Item candidate can only be submitted from running: ${workItem.id}/${workItem.status}.`);
     }
     const revision = workItem.revision + 1;
@@ -116,26 +112,28 @@ export function submitWorkItemCandidate(workItem, input, now) {
         ...(input.taskMainSnapshot === undefined
             ? {}
             : { taskMainSnapshot: input.taskMainSnapshot }),
+        ...(input.artifactRefs === undefined ? {} : { artifactRefs: input.artifactRefs.map((ref) => ({ ...ref })) }),
         createdAt: now.toISOString()
     });
     const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
     return validateWorkItem({
         ...base,
-        status: "awaiting_acceptance",
+        status: "open",
         candidates: [...workItem.candidates, candidate],
+        currentCandidateId: candidate.id,
         revision,
         updatedAt: now.toISOString()
     });
 }
-export function updateWorkItemStatus(workItem, status, now, outcome) {
+export function updateWorkItemStatus(workItem, status, now, outcome, candidateId) {
     validateWorkItem(workItem);
     validateStatus(status);
     const alreadyTerminal = isTerminalStatus(workItem.status);
     if (workItem.disposition !== undefined && status !== workItem.status) {
         throw new Error(`Retired Work Item status cannot change: ${workItem.id}.`);
     }
-    const closingFailedWork = workItem.status === "failed" && status === "retired";
-    if (alreadyTerminal && status !== workItem.status && !closingFailedWork) {
+    const withdrawingAcceptance = workItem.status === "accepted" && status === "open";
+    if (alreadyTerminal && status !== workItem.status && !withdrawingAcceptance) {
         throw new Error(`Terminal Work Item status cannot change: ${workItem.id}.`);
     }
     const terminal = isTerminalStatus(status);
@@ -154,16 +152,19 @@ export function updateWorkItemStatus(workItem, status, now, outcome) {
             updatedAt: timestamp
         });
     }
-    const { endedAt: _endedAt, outcome: _outcome, workspaceDisposition, ...base } = workItem;
+    const { endedAt: _endedAt, outcome: _outcome, workspaceDisposition, acceptedCandidateId, currentCandidateId, ...base } = workItem;
     return validateWorkItem({
         ...base,
         status,
         revision: workItem.revision + 1,
         ...(normalizedOutcome === undefined ? {} : { outcome: normalizedOutcome }),
         // Isolated workspace cleanup remains durable evidence after retirement.
-        ...(closingFailedWork && workspaceDisposition !== undefined
+        ...(workspaceDisposition !== undefined
             ? { workspaceDisposition }
             : {}),
+        ...(status === "accepted" && (candidateId ?? acceptedCandidateId ?? currentCandidateId) !== undefined
+            ? { acceptedCandidateId: candidateId ?? acceptedCandidateId ?? currentCandidateId } : {}),
+        ...(status === "open" && !withdrawingAcceptance && currentCandidateId !== undefined ? { currentCandidateId } : {}),
         updatedAt: timestamp,
         ...(terminal ? { endedAt: timestamp } : {})
     });
@@ -172,7 +173,7 @@ export function updateWorkItemStatus(workItem, status, now, outcome) {
 export function attachWorkItemExecutionGroup(workItem, executionGroup, now) {
     validateWorkItem(workItem);
     const checked = validateWorkItemExecutionGroup(executionGroup, workItem.taskId, workItem.id);
-    if (workItem.status === "completed" || workItem.status === "failed" || workItem.status === "retired") {
+    if (workItem.status !== "open") {
         throw new Error(`A terminal Work Item cannot attach an ExecutionGroup: ${workItem.id}.`);
     }
     const existing = workItemExecutionGroupById(workItem, checked.id);
@@ -235,11 +236,10 @@ export function retireWorkItem(workItem, input, now) {
         }
         throw new Error(`Work Item already has an explicit disposition: ${workItem.id}.`);
     }
-    if (workItem.status === "completed") {
+    if (workItem.status === "accepted") {
         throw new Error(`Completed Work Item cannot be retired: ${workItem.id}.`);
     }
     if (isTerminalStatus(workItem.status)
-        && workItem.status !== "failed"
         && workItem.status !== "retired") {
         throw new Error(`Terminal Work Item status cannot change: ${workItem.id}.`);
     }
@@ -254,15 +254,15 @@ export function retireWorkItem(workItem, input, now) {
         endedAt: timestamp
     });
 }
-export function retryFailedWorkItem(workItem, now) {
+export function prepareWorkItemDispatch(workItem, now) {
     validateWorkItem(workItem);
-    if (workItem.status !== "failed") {
+    if (workItem.status !== "open") {
         throw new Error(`Work item is not retryable from ${workItem.status}: ${workItem.id}.`);
     }
     if (workItem.workspaceDisposition !== undefined) {
         throw new Error(`Work item workspace is already settled: ${workItem.id}.`);
     }
-    const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
+    const { outcome: _outcome, endedAt: _endedAt, currentCandidateId: _candidate, ...base } = workItem;
     // Keep every historical Group. A settled current Group is cleared only as
     // the current pointer; redispatch appends a fresh immutable Group.
     const current = currentWorkItemExecutionGroup(workItem);
@@ -271,7 +271,7 @@ export function retryFailedWorkItem(workItem, now) {
         : (({ currentExecutionGroupId: _currentExecutionGroupId, ...history }) => history)(base);
     return validateWorkItem({
         ...retryBase,
-        status: "running",
+        status: "open",
         revision: workItem.revision + 1,
         updatedAt: now.toISOString()
     });
@@ -316,7 +316,10 @@ export function validateWorkItem(workItem) {
         "workspaceDisposition",
         "createdAt",
         "updatedAt",
-        "endedAt"
+        "endedAt",
+        "acceptedCandidateId",
+        "currentCandidateId",
+        "historicalState"
     ], "WorkItem");
     if (workItem.schemaVersion !== 15)
         throw new Error("WorkItem must use schemaVersion 15.");
@@ -381,9 +384,27 @@ export function validateWorkItem(workItem) {
             throw new Error("Work Item candidate revision cannot exceed the Work Item revision.");
         }
     });
-    const currentCandidate = currentWorkItemCandidate(workItem);
-    if (workItem.status === "awaiting_acceptance" && currentCandidate === undefined) {
-        throw new Error("A Work Item awaiting acceptance requires a candidate.");
+    if (workItem.acceptedCandidateId !== undefined
+        && !candidateIds.has(workItem.acceptedCandidateId))
+        throw new Error("Accepted Candidate is missing.");
+    if (workItem.acceptedCandidateId !== undefined && workItem.status !== "accepted") {
+        throw new Error("Only an accepted Work Item may select an accepted Candidate.");
+    }
+    if (workItem.status === "accepted" && workItem.candidates.length > 0 && workItem.acceptedCandidateId === undefined) {
+        throw new Error("Accepted Work Item must identify its selected Candidate.");
+    }
+    if (workItem.currentCandidateId !== undefined
+        && !candidateIds.has(workItem.currentCandidateId))
+        throw new Error("Current Candidate is missing.");
+    if (workItem.historicalState !== undefined) {
+        const historical = workItem.historicalState;
+        if (!["pending", "running", "awaiting_acceptance", "completed", "failed", "retired"].includes(historical.status)) {
+            throw new Error("Historical Work Item status is invalid.");
+        }
+        if (historical.outcome !== undefined)
+            requireText(historical.outcome, "Historical outcome");
+        if (historical.endedAt !== undefined)
+            requireTimestamp(historical.endedAt, "Historical endedAt");
     }
     if (workItem.outcome !== undefined)
         requireText(workItem.outcome, "Work item outcome");
@@ -406,9 +427,6 @@ export function validateWorkItem(workItem) {
         if (!["integrated", "abandoned"].includes(workItem.workspaceDisposition)) {
             throw new Error("Work item workspaceDisposition is invalid.");
         }
-        if (!terminal) {
-            throw new Error("Only a terminal Work Item can record workspace cleanup.");
-        }
     }
     if (workItem.disposition !== undefined) {
         validateDisposition(workItem.disposition);
@@ -433,7 +451,7 @@ export function workItemExecutionGroupById(workItem, executionGroupId) {
     return workItem.executionGroups.find(({ id }) => id === executionGroupId);
 }
 /**
- * True when a Turn failure belongs to the WorkItem's current unresolved Lane.
+ * True when a AgentRun failure belongs to the WorkItem's current unresolved Lane.
  * Such a failure is Lane-bounded: the WorkItem remains running so the Leader
  * can reuse completed siblings and retry only this failed attempt.
  */
@@ -445,7 +463,7 @@ export function workItemOwnsUnresolvedExecutionLane(workItem, executionGroupId,
     const group = workItem.executionGroups.find(({ id }) => id === executionGroupId);
     return group !== undefined
         && !workItemExecutionGroupSettled(group)
-        && group.lanes.some(({ id, disposition, currentTurnId }) => (id === executionLaneId && disposition === "open" && currentTurnId !== undefined));
+        && group.lanes.some(({ id, disposition, currentRunId }) => (id === executionLaneId && disposition === "open" && currentRunId !== undefined));
 }
 function validateWorkItemExecutionGroup(group, taskId, workItemId) {
     validateExecutionGroupRecord(group);
@@ -481,17 +499,33 @@ export function validateWorkItemCandidate(candidate) {
         throw new Error("Work Item candidate revision must be a positive integer.");
     }
     requireText(candidate.summary, "Work Item candidate summary");
+    if (candidate.artifactRefs !== undefined) {
+        if (!Array.isArray(candidate.artifactRefs))
+            throw new Error("Candidate Artifact refs must be an array.");
+        const ids = new Set();
+        for (const ref of candidate.artifactRefs) {
+            requireIdentity(ref.artifactId, "Candidate Artifact id");
+            if (ref.taskId !== candidate.taskId || !["content", "external-version", "receipt"].includes(ref.kind)
+                || ids.has(ref.artifactId))
+                throw new Error("Candidate Artifact scope, kind or identity is invalid.");
+            if ((ref.kind !== "external-version" || ref.digest !== undefined)
+                && (typeof ref.digest !== "string" || !/^[a-f0-9]{64}$/u.test(ref.digest))) {
+                throw new Error("Candidate Artifact digest is invalid.");
+            }
+            ids.add(ref.artifactId);
+        }
+    }
     if (typeof candidate.source !== "object" || candidate.source === null) {
         throw new Error("Work Item candidate source is required.");
     }
-    if (candidate.source.type !== "direct" && candidate.source.type !== "turn") {
+    if (candidate.source.type !== "direct" && candidate.source.type !== "run") {
         throw new Error("Work Item candidate source is invalid.");
     }
-    if (candidate.source.type === "turn") {
+    if (candidate.source.type === "run") {
         validateTaskRecordReference({
             taskId: candidate.taskId,
-            localId: candidate.source.turnId
-        }, "turn");
+            localId: candidate.source.runId
+        }, "run");
     }
     if ((candidate.executionGroupId === undefined) !== (candidate.executionLaneId === undefined)) {
         throw new Error("Work Item candidate execution lineage is incomplete.");
@@ -647,8 +681,8 @@ function requireCommit(value, label) {
     return commit;
 }
 export function currentWorkItemCandidate(workItem) {
-    return workItem.status === "awaiting_acceptance"
-        ? workItem.candidates.at(-1)
+    return workItem.status === "open"
+        ? workItem.candidates.find(({ id }) => id === workItem.currentCandidateId)
         : undefined;
 }
 /**
@@ -659,9 +693,10 @@ export function currentWorkItemCandidate(workItem) {
  * Candidates on the same WorkItem are superseded by its latest Candidate.
  */
 export function governingWorkItemCandidate(workItem) {
-    return workItem.status === "awaiting_acceptance" || workItem.status === "completed"
-        ? workItem.candidates.at(-1)
-        : undefined;
+    if (workItem.status === "accepted" && workItem.acceptedCandidateId !== undefined) {
+        return workItem.candidates.find(({ id }) => id === workItem.acceptedCandidateId);
+    }
+    return currentWorkItemCandidate(workItem);
 }
 export function updateWorkItemWriteProjects(workItem, writeProjectIds, now) {
     validateWorkItem(workItem);
@@ -690,11 +725,8 @@ function isTerminalStatus(status) {
 }
 function validateStatus(status) {
     if (![
-        "pending",
-        "running",
-        "awaiting_acceptance",
-        "completed",
-        "failed",
+        "open",
+        "accepted",
         "retired"
     ].includes(status)) {
         throw new Error(`Work Item status is invalid: ${String(status)}.`);

package/dist/workspace/workItemChangeSetManager.js

@@ -8,9 +8,8 @@ import { governingWorkItemCandidate } from "../workItem/workItem.js";
 import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
 import { captureManagedGitChanges } from "./gitChangeSetCapture.js";
 const CAPTURABLE_WORK_ITEM_STATUSES = new Set([
-    "awaiting_acceptance",
-    "completed",
-    "failed",
+    "open",
+    "accepted",
     "retired"
 ]);
 export class WorkItemChangeSetManager {
@@ -44,10 +43,15 @@ export class WorkItemChangeSetManager {
         }
         return captured;
     }
-    async assertIntegrated(taskId, workItemId) {
+    async assertIntegrated(taskId, workItemId, candidateId) {
         const item = this.store.getWorkItem(taskId, workItemId);
         if (item === null)
             throw new Error(`Work item not found: ${taskId}/${workItemId}.`);
+        const candidate = candidateId === undefined ? governingWorkItemCandidate(item)
+            : item.candidates.find(({ id }) => id === candidateId);
+        if (candidateId !== undefined && candidate === undefined) {
+            throw new Error(`Candidate not found: ${taskId}/${workItemId}/${candidateId}.`);
+        }
         const workspace = this.store.getWorkItemWorkspace(item.taskId, item.id);
         if (workspace === null
             || workspace.owner.type !== "work-item"
@@ -59,14 +63,17 @@ export class WorkItemChangeSetManager {
             if (!await git.isClean(entry.path)) {
                 throw new Error(`WorkItem Project workspace is not clean: ${item.id}/${entry.projectId}.`);
             }
-            const headCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
-            const candidate = governingWorkItemCandidate(item);
+            const workspaceHeadCommit = (await git.inspect(entry.path, "HEAD")).baseCommit;
             const resultCommit = candidate?.gitSnapshot?.projects.find(({ projectId }) => projectId === entry.projectId)?.commit;
             if (candidate?.workspace === undefined
                 || !isDeepStrictEqual(candidate.workspace, workspace)
-                || resultCommit !== headCommit) {
+                || resultCommit === undefined
+                || (candidateId === undefined && resultCommit !== workspaceHeadCommit)) {
                 throw new Error(`WorkItem Project no longer matches its frozen result: ${item.id}/${entry.projectId}.`);
             }
+            // An explicit historical selection is proved against its immutable
+            // integrated commit, not mislabeled as the workspace's current HEAD.
+            const headCommit = resultCommit;
             const integrated = this.store.listIntegrationAttempts(item.taskId).some((integration) => (integration.status === "committed"
                 && integration.projectId === entry.projectId
                 && integration.source.kind === "work-item"
@@ -282,7 +289,7 @@ function requireCapturableContext(store, taskId, workItemId, taskFinalReviewCont
         if (taskFinalReviewContract === undefined) {
             throw new Error(`Work item has no managed workspace: ${item.id}.`);
         }
-        const candidate = item.candidates.at(-1);
+        const candidate = governingWorkItemCandidate(item);
         if (candidate === undefined
             || !sameTaskFinalReviewContract(candidate.taskFinalReviewContract, taskFinalReviewContract)) {
             throw new Error(`Work item has no matching exact Task-final direct Candidate: ${item.id}.`);
@@ -346,7 +353,7 @@ function assertCaptureStillCurrent(store, expected) {
     const workspace = expected.source === "task-main"
         ? store.getTaskWorkspace(expected.taskId)
         : store.getWorkItemWorkspace(expected.taskId, expected.workItemId);
-    const candidate = item?.candidates.at(-1);
+    const candidate = item === null ? undefined : governingWorkItemCandidate(item);
     if (task?.status !== "active"
         || item === null
         || item.revision !== expected.expectedRevision

package/docs/agent-result-consumption.md

@@ -0,0 +1,94 @@
+# Agent result consumption
+
+Every explicitly dispatched AgentRun produces one durable original result.
+Ordinary notification and native conversation do not implicitly create Runs.
+The next Agent in the ownership chain reads the exact result and decides what
+it means.
+
+## One original result
+
+`AgentRunResult.output` is the Agent-authored report. Core preserves its bytes
+and does not parse, classify or validate semantic content. Markdown, JSON and
+ordinary prose are all legal; omitted headings or an unconvincing conclusion are
+quality evidence, not a runtime failure.
+
+Core separately records Provider identity/status, completion time, diagnostics,
+failure reasons and system-owned workspace evidence. Non-empty output must fit
+the current transport limit and contain no NUL. Missing or untransportable text
+fails the Run without fabricated prose. An arrived report can remain on a failed
+Run when a later Core-owned boundary fails.
+
+One reference Message is saved with the terminal result.
+`task message show <task/message>` and Context inspect expand the same
+`resultRef`. ReviewRound does not hold a second report. Files and durable
+business outputs belong to Artifacts or managed Git results.
+
+## Execution is not acceptance
+
+Run lifecycle is `active / completed / failed`. Provider outcome, input
+acceptance and resource quiescence are separate facts. A completed Run means
+its required Core execution boundaries succeeded, not that its answer is
+correct or the WorkItem accepted.
+
+Writable replicated Lanes require their exact Core-owned workspace evidence.
+A wrong branch, dirty snapshot, mismatched owner or scope fails that boundary
+without replacing an already arrived original report.
+
+Only the Leader decides whether evidence warrants acceptance, further work,
+another review or abandonment. Core never derives findings, votes or repair
+topology from Agent text.
+
+## Direct and replicated execution
+
+Direct WorkItem execution uses one main Run and no ExecutionGroup. Direct
+Review likewise uses one main Reviewer Run.
+
+Replicated execution uses distinct Producer Lanes over one frozen Assignment.
+Each Producer retains its own original result and exact lineage. Leader
+explicitly supplies distinct terminal source Run references to synthesis.
+Sources must belong to the exact Group/Lane and have a result; they may be
+completed or failed. There is no automatic synthesis, vote, minimum successful
+Producer count or requirement to wait for all Lanes before choosing sources.
+
+The synthesis snapshot retains the selected source order and bounded views of
+their original outputs, diagnostics and provenance. It does not copy complete
+transcripts. Only the main synthesis result can supply the WorkItem Candidate
+or authoritative replicated Review result. Producers never enter Integration
+or acceptance directly. Retry targets the failed exact execution; it does not
+silently rerun successful Producers.
+
+## Review
+
+ReviewRound owns frozen Candidate or Task-head identity, workspace provenance,
+execution topology, exact main Reviewer Run, lifecycle and Core diagnostics.
+Its completed state is structural execution evidence, not a “pass” extracted
+from the report.
+
+Candidate review follows its captured review rule. Task-final review can be
+explicitly requested or required by the immutable final-review contract. A
+requested review is evidence, not an automatic new policy requiring review
+after every subsequent change. When current delivery requires a review, it
+must cover the exact governing candidate or heads and completed main Run.
+
+The Reviewer should inspect the complete bounded scope and report material
+findings together. The Leader reads the full report, routes findings to the
+original owner, fixes small Task-main issues directly, and creates a new
+WorkItem only for substantial independent work.
+
+## Leader consumption
+
+Wake windows point to result-bearing events, including a Run created before
+the window but completed inside it. Read the exact source:
+
+```sh
+yui task wake show <task> <wake>
+yui task run show <task/run>
+yui task message show <task/message>
+```
+
+An optional report layout is outcome, changes/findings, verification, uncertainty
+and next action. It is communication guidance, not a machine protocol.
+
+Acceptance and Task completion remain explicit operations with current Git,
+review, scope and resource checks. See [Session and AgentRun](managed-turn-and-session-runtime.md)
+and [Task dependencies](task-dag-semantics.md).

package/docs/agent-runtime-drivers.md

@@ -0,0 +1,91 @@
+# Agent runtime Drivers
+
+AgentEndpoint supplies the common execution boundary. Drivers translate native
+events, errors and supported observation sources into `RuntimeObservation`;
+Controller, Store, CLI and Web consume that shared contract.
+
+## Responsibilities
+
+The connection implementation owns launch, protocol, prompt delivery, resume and
+interrupt. Driver owns native identity extraction, observation capabilities,
+event/error mapping and usage normalization. Core owns authority, exact request
+correlation, durable folding and projections; Agents choose recovery and judge
+semantic progress.
+
+Built-in Driver identities are `openai/codex`, `anthropic/claude-code` and
+`acp/agent-client-protocol`. ACP is a protocol Driver, not a product label.
+Adding an ACP peer does not require another business-state model.
+
+Capabilities must be stated truthfully. Unknown resume, cancellation, activity
+or usage behavior cannot be inferred from a product name.
+
+## Observation path
+
+Native structured facts pass the exact Session/request fence, enter the runtime
+inbox, and fold into durable observations and original results. A separately
+sampled usage source can feed the same canonical contract. Driver cannot choose
+another actor, assign a successor Run, or bypass the fence.
+
+Yui Run identity and Provider native Turn identity are not interchangeable.
+An explicitly dispatched Run retains its accepted native correlation; direct
+native chat is not another implicit Run. Replay is deduplicated by exact fact
+identity, and late events cannot terminalize a successor.
+
+Managed Codex uses App Server events. Claude maps its structured stream and
+supported Hook/source payloads. ACP maps protocol Session updates and prompt
+responses. Terminal text, trust dialogs and prompt glyphs are not lifecycle facts.
+
+## State and error evidence
+
+Persistent Run lifecycle is `active / completed / failed`. Input disposition,
+native waiting/activity, Goal, Session lifecycle and process presence answer
+different questions. UI projections must not present a queued request as proof
+that the Agent is busy, or a live process as acceptance.
+
+Standard Agent errors preserve source, phase, category, code, input disposition,
+Session disposition and the serialized native error. Categories include
+availability, rate-limit, transport, access, invalid-request, context, session,
+runtime, conflict, cancelled and unknown. A mapping reports evidence, not a
+retry policy. Unrecognized errors stay unknown.
+
+Runtime activity and workflow progress use separate evidence. A tool boundary
+may show native activity; a durable accepted result shows semantic progress.
+Tokens, CPU, RSS and pane presence cannot substitute for either acceptance or
+Task completion.
+
+## Usage
+
+Usage is read-only and scoped to the exact native Session. Input/output totals
+are distinguished from cache/reasoning breakdowns, request context and remaining
+capacity. Stable activity IDs deduplicate request snapshots; cumulative deltas
+are used only with valid ordered same-Session evidence.
+
+Missing, partial, mixed or rolled-back observations remain unobserved rather
+than guessed. Incremental observers report health and coverage; sampling does
+not block lifecycle events. Metrics never trigger model selection, wake, retry,
+resource release or acceptance.
+
+## Native children
+
+Native subagents are collaboration inside a parent conversation, not Yui Roles,
+Lanes or independent managed workspace owners. Continuation observations may
+record lineage and result references when the Provider exposes them.
+
+Best-effort child results return through the parent. Only a persisted content
+receipt justifies `durable-result`; a live child or claimed success does not.
+Reported results remain untrusted data. A lost best-effort conversation may
+require redoing the work. Choose a managed WorkItem execution when independent
+durability and acceptance are needed; replication is a separate choice.
+
+## Integration and validation
+
+A new connection implementation must supply truthful control/observation
+capabilities and pair them with exact identity, error and terminal mapping.
+Provider-specific protocol details stay at the edge, not in Task planning,
+Store semantics or Web business rules.
+
+Change-specific disposable evidence should cover the changed correlation,
+permission, cancellation or observation boundary. Keep permanent tests to the
+primary paths in the [verification policy](testing/verification-levels.md).
+Real Provider/model validation requires explicit authorization and must distinguish
+native process evidence from fixture output.

package/docs/architecture/README.md

@@ -0,0 +1,38 @@
+# 当前架构与文档导航
+
+以下文档描述当前源码合同。能力边界不等于所有真实 Provider 场景已经验证。
+
+## 阅读入口
+
+- [README](../../README.md)：安装、配置和日常使用。
+- [中文 README](../../i18n/README.zh-CN.md)：同一产品入口的中文说明。
+- [总体架构](../../ARCHITECTURE.md)：职责、权威和端到端流程。
+- [能力、资源与 Surface](capabilities-and-resources.md)：扩展入口、实例所有权和资源效果。
+
+## 领域合同
+
+| 问题 | 当前文档 |
+| --- | --- |
+| Session、AgentRun、消息和激活如何配合？ | [执行与会话](../managed-turn-and-session-runtime.md) |
+| 谁消费结果、综合与审查？ | [结果消费](../agent-result-consumption.md) |
+| WorkItem 依赖何时满足？ | [Task 依赖](../task-dag-semantics.md) |
+| Task 内记录如何引用？ | [局部身份](../task-local-identity.md) |
+| Role、Profile 与运行配置如何生效？ | [角色与配置](../roles-and-configuration.md) |
+| 怎样交付、集成和归档？ | [交付生命周期](../task-delivery.md) |
+| Provider、ACP 与配置事实如何接入？ | [Provider Runtime](../provider-runtime.md) |
+| 运行观察和错误由谁解释？ | [Agent Drivers](../agent-runtime-drivers.md) |
+| 如何创建、验证与采用插件？ | [插件 SDK](../plugin-sdk.md) |
+| 数据、升级与并发的边界是什么？ | [SQLite Store](../sqlite-control-plane-design.md) |
+| 如何执行获授权的发布操作？ | [发布流程](../release-workflow.md) |
+| 如何查看当前运行证据？ | [可观察性](../observability/README.md) |
+| 哪些验证应长期保留？ | [验证策略](../testing/verification-levels.md) |
+
+## 维护约定
+
+行为变更同步修改所属合同和必要的入口说明。具体 CLI 参数以
+`src/cli/commandCatalog.ts` 和命令处理器为准；公开领域类型以运行源码为准，
+不另外维护一套目标模型或生成的离线副本。
+
+Project Skill 管理 Yui 的开发与验证规则；通用 Role Skills 管理 Agent 使用
+Yui 的职责。仓库文档不替代 `YUI_HOME` 中维护的 Project Knowledge，也不授予
+共享环境、真实模型或外部系统的执行权限。