@zq-silk/yui 0.15.7 → 0.15.9

package/docs/task-local-identity.zh-CN.md

@@ -0,0 +1,58 @@
+<p align="right"><a href="./task-local-identity.md">English</a> | <strong>简体中文</strong></p>
+
+# Task 局部身份
+
+Yui 把 Task 作为持久工作流记录的聚合边界。每个 Task 为下面每一类记录族维护
+一条独立、单调递增的序列：
+
+- WorkItem
+- AgentRun
+- ReviewRound
+- ChangeSet
+- IntegrationAttempt
+- Message
+- InputRequest
+- Decision
+- Milestone
+- Event
+
+序列从 1 开始，因此每个 Task 内某个族的第一条记录本地编号都以 `-1` 结尾
+（例如 `work-item-1`）。删除、取消、完成、重开和归档都不会降低已持久化的
+高水位，所以本地 ID 在同一个 Task 内永不复用。每次分配都在 Store 事务内推进
+该聚合高水位。
+
+Candidate 身份的范围更窄：`candidate-N` 是 WorkItem 内的局部序列。每个
+Candidate 都保存自己的 `taskId` 和 `workItemId`，在有来源 AgentRun 时再附带
+其引用。
+
+## 引用合同
+
+Task 所属引用的可移植形式为：
+
+```text
+<task-id>/<local-id>
+```
+
+例如 `task-7/work-item-1` 和 `task-9/work-item-1` 是不同的。CLI、JSON、mailbox、
+Controller、Hook、回执、Web 以及错误路径都保留 Task 范围。无上下文的命令会
+拒绝裸的本地 ID，而不是在所有 Task 中搜索，即使该 ID 当前恰好唯一。
+
+受管的 Task 会话可以直接用 `work-item-1` 或 `run-1`，因为它的 `YUI_TASK_ID`
+是明确的。已经通过其他参数收到 Task 的命令也可以使用从属的本地 ID。除这两种
+情形外，一律使用限定形式。投递回执沿用同样的来源标注，例如：
+
+```text
+run:task-7/run-1
+input-request:task-7/input-1
+```
+
+不存在兼容查找、跨 Task 猜测或裸 ID 回退。
+
+## 当前 schema 边界
+
+运行时只打开当前 Home 存储版本和当前记录形态，普通工作中既不双读也不推断
+历史记录。历史解码与改写只发生在显式的 `yui upgrade` 边界和 `yui update` 的
+迁移阶段；凡是不低于 CLI 最低支持存储版本的有效 Home 都能直接推进到当前版本。
+
+这条边界让 Task 局部引用、Role 期望配置以及不可变的 AgentRun/RoleSession
+生效快照都处在同一份无歧义的运行时合同下，而只追加的迁移链保留受支持的历史。

package/docs/testing/verification-levels.md

@@ -0,0 +1,88 @@
+<p align="right"><strong>English</strong> | <a href="./verification-levels.zh-CN.md">简体中文</a></p>
+
+# Verification policy
+
+Yui is a single-user local product. Permanent verification protects essential
+happy paths and a few critical, easily changed correctness boundaries. It is
+not a historical catalog of every defect or edge case.
+
+## Local development
+
+Use the smallest evidence needed for the current change. Retain a focused
+regression when all of the following apply:
+
+- Failure would lose durable intent, cross an authority/isolation boundary, or
+  prevent an Agent/Operator from making legitimate progress.
+- The boundary is shared by frequently changed code or has already failed in
+  a realistic execution.
+- The check is deterministic, uses disposable local fixtures, runs in
+  milliseconds, and asserts observable behavior rather than incidental layout.
+- Equivalent coverage is not already present; prefer one coherent scenario
+  over separate cases for each historical symptom.
+
+Keep broad fault matrices, real-model exercises, malformed-data combinations
+and incident-specific scripts temporary. Remove their harnesses after the
+change, preserving useful reports. Real-resource results do not replace fast
+regressions, and fast regressions do not establish real-model behavior.
+
+## Permanent core smoke
+
+`npm test` and `npm run test:core` build the checkout and run one permanent suite:
+
+1. the packaged CLI starts and exposes setup/update/upgrade/Task commands;
+2. one normal SQLite Task and Message survive a reopen;
+3. a supported historical Home migrates through the linear storage chain to current;
+4. the built-in Codex and Claude Drivers are registered;
+5. one independent declarative plugin is created, validated, called and disabled
+   through authenticated ingress, with its selection and validation preserved.
+6. a Task starts from durable Operator input, exposes planning Context and enters
+   delivery with its original intent and captured planning authority preserved.
+7. Session replacement preserves pending original Messages and independent work;
+   old Sessions keep scoped reads but cannot regain write authority;
+8. InputRequests survive Session replacement without a synthetic AgentRun;
+9. late native terminals cannot settle successor input or invent acceptance;
+10. remote Operator startup carries its reserved workspace, Role instructions
+    and scoped CLI identity, while offline diagnostics/recovery remain reachable.
+11. durably queued native results survive Controller outages and replay without
+    poisoning the Host; known terminal inputs do not become active merely by aging;
+12. Task-final review can use its Task-local Reviewer without a global template.
+13. a native error label permits replacement only with latest-Turn terminal
+    evidence and drained background execution; a wrong native account cannot
+    authorize cleanup.
+14. Claude receives its native environment and settings paths without injected
+    authentication helpers, rewritten approval records, or secrets forwarded
+    to unrelated adapters; native authentication selection stays with Claude. Environment refresh
+    removes revoked keys and keeps values out of durable Task/Role records.
+
+Keep the test phase seconds-scale; measure TypeScript build separately. Record
+incremental runtime when adding a critical regression. The seven recovery boundary
+cases initially add about 0.4 seconds of test bodies (about 0.6 seconds standalone,
+including module startup) on the development host. Avoid sleep-based checks or
+mandatory model/daemon launches in the permanent suite.
+
+## Skill and instruction changes
+
+Review the shared Runtime contract and affected Role/Project Skills together.
+Check instruction boundaries with a few relevant scenarios: analysis remains
+read-only, existing mechanisms are reused, Session loss preserves Task intent,
+and execution failure does not prevent authorized supervision. This is a
+bounded review, not a new permanent matrix or permission to use real models.
+
+The package-start check follows local Skill references in the installed tree,
+including cross-Role links. Entry points and their referenced Markdown must
+ship together. File/format checks establish availability, not Agent behavior;
+do not add prose-matching tests or claim model validation from static checks.
+
+## CI and release
+
+`ci.yml` runs the core smoke plus one package-assembly/start check. It does not
+run a second lint pass or a separate broad regression suite. `publish.yml` reuses that
+exact gated commit and adds only tag, artifact, install, and provenance checks
+that are unique to publishing.
+
+Configured Agents acting as developers or reviewers are ordinary execution
+resources. Using a live provider or model as the subject of validation is
+different: paid APIs, shared Homes, production systems, real account quota, and
+other non-disposable external effects are never implied by a request to test or
+validate. They require an explicit user request for the exact resource and
+effect boundary.

package/docs/testing/verification-levels.zh-CN.md

@@ -0,0 +1,69 @@
+<p align="right"><a href="./verification-levels.md">English</a> | <strong>简体中文</strong></p>
+
+# 验证策略
+
+Yui 是一个单用户本地产品。永久验证保护关键的 happy path 和少数几个高影响、易被改动
+的正确性边界。它不是一份把每个缺陷或边界情况都收录在案的历史目录。
+
+## 本地开发
+
+使用当前变更所需的最小证据。仅当以下全部成立时才保留一个聚焦的回归测试：
+
+- 失败会丢失持久意图、越过权限/隔离边界，或阻止 Agent/Operator 取得正当进展。
+- 该边界被频繁改动的代码共享，或已经在一次真实执行中失败过。
+- 该检查是确定性的、使用一次性本地夹具、在毫秒级运行，并断言可观察行为而非附带布局。
+- 尚不存在等价覆盖；优先用一个连贯的场景，而不是为每个历史症状分开建用例。
+
+把宽泛的故障矩阵、真实模型演练、畸形数据组合和针对具体事故的脚本保持为临时的。变更
+完成后移除它们的 harness，并保留有用的报告。真实资源结果不替代快速回归，快速回归也
+不确立真实模型行为。
+
+## 永久 core smoke
+
+`npm test` 和 `npm run test:core` 构建 checkout 并运行一个永久套件：
+
+1. 打包后的 CLI 能启动，并暴露 setup/update/upgrade/Task 命令；
+2. 一个普通的 SQLite Task 和 Message 能在重开后存活；
+3. 一个受支持的历史 Home 沿线性存储链迁移到当前版本；
+4. 内置的 Codex 与 Claude Driver 已注册；
+5. 一个独立的声明式插件通过认证入口被创建、验证、调用和停用，其选择和验证被保留。
+6. 一个 Task 从持久的 Operator 输入启动，暴露规划 Context，并在原始意图和捕获的
+   planning 权限被保留的情况下进入交付。
+7. Session 替换保留待处理的原始 Message 和独立工作；旧 Session 保留范围受限的读取，
+   但不能重获写权限；
+8. InputRequest 在没有合成 AgentRun 的情况下经受 Session 替换；
+9. 迟到的原生终态不能结算后继输入或编造接受；
+10. 远程 Operator 启动携带其保留工作区、Role 指令和范围受限的 CLI 身份，同时离线
+    诊断/恢复仍可达。
+11. 持久排队的原生结果经受 Controller 中断并重放，而不毒化 Host；已知的终态输入不会
+    仅因时间变老就变为活动；
+12. Task-final 审查能在没有全局模板的情况下使用其 Task 局部 Reviewer。
+13. 一个原生错误标签只有在具备最新 Turn 终态证据且后台执行已排空时才允许替换；一个
+    错误的原生账号不能授权清理。
+14. Claude 收到其原生环境和 settings 路径，而没有被注入的认证 helper、被改写的批准
+    记录，也没有把 secret 转发给无关适配器；原生认证选择仍归 Claude。环境刷新移除
+    已撤销的 key，并把值挡在持久 Task/Role 记录之外。
+
+把测试阶段保持在秒级；单独度量 TypeScript 构建。新增一个关键回归时记录其增量运行
+时长。这七个恢复边界用例在开发主机上最初约增加 0.4 秒的测试体（独立运行约 0.6 秒，
+含模块启动）。避免在永久套件中使用基于 sleep 的检查或强制的模型/daemon 启动。
+
+## Skill 与指令变更
+
+一并审阅共享的 Runtime 合同和受影响的 Role/Project Skill。用几个相关场景检查指令
+边界：分析保持只读、复用既有机制、Session 丢失保留 Task 意图，以及执行失败不阻止获
+授权的监督。这是一次有界审阅，而不是一套新的永久矩阵，也不是使用真实模型的许可。
+
+package-start 检查跟随已安装树中的本地 Skill 引用，包括跨 Role 链接。入口点及其引用
+的 Markdown 必须一起发布。文件/格式检查确立可用性，而不是 Agent 行为；不要添加基于
+散文匹配的测试，也不要从静态检查中宣称模型验证。
+
+## CI 与发布
+
+`ci.yml` 运行 core smoke 加一个包装配/启动检查。它不运行第二遍 lint，也不运行单独的
+宽泛回归套件。`publish.yml` 复用那个确切的、已过门的提交，只增加发布独有的 tag、
+产物、安装和 provenance 检查。
+
+作为开发者或审查者的已配置 Agent 是普通执行资源。把一个真实 provider 或模型作为验证
+对象则不同：付费 API、共享 Home、生产系统、真实账号额度以及其他不可丢弃的外部效果，
+绝不由一个测试或验证请求隐含。它们需要用户就确切的资源和效果边界提出显式请求。