diff --git a/docs/product/use-cases/README.md b/docs/product/use-cases/README.md index 2a17600555..31616fa14b 100644 --- a/docs/product/use-cases/README.md +++ b/docs/product/use-cases/README.md @@ -7,3 +7,4 @@ They do not grant domain providers core control-plane authority. - [Issue and PR work](issue-pr/README.md) - [Cross-runtime implementation and review](cross-runtime/README.md) - [Office operations](office-operations/README.md) +- [Steward: an owner sentence becomes a confirmed team](steward/README.md) diff --git a/docs/product/use-cases/steward/README.md b/docs/product/use-cases/steward/README.md new file mode 100644 index 0000000000..9242f29a50 --- /dev/null +++ b/docs/product/use-cases/steward/README.md @@ -0,0 +1,90 @@ +# Steward: An Owner Sentence Becomes A Confirmed Team + +Status: qualification case. It records what the local steward journey proves on +the workspace today, which beats are still unproven, and how to reproduce both. +It is product guidance, not a new capability, contract or scheduler. + +The case is grounded in one deterministic browser scenario +(`examples/personal-workspace-browser/steward-journey.mjs`) that runs on synthetic +data. The fixture substitutes the agent turn; everything the case describes is a +fact the workspace surfaces render, not a claim about a live Goal. + +## When This Case Applies + +- an owner wants work to start from one sentence instead of a filled-in form; +- the work needs more than one Agent or more than one lane, so staffing is + itself part of the answer; +- the owner wants to keep confirming, correcting and reading results in one + place instead of relaying between Agent conversations. + +## The Journey + +| Beat | What the owner does | What the workspace shows | State | +| --- | --- | --- | --- | +| 1 | Looks at the first screen | Goal board lanes (needs you / running / observing / scheduled), each Goal card naming its Agent and its next sentence | Proven | +| 2 | Asks the steward in the Goal conversation | The ask becomes an accepted Turn and the admitted team plan card lands in the same conversation | Proven | +| 3 | Reads the card | Per lane: the Agent, the first bounded Todo with priority and action kind, the acceptance signal, and an explicitly unstaffed lane that keeps the work it did not staff; the quota envelope and stop condition; a statement that confirming is what creates the lanes | Proven | +| 4 | Confirms | Exactly one apply and one durable write; the card reports that LoopX state will refresh | Proven, but see gap 2 | +| 5 | Checks who can actually work | — | Gap 3 | +| 6 | Corrects or pauses one lane | — | Gap 4 | +| 7 | Waits for a lane to fail and asks who fixes it / judges completion | — | Gaps 5, 6 | + +Beats 5–7 are recorded by the scenario as typed gaps with the probe that looked +for them. They are not "not implemented here" hand-waving: the scenario names +the selectors and phrases it searched for and what it found instead. + +## Patterns + +1. **Ask for an outcome, not an org chart.** One sentence with the outcome and + the constraint produces a plan card; naming Agents before the outcome turns + coordination into the owner's job. +2. **Read four facts before confirming.** Agent, first bounded Todo, acceptance + signal and staffing gap. A card that cannot show a gap is not yet reviewable. +3. **Treat the gap lane as information, not failure.** An unstaffed lane keeps + the work it could not staff and names the reason, so the owner can decide to + drop it, staff it, or accept partial delivery. +4. **Confirmation is a durable write.** Confirming sends exactly one apply and + performs one durable write; the surface must not claim a lane exists before + that write, and must say what the write produced afterwards. +5. **Judge delivery by the returned result, not by the conversation.** A reply + or a message is not a completed lane. Until gap 6 closes, treat the + conversation as the request channel and the Goal's own state as the truth. +6. **Correct in the conversation the work came from.** Steering an active run is + supported today; correcting a confirmed lane commitment is not yet, so avoid + confirming a plan whose lanes may need to be withdrawn. + +## Reproduce + +```sh +# development surfaces +LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \ + node examples/personal-workspace-browser-smoke.mjs + +# packaged workspace bundle +LOOPX_PERSONAL_WORKSPACE_PACKAGED=1 \ +LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \ + node examples/personal-workspace-browser-smoke.mjs +``` + +The run writes `steward-journey-report.json` (beats, gaps, probe evidence) and +per-beat screenshots under `output/playwright/personal-workspace/`, which is +gitignored. No live Goal, Agent, credential or local path is read or captured. + +## Recorded Gaps And Owners + +| # | Gap | Evidence the scenario recorded | Owner surface | +| --- | --- | --- | --- | +| 1 | The steward's bounded prompt set (`找下一步` / `看阻塞` / `查证据`) is defined in the client model but not reachable from the conversation | probe: no steward-prompt element, no prompt phrases before the owner types | workspace composer | +| 2 | A confirmed plan does not distinguish committed / partial / all-gap / stale / rejected per lane | probe: the only outcome sentence is the generic applied notice | steward plan commit (roadmap R1 remainder) | +| 3 | No per-lane readiness ladder (registered → bound → launchable → executing) | probe: no lane-readiness element or phrase | steward readiness (roadmap R2 / audit F6) | +| 4 | No lane-level correction (pause or supersede a confirmed commitment) | probe: no lane-correction element; only run steering exists | shared alignment (roadmap R4) | +| 5 | A failed lane does not name its blocker owner and next step | probe: no lane-blocker element or phrase | recovery/continuation (roadmap R3) | +| 6 | Completion is not judged by the lane's returned result | probe: no lane-return element or phrase | return delivery (roadmap R3) | + +## What This Case Does Not Claim + +- It does not qualify a live steward conversation: the fixture substitutes the + agent turn, so the model/runtime behind the intake stays untested here. +- It does not qualify Lark audiences or any cloud/remote worker. +- It does not turn a passing smoke into product acceptance for a Goal whose + plan was confirmed with real consequences. diff --git a/docs/product/use-cases/steward/README.zh-CN.md b/docs/product/use-cases/steward/README.zh-CN.md new file mode 100644 index 0000000000..67cc7416b0 --- /dev/null +++ b/docs/product/use-cases/steward/README.zh-CN.md @@ -0,0 +1,66 @@ +# 管家：一句话变成一个被确认的团队 + +状态：qualification 案例。它记录本机管家旅程今天在工作台面上证明了什么、哪几拍还没有证明，以及如何复现两者。它是产品侧使用说明，不是新能力、新契约或新调度器。 + +本文案的事实来源是一个确定性的浏览器场景（`examples/personal-workspace-browser/steward-journey.mjs`），全部跑在合成数据上。fixture 顶替了 agent turn；本文描述的每一句都是工作台面渲染出来的事实，不是对某个真实 Goal 的断言。 + +## 什么情况下适用 + +- 老板想用一句话启动工作，而不是填表； +- 这项工作需要不止一个 Agent 或不止一条 lane，所以“有没有人干”本身就是答案的一部分； +- 老板想在同一个地方确认、纠偏、看结果，而不是在多个 Agent 会话之间来回转发。 + +## 旅程七拍 + +| 拍 | 老板做什么 | 界面显示什么 | 状态 | +| --- | --- | --- | --- | +| 1 | 看首屏 | Goal 看板四条 lane（需要你/执行中/观察中/已安排），每张 Goal 卡给出 Agent 与下一步那句话 | 已证明 | +| 2 | 在 Goal 对话里向管家提要求 | 这句话成为一个被接受的 Turn，被准入的团队计划卡落在同一个对话里 | 已证明 | +| 3 | 阅读计划卡 | 每条 lane 的 Agent、第一刀 Todo（含优先级与 action kind）、验收信号，以及一条明确“未配齐”并保留未派工工作的 lane；配额包络与停止条件；以及“确认才会建 lane”的说明 | 已证明 | +| 4 | 确认 | 恰好一次 apply、一次 durable write；卡片提示 LoopX 状态将刷新 | 已证明，但见缺口 2 | +| 5 | 检查到底谁能干活 | — | 缺口 3 | +| 6 | 暂停或撤销某条 lane | — | 缺口 4 | +| 7 | 等某条 lane 失败，问谁负责修 / 用什么判定完成 | — | 缺口 5、6 | + +第 5–7 拍由场景以 typed gap 记录，并带上“探针找过什么”的证据：不是“这里先不做”的一句话，而是列出了查找的选择器和文本、以及实际找到什么。 + +## 推荐姿势 + +1. **说要结果，不要点将。** 一句话给出结果与约束，让计划卡来回答“谁来做”；先点名 Agent 会把协调变成老板的活。 +2. **确认前先看四件事**：Agent、第一刀 bounded Todo、验收信号、缺人情况。看不到缺口的卡片还不具备可评审性。 +3. **缺人 lane 是信息，不是失败。** 未配齐的 lane 会保留它没能派出去的工作并给出原因，老板可以选择砍掉、补人、或接受部分交付。 +4. **确认是一次落地的 durable 写入。** 确认只发一次 apply、只做一次 durable write；卡片不能在写入前声称 lane 已存在，写入后必须说明产生了什么。 +5. **用回传结果判定交付，不要用对话判定。** 一条回复不等于一条 lane 完成。在缺口 6 关闭前，把对话当请求通道，把 Goal 自身状态当事实。 +6. **在产生工作的那个对话里纠偏。** 对运行中的 Turn 纠偏今天已支持；对已确认 lane 承诺的纠偏还没有，所以不要确认一张可能需要撤回 lane 的计划。 + +## 如何复现 + +```sh +# 开发态台面 +LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \ + node examples/personal-workspace-browser-smoke.mjs + +# 打包态工作台 +LOOPX_PERSONAL_WORKSPACE_PACKAGED=1 \ +LOOPX_PERSONAL_WORKSPACE_SCENARIO=steward-journey \ + node examples/personal-workspace-browser-smoke.mjs +``` + +运行会在 `output/playwright/personal-workspace/`（已 gitignore）下写出 `steward-journey-report.json`（拍子、缺口、探针证据）与每拍截图。不读取、不截取任何真实 Goal、Agent、凭证或本地路径。 + +## 已记录缺口与归属 + +| # | 缺口 | 场景记录的证据 | 归属面 | +| --- | --- | --- | --- | +| 1 | 管家快捷提示（找下一步 / 看阻塞 / 查证据）只定义在客户端模型里，对话里点不到 | 探针：老板输入前既无 steward-prompt 元素，也无提示文本 | 工作台输入区 | +| 2 | 确认后不区分 committed / partial / all-gap / stale / rejected | 探针：只有一条通用的“已应用”提示 | 管家计划落地（roadmap R1 剩余项） | +| 3 | 没有 per-lane readiness 阶梯（registered → bound → launchable → executing） | 探针：无 lane-readiness 元素或文本 | 管家 readiness（roadmap R2 / 审计 F6） | +| 4 | 没有 lane 级纠偏（暂停或撤销已确认承诺） | 探针：无 lane-correction 元素；只有运行中 Turn 的纠偏 | shared alignment（roadmap R4） | +| 5 | lane 失败后不说明阻塞归属与下一步 | 探针：无 lane-blocker 元素或文本 | 恢复与继续（roadmap R3） | +| 6 | 不用 lane 的回传结果判定完成 | 探针：无 lane-return 元素或文本 | 交付回收（roadmap R3） | + +## 本文案不主张什么 + +- 它不资格化真实管家对话：fixture 顶替了 agent turn，因此接入背后的模型/运行时在这里仍未测试； +- 它不资格化飞书受众，也不资格化任何云端/远端 worker； +- 它不把一条通过的 smoke 当成“某个真实确认过的 Goal 已被产品验收”。