From a4faeb549efd105cfefd024b3edd8aa5d7d76a54 Mon Sep 17 00:00:00 2001 From: huangruiteng <14976749+huangruiteng@users.noreply.github.com> Date: Thu, 17 Sep 2026 01:59:31 +0800 Subject: [PATCH] docs(steward): add the product-side steward journey case The steward lane had a reproducible frontend journey but no product-side guidance: an owner had no case explaining what the workspace proves today and which beats it does not. Add `docs/product/use-cases/steward/` (English canonical plus a zh-CN mirror) and list it from the use-case index. The case walks the same seven beats as the browser scenario, states which are proven (first screen, asking the steward, reading the plan card, confirming) and which are recorded gaps, and gives six operating patterns derived from those facts instead of from optimism. Every claim points at the scenario and its report; the gaps table names the probing evidence and the owning surface (plan commit, readiness, alignment, recovery, return delivery). The case explicitly does not qualify a live steward turn, Lark audiences or cloud workers. Validation: `docs-governance-smoke.py` ok, `docs-asset-integrity-smoke.py` ok, private-marker scan clean. Signed-off-by: huangruiteng <14976749+huangruiteng@users.noreply.github.com> --- docs/product/use-cases/README.md | 1 + docs/product/use-cases/steward/README.md | 90 +++++++++++++++++++ .../product/use-cases/steward/README.zh-CN.md | 66 ++++++++++++++ 3 files changed, 157 insertions(+) create mode 100644 docs/product/use-cases/steward/README.md create mode 100644 docs/product/use-cases/steward/README.zh-CN.md diff --git a/docs/product/use-cases/README.md b/docs/product/use-cases/README.md index 2a1760055..31616fa14 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 000000000..9242f29a5 --- /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 000000000..67cc7416b --- /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 已被产品验收”。