@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/docs/vendor/dot-codex/specs/viewport-safe-browser-evidence/SPEC.md

@@ -0,0 +1,168 @@
+# Viewport-safe browser evidence capture
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前 Storybook / 浏览器证据链已经要求 mock-first、元素优先与稳定来源，但没有把“指定 viewport 的截图必须怎样达成”钉成硬规则。
+- 这留下了执行歧义：agent 很容易退化成“打开 Storybook canvas 页面、调整浏览器窗口尺寸、再截 browser viewport”，导致浏览器会话被持续改窗，和视觉证据本身混在一起。
+- 如果不收紧这条契约，后续 `ui_demo`、`storybook_canvas`、`storybook_docs` 与 `mock_ui` 仍可能重复走同样的坏路径，既影响主人复查，也让截图元数据缺少一致真相源。
+
+## 目标 / 非目标
+
+### Goals
+
+- 统一 `ui_demo`、`storybook_canvas`、`storybook_docs` 与 `mock_ui` 的 viewport-safe 截图契约：默认不依赖浏览器窗口 resize 来满足目标尺寸。
+- 明确浏览器证据的优先级：来源自带 viewport / `emulate.viewport` / 元素级截图优先，`browser-resize-fallback` 仅保留为末级兜底。
+- 为相关 skills 增加统一的 `requested_viewport` 与 `viewport_strategy` 元数据约定，便于后续 audit 与复盘。
+- 让 `storybook-stories` 在响应式验收场景下提供稳定的 Storybook 入口，而不是把 viewport 控制责任推迟给截图阶段。
+- 为未声明尺寸的移动端验收提供确定的 `393x852` CSS px 默认 viewport，同时保留主人、项目、spec 与来源 surface 的显式覆盖能力。
+
+### Non-goals
+
+- 不修改 `chrome-devtools-mcp`、Storybook upstream、或任何业务仓库中的具体 story/config 实现。
+- 不扩展到真实应用窗口截图（`target_app_window`）或固件显示类证据源。
+- 不引入新的截图后端、视觉回归平台或外部依赖。
+
+## 范围（Scope）
+
+### In scope
+
+- `docs/specs/README.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `skills/storybook-stories/SKILL.md`
+- `AGENTS.md`
+- `skills/storybook-screenshots/agents/openai.yaml`
+- `skills/ui-visual-evidence/agents/openai.yaml`
+- `skills/storybook-stories/agents/openai.yaml`
+- `skills/README.md`
+
+### Out of scope
+
+- `AGENTS.md` 顶层提示词
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md` 与其他非本轮直接使用的 flow / review skills
+- 任何 repo 外截图脚本或浏览器自动化实现
+
+## 需求（Requirements）
+
+### MUST
+
+- `storybook_canvas` 与 `storybook_docs` 的特定 viewport 证据必须优先来自 Storybook 自身可控 surface，而不是浏览器窗口 resize。
+- `ui_demo` 的特定 viewport 证据必须优先来自 demo 自身可控场景，并记录 `viewport_strategy=ui-demo-source`；若 demo 没有 source-managed viewport，则使用 `devtools-emulate`，并继续优先元素级截图。
+- `mock_ui` 的特定 viewport 证据必须优先由负责该证据源的 current-truth skill 提供稳定 viewport 控制，并继续优先元素级截图。
+- 浏览器证据统一记录 `requested_viewport=<name|WxH|none>` 与 `viewport_strategy=<ui-demo-source|storybook-viewport|devtools-emulate|browser-resize-fallback>`。
+- `capture_scope=browser-viewport` 只能在“整个浏览器渲染区域本身就是证据目标”时使用，不能替代元素级截图成为默认路径。
+- `browser-resize-fallback` 只能在来源自带 viewport 与 `devtools-emulate` 都无法满足时使用，并且必须记录原因、恢复原始窗口尺寸；恢复失败时不得把该会话当作最终 owner-facing 浏览器状态。
+- `storybook-stories` 必须要求：若验收依赖 mobile/tablet/desktop 等响应式尺寸，稳定 Storybook 入口本身就要绑定对应 viewport 或等价响应式场景，而不是把这件事留给后续截图动作。
+- 移动端证据在主人、项目、spec、Storybook story 与 demo scenario 都未声明 viewport 时，必须使用 `393x852` CSS px，并记录 `requested_viewport=393x852`；任何显式 viewport 都优先于该默认值。
+- `393x852` 只定义响应式验收的 CSS viewport，不代表设备物理像素，也不要求模拟特定 User-Agent。
+- 默认值生效时，必须先通过来源自带 viewport 或来源适用的 emulation 路径将实际渲染 surface 绑定到 `393x852` CSS px 并验证，再记录 `requested_viewport=393x852`；禁止只写元数据而保持任意渲染尺寸。
+- Storybook 证据不得用截图阶段的临时 emulation 代替稳定 story/docs viewport；默认值必须落在可复现的 Storybook surface 上，无法绑定时回到 Storybook coverage 或报告阻断。
+
+### SHOULD
+
+- skills 索引与 agent metadata 文案应同步强调 viewport-safe、element-first 的默认路径。
+- 文本示例应明确 `ui_demo` source-managed 场景优先 `ui-demo-source`，Storybook 场景优先 `storybook-viewport`，普通浏览器页面优先 `devtools-emulate`。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 解析移动端验收 viewport 时：
+  - 优先使用主人显式尺寸，其次使用项目、spec 或来源 surface 已绑定的尺寸。
+  - 所有显式来源均缺失时，使用 `393x852` CSS px。
+  - 默认值生效时先应用并验证实际渲染 viewport，再写入 `requested_viewport=393x852`，并按所选证据源记录 `viewport_strategy`。
+
+- Storybook canvas/docs 取证时：
+  - 若截图依赖特定 viewport，先选择或建立已绑定目标 viewport 的 Storybook surface。
+  - 然后对实际渲染内容做元素级截图；只有整个浏览器渲染区域就是证据目标时才允许 `browser-viewport`。
+  - 默认 `viewport_strategy=storybook-viewport`。
+- 普通浏览器 `mock_ui` 取证时：
+  - 若截图依赖特定 viewport，先使用显式 `chrome-devtools` 例外路径的 `emulate.viewport` 设定目标尺寸。
+  - 然后优先以页面元素为目标截图；默认 `viewport_strategy=devtools-emulate`。
+- `ui_demo` 取证时：
+  - 若 demo surface 自带稳定 viewport/scenario，优先使用该 source-managed 场景；默认 `viewport_strategy=ui-demo-source`。
+  - 否则按普通浏览器 mock 证据走显式 `chrome-devtools` 例外路径的 `devtools-emulate` + 元素级截图。
+- 对这些浏览器证据：
+  - 只有在默认路径都不可行时，才允许 `browser-resize-fallback`。
+  - 一旦用到 fallback，必须先记录失败原因，再恢复窗口外尺寸，最后才能进入 handoff / 回图语义。
+
+### Edge cases / errors
+
+- 若 Storybook 仓库没有可复用的 viewport 约定，`storybook-stories` 必须要求沿用仓库现有方式建立稳定入口；不得用“先调浏览器大小再截”替代。
+- 若元素级截图无法覆盖目标（例如证据目标确实是整页浏览器渲染区域），允许 `capture_scope=browser-viewport`，但仍不得先把它降级成 resize 驱动。
+- 若 `browser-resize-fallback` 无法恢复原始窗口尺寸，相关 skills 必须报告 blocker，而不是把浏览器留在被改过的尺寸继续对外交付。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| Storybook viewport-safe capture contract | skill | internal | Modify | in-spec | Codex skills | `storybook-screenshots`, review flows | 新增 viewport metadata 与 resize fallback 约束 |
+| Browser viewport-safe capture ladder | skill/policy | internal | Modify | in-spec | Codex skills + AGENTS | `ui_demo`, `mock_ui` evidence flows | `ui_demo` 优先 source-managed demo scenario，`mock_ui` 由 current-truth evidence path 提供稳定 viewport 控制 |
+| Visual evidence source sizing rules | skill | internal | Modify | in-spec | Codex skills | `ui-visual-evidence`, shared workflow | 统一四类浏览器证据的优先级 |
+| Responsive Storybook entry requirement | skill | internal | Modify | in-spec | Codex skills | `storybook-stories`, UI implementation turns | 响应式验收入口前置到 Storybook 覆盖阶段 |
+| Discovery / agent copy for viewport-safe evidence | doc | internal | Modify | in-spec | Codex skills | skills index, agent picker | 文案同步新默认路径 |
+
+### 契约文档（按 Kind 拆分）
+
+- None. 本计划只修改内部 skills / metadata / docs 索引，以上表与对应 `SKILL.md` / metadata 文本即为真相源。
+
+## 验收标准（Acceptance Criteria）
+
+- Given `storybook-screenshots` 需要一张 mobile/tablet/desktop 尺寸下的 Storybook 证据图 When agent 读取该 skill Then 默认路径必须是“Storybook 自带 viewport / 稳定 surface + 元素级截图”，而不是“改浏览器窗口大小再截视口”。
+
+- Given current-truth evidence path 为 `mock_ui` 生成特定 viewport 的浏览器证据 When agent 读取对应技能与策略 Then 默认路径必须优先稳定 viewport 控制，并只在整页本身是证据目标时才使用 `capture_scope=browser-viewport`。
+
+- Given current-truth evidence path 为 `ui_demo` 生成特定 viewport 的浏览器证据 When demo surface 已定义稳定 viewport/scenario Then 默认路径必须优先使用 demo 自身场景；否则才使用 `devtools-emulate`。
+
+- Given `ui-visual-evidence` 为 `ui_demo`、`storybook_docs`、`storybook_canvas` 或 `mock_ui` 选择证据来源 When agent 进入截图步骤 Then 必须沿用统一的 viewport-safe ladder，并把 `browser-resize-fallback` 保持为末级兜底而不是默认方案。
+
+- Given 当前任务要求移动端视觉验收，但主人、项目、spec 与稳定渲染来源均未指定 viewport When `ui-visual-evidence` 解析验收尺寸 Then 必须使用 `393x852` CSS px，并记录 `requested_viewport=393x852`。
+
+- Given `storybook-stories` 面对一个依赖响应式断点验收的 UI 变更 When agent 补 Storybook 覆盖 Then skill 必须要求稳定 Storybook 入口显式承载该 viewport，而不是把 viewport 决策留到截图阶段。
+
+- Given skills index 或 agent picker 文案 When 用户或 agent 查找这些 skills Then 至少能看到 viewport-safe / element-first 的新默认口径，而不是继续暗示 browser resize 是常规手法。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-screenshots`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/ui-visual-evidence`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-stories`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-screenshots`
+- `git diff --check`
+
+### Quality checks
+
+- `rg -n "393x852|requested_viewport|viewport_strategy|ui-demo-source|browser-resize-fallback|devtools-emulate|storybook-viewport|prefer .*element|resize_page" skills docs/specs`
+- 人工 spot-check 4 个主 skill 与相关 metadata / 索引文案的默认路径是否一致。
+
+## 方案概述（Approach, high-level）
+
+- 继续沿用现有 Storybook / browser / visual-evidence 技能边界，只收紧“viewport 如何达成”的默认路径。
+- 把 Storybook 取证与通用浏览器取证分别锚定到各自最稳定的控制面：前者优先 source-managed viewport，后者优先由 current-truth evidence path 提供的稳定 viewport 控制。
+- 把 `ui_demo` 锚定到 demo 自身稳定场景；没有 source-managed 场景时再走通用浏览器 mock 梯度。
+- 保留 `browser-resize-fallback`，但把它从默认做法降级为可审计、可恢复、可阻断的末级例外路径。
+
+## Visual Evidence
+
+本次只修改 Skill、Spec 与索引契约，不改变任何渲染界面，因此视觉证据不适用。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：部分仓库的 Storybook viewport 能力可能较弱，因此 `storybook-stories` 只能要求“稳定入口”而不能强制某一种实现写法。
+- 风险：`393x852` 不能代表所有移动设备；它只在没有显式项目尺寸时提供一致基线，不能覆盖额外的小屏、宽屏或横屏测试需求。
+- 风险：若未来需要把同一套 metadata 暴露到更多 flow/PR 输出，还需要追加联动点；本轮只覆盖直接使用的 source skills 与索引文案。
+- 假设：当前仓库已有的 `chrome-devtools` / Storybook 能力足以支撑默认路径，`browser-resize-fallback` 只会是少数例外。
+
+## 参考（References）
+
+- `docs/specs/storybook-skill-upgrade/SPEC.md`
+- `docs/specs/shared-ui-visual-evidence-gate/SPEC.md`
+- `docs/specs/visual-evidence-whitespace-trim/SPEC.md`
+- Storybook official docs: Viewport essentials, Story / Canvas doc blocks
+- Chrome DevTools MCP source: `take_screenshot`, `take_snapshot`, `includeIframes`

package/toolkit/skills/docs/vendor/dot-codex/specs/visual-evidence-whitespace-trim/HISTORY.md

@@ -0,0 +1,22 @@
+# Visual evidence 外缘空白裁剪规范 演进历史（#vw73w）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `188e114` feat(ui-evidence): trim excessive screenshot whitespace
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- 2026-03-26: 新建 follow-on 规格，锁定 Mock + Storybook 视觉证据的外缘空白裁剪契约。
+- 2026-03-26: 完成共享 helper、技能契约和本地测试/校验。
+- 2026-05-29: 将 `ui_demo` 纳入 mock-first 视觉证据标准化范围，与 `mock_ui`、`storybook_docs`、`storybook_canvas` 使用同一外缘空白裁剪契约。
+- 2026-07-15: 将组件/片段/可复用状态与 `mock_ui` 证据从“保守 trim + fail-open”升级为硬留边门禁，新增 `margin_policy=trim_only|require_margin` 与 `evidence_surface` 双模式语义，并保留 `空白裁剪` 作为兼容状态字段。
+- 组件证据改为源管理展示面：Story 提供 `data-visual-evidence-surface` / `data-visual-evidence-target` 与自然主题留白；截图端只做一次 DOM 预检和 surface 内几何收紧，`require_margin` helper 改为像素分析前阻断。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#vw73w`.

package/toolkit/skills/docs/vendor/dot-codex/specs/visual-evidence-whitespace-trim/IMPLEMENTATION.md

@@ -0,0 +1,63 @@
+# Visual evidence 外缘空白裁剪规范 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 页面保留 trim-only；组件证据改由 Story 源管理展示面与一次 DOM 预检保证自然留白
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-26
+- Legacy last-tracked: 2026-07-15
+- Current lifecycle: active
+- Catalog note: 页面保留 trim-only；组件证据改由 Story 源管理展示面与一次 DOM 预检保证自然留白
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs/visual-evidence-whitespace-trim/SPEC.md` 规格并更新 specs 索引
+- [x] M2: 新增共享外缘空白裁剪 helper
+- [x] M3: 同步 `ui-visual-evidence` 与 `storybook-screenshots` 契约
+- [x] M4: 补充 helper 自测与本地校验
+- [x] M5: 将组件 / `mock_ui` 证据升级为源管理展示面与一次 DOM 预检，禁止截图时补边
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 新增 `docs/specs/visual-evidence-whitespace-trim/SPEC.md` 规格索引
+- `docs/specs/visual-evidence-whitespace-trim/SPEC.md`: 固化源管理展示面、一次 DOM 预检、页面 trim-only 与组件 hard-block 契约
+- `skills/ui-visual-evidence/SKILL.md`: 明确组件展示面、量化留白、无 DOM mutation 与 `视觉证据=不存在` 阻断语义
+- `skills/storybook-stories/SKILL.md`: 让选定组件证据的 Story 提供展示面，不将其误作 coverage 或 `play` 要求
+- `skills/storybook-screenshots/SKILL.md`: 捕获前读取一次 DOM，仅在展示面内按几何收紧多余空白
+- `skills/ui-visual-evidence/scripts/trim_whitespace.py`: 保留 trim-only 页面路径；兼容 require-margin 参数但在像素分析前 hard-block
+- `skills/ui-visual-evidence/scripts/test_trim_whitespace.py`: 覆盖页面 trim-only 与 require-margin 无像素分析、无裁切、无补边回归
+
+### Plan assets
+
+- Directory: `docs/specs/visual-evidence-whitespace-trim/assets/`
+- In-plan references: None
+- Visual evidence source: not used for this skill/script change
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `188e114` feat(ui-evidence): trim excessive screenshot whitespace
+- `b39a914` docs(specs): adopt topic-level spec model
+- Current policy update: include `ui_demo` in visual evidence trimming contract
+- Current policy update: component / `mock_ui` evidence use source-managed surfaces instead of pixel inference or synthetic padding
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/visual-evidence-whitespace-trim/SPEC.md

@@ -0,0 +1,76 @@
+# Visual evidence 外缘空白与组件展示面规范
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Context and Scope
+
+组件证据的留白属于 Story 的展示语义，而不是截图文件的像素属性。截图时从像素推断背景并补边，无法判断颜色是否属于真实主题，容易制造多余边框、重复留白或嵌套卡片观感。本主题规定组件证据的源管理展示面、一次性 DOM 预检和页面级 trim-only fallback。
+
+### In scope
+
+- `$ui-visual-evidence` 与 `$storybook-screenshots` 的组件证据捕获合同。
+- `$storybook-stories` 对被选为组件证据的 Story/docs 展示面要求。
+- `skills/ui-visual-evidence/scripts/trim_whitespace.py` 的页面裁切与兼容阻断行为。
+
+### Out of scope
+
+- 业务仓库的组件样式、Story 组织、页面布局和历史证据图片。
+- `firmware_preview`、`target_app_window` 或新的截图后端。
+- 业务仓库 CI、`play`、测试配置、持久化测量回执和 owner-facing 测量字段。
+
+## Requirements
+
+### REQ-VISUAL-SURFACE-001
+
+选作组件、片段、可复用状态或 `mock_ui` 证据的 DOM 源 MUST 提供外层 `[data-visual-evidence-surface]` 与其内的 `[data-visual-evidence-target]`。target MUST 包含全部可见组件效果，surface MUST 拥有目标的自然外边距。
+
+### REQ-VISUAL-SURFACE-002
+
+展示面 MUST 使用当前 Story 主题自有的不透明、均匀、纯色背景，且 MUST NOT 新增边框、圆角、阴影、渐变、图片背景、证据专用颜色、画框边界或嵌套卡片。已有合理留白时 MUST NOT 额外补留白。
+
+### REQ-VISUAL-SURFACE-003
+
+组件捕获 MUST 在截图前只做一次 DOM 预检，读取已声明 selectors、target/surface 矩形、containment、overflow 与 computed styles。预检 MUST 量化 `required_margin=clamp(round(long_edge * 0.02), 16, 48)`，并确认四边 target-to-surface 间距均在 `[required_margin, 48]`。
+
+### REQ-VISUAL-SURFACE-004
+
+当任一边超过 `48px` 时，捕获 MAY 仅在声明的 surface 内按已知 DOM 几何收紧该边至 `48px`；不得使用像素分析裁切。流程 MUST NOT 注入 DOM、改写样式、合成补边、推断背景或保存测量回执。
+
+### REQ-VISUAL-SURFACE-005
+
+缺少 selector、surface 透明或非自然背景、存在画框样式、target 越界、任一边小于 `required_margin` 或无法证明自然主题 surface 时，组件捕获 MUST 阻断并回到 `$storybook-stories`。阻断报告 MUST 使用 `视觉证据=不存在`、`空白裁剪=不适用` 并包含实测原因；合规且未收紧时使用 `空白裁剪=无需裁剪`，收紧时使用 `空白裁剪=已裁剪`。
+
+### REQ-VISUAL-SURFACE-006
+
+页面或完整页面 Storybook fallback MUST 保留 `trim_only`：仅检测边缘连通的统一背景并裁切多余外缘，保留可用的目标留白。`trim_whitespace.py --margin-policy=require_margin` MUST 保留 CLI 参数兼容，但 MUST 在任何像素分析前返回 `action=blocked` 与 `reason=source_managed_surface_required`，不得裁切、补边或合成组件图。
+
+## Verification
+
+### VER-VISUAL-SURFACE-001
+
+- Method: inspect `$storybook-stories`, `$storybook-screenshots`, and `$ui-visual-evidence` contracts plus `skills_index_check.py`.
+- covers: REQ-VISUAL-SURFACE-001, REQ-VISUAL-SURFACE-002, REQ-VISUAL-SURFACE-003, REQ-VISUAL-SURFACE-004, REQ-VISUAL-SURFACE-005
+- Pass condition: selectors, opaque natural surface, formula, `[required_margin,48]` range, one-preflight boundary, no-mutation rules, and block/report states are explicit.
+
+### VER-VISUAL-SURFACE-002
+
+- Method: `python3 skills/ui-visual-evidence/scripts/test_trim_whitespace.py`.
+- covers: REQ-VISUAL-SURFACE-006
+- Pass condition: trim-only crop/no-op/internal whitespace regressions pass; `require_margin` blocks before pixel analysis, never crops or pads, and preserves the input bytes.
+
+### VER-VISUAL-SURFACE-003
+
+- Method: `python3 bin/spec_contract_check.py --path docs/specs/visual-evidence-whitespace-trim/SPEC.md` and the compatibility-copy comparison.
+- covers: REQ-VISUAL-SURFACE-001, REQ-VISUAL-SURFACE-002, REQ-VISUAL-SURFACE-003, REQ-VISUAL-SURFACE-004, REQ-VISUAL-SURFACE-005, REQ-VISUAL-SURFACE-006
+- Pass condition: canonical structure, normative requirements, verification traceability, ADR membership, and byte-identical stable/legacy Spec copies pass.
+
+## Related ADRs
+
+- [组件证据采用源管理展示面](../../adr/0007-source-managed-component-evidence.md)
+
+## References
+
+- `skills/storybook-stories/SKILL.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `skills/ui-visual-evidence/scripts/trim_whitespace.py`

package/toolkit/skills/docs/vendor/dot-codex/specs/vw73w-visual-evidence-whitespace-trim/HISTORY.md

@@ -0,0 +1,22 @@
+# Visual evidence 外缘空白裁剪规范 演进历史（#vw73w）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `188e114` feat(ui-evidence): trim excessive screenshot whitespace
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- 2026-03-26: 新建 follow-on 规格，锁定 Mock + Storybook 视觉证据的外缘空白裁剪契约。
+- 2026-03-26: 完成共享 helper、技能契约和本地测试/校验。
+- 2026-05-29: 将 `ui_demo` 纳入 mock-first 视觉证据标准化范围，与 `mock_ui`、`storybook_docs`、`storybook_canvas` 使用同一外缘空白裁剪契约。
+- 2026-07-15: 将组件/片段/可复用状态与 `mock_ui` 证据从“保守 trim + fail-open”升级为硬留边门禁，新增 `margin_policy=trim_only|require_margin` 与 `evidence_surface` 双模式语义，并保留 `空白裁剪` 作为兼容状态字段。
+- 组件证据改为源管理展示面：Story 提供 `data-visual-evidence-surface` / `data-visual-evidence-target` 与自然主题留白；截图端只做一次 DOM 预检和 surface 内几何收紧，`require_margin` helper 改为像素分析前阻断。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#vw73w`.

package/toolkit/skills/docs/vendor/dot-codex/specs/vw73w-visual-evidence-whitespace-trim/IMPLEMENTATION.md

@@ -0,0 +1,63 @@
+# Visual evidence 外缘空白裁剪规范 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 页面保留 trim-only；组件证据改由 Story 源管理展示面与一次 DOM 预检保证自然留白
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-26
+- Legacy last-tracked: 2026-07-15
+- Current lifecycle: active
+- Catalog note: 页面保留 trim-only；组件证据改由 Story 源管理展示面与一次 DOM 预检保证自然留白
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs/visual-evidence-whitespace-trim/SPEC.md` 规格并更新 specs 索引
+- [x] M2: 新增共享外缘空白裁剪 helper
+- [x] M3: 同步 `ui-visual-evidence` 与 `storybook-screenshots` 契约
+- [x] M4: 补充 helper 自测与本地校验
+- [x] M5: 将组件 / `mock_ui` 证据升级为源管理展示面与一次 DOM 预检，禁止截图时补边
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 新增 `docs/specs/visual-evidence-whitespace-trim/SPEC.md` 规格索引
+- `docs/specs/visual-evidence-whitespace-trim/SPEC.md`: 固化源管理展示面、一次 DOM 预检、页面 trim-only 与组件 hard-block 契约
+- `skills/ui-visual-evidence/SKILL.md`: 明确组件展示面、量化留白、无 DOM mutation 与 `视觉证据=不存在` 阻断语义
+- `skills/storybook-stories/SKILL.md`: 让选定组件证据的 Story 提供展示面，不将其误作 coverage 或 `play` 要求
+- `skills/storybook-screenshots/SKILL.md`: 捕获前读取一次 DOM，仅在展示面内按几何收紧多余空白
+- `skills/ui-visual-evidence/scripts/trim_whitespace.py`: 保留 trim-only 页面路径；兼容 require-margin 参数但在像素分析前 hard-block
+- `skills/ui-visual-evidence/scripts/test_trim_whitespace.py`: 覆盖页面 trim-only 与 require-margin 无像素分析、无裁切、无补边回归
+
+### Plan assets
+
+- Directory: `docs/specs/visual-evidence-whitespace-trim/assets/`
+- In-plan references: None
+- Visual evidence source: not used for this skill/script change
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `188e114` feat(ui-evidence): trim excessive screenshot whitespace
+- `b39a914` docs(specs): adopt topic-level spec model
+- Current policy update: include `ui_demo` in visual evidence trimming contract
+- Current policy update: component / `mock_ui` evidence use source-managed surfaces instead of pixel inference or synthetic padding
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/vw73w-visual-evidence-whitespace-trim/SPEC.md

@@ -0,0 +1,76 @@
+# Visual evidence 外缘空白与组件展示面规范
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Context and Scope
+
+组件证据的留白属于 Story 的展示语义，而不是截图文件的像素属性。截图时从像素推断背景并补边，无法判断颜色是否属于真实主题，容易制造多余边框、重复留白或嵌套卡片观感。本主题规定组件证据的源管理展示面、一次性 DOM 预检和页面级 trim-only fallback。
+
+### In scope
+
+- `$ui-visual-evidence` 与 `$storybook-screenshots` 的组件证据捕获合同。
+- `$storybook-stories` 对被选为组件证据的 Story/docs 展示面要求。
+- `skills/ui-visual-evidence/scripts/trim_whitespace.py` 的页面裁切与兼容阻断行为。
+
+### Out of scope
+
+- 业务仓库的组件样式、Story 组织、页面布局和历史证据图片。
+- `firmware_preview`、`target_app_window` 或新的截图后端。
+- 业务仓库 CI、`play`、测试配置、持久化测量回执和 owner-facing 测量字段。
+
+## Requirements
+
+### REQ-VISUAL-SURFACE-001
+
+选作组件、片段、可复用状态或 `mock_ui` 证据的 DOM 源 MUST 提供外层 `[data-visual-evidence-surface]` 与其内的 `[data-visual-evidence-target]`。target MUST 包含全部可见组件效果，surface MUST 拥有目标的自然外边距。
+
+### REQ-VISUAL-SURFACE-002
+
+展示面 MUST 使用当前 Story 主题自有的不透明、均匀、纯色背景，且 MUST NOT 新增边框、圆角、阴影、渐变、图片背景、证据专用颜色、画框边界或嵌套卡片。已有合理留白时 MUST NOT 额外补留白。
+
+### REQ-VISUAL-SURFACE-003
+
+组件捕获 MUST 在截图前只做一次 DOM 预检，读取已声明 selectors、target/surface 矩形、containment、overflow 与 computed styles。预检 MUST 量化 `required_margin=clamp(round(long_edge * 0.02), 16, 48)`，并确认四边 target-to-surface 间距均在 `[required_margin, 48]`。
+
+### REQ-VISUAL-SURFACE-004
+
+当任一边超过 `48px` 时，捕获 MAY 仅在声明的 surface 内按已知 DOM 几何收紧该边至 `48px`；不得使用像素分析裁切。流程 MUST NOT 注入 DOM、改写样式、合成补边、推断背景或保存测量回执。
+
+### REQ-VISUAL-SURFACE-005
+
+缺少 selector、surface 透明或非自然背景、存在画框样式、target 越界、任一边小于 `required_margin` 或无法证明自然主题 surface 时，组件捕获 MUST 阻断并回到 `$storybook-stories`。阻断报告 MUST 使用 `视觉证据=不存在`、`空白裁剪=不适用` 并包含实测原因；合规且未收紧时使用 `空白裁剪=无需裁剪`，收紧时使用 `空白裁剪=已裁剪`。
+
+### REQ-VISUAL-SURFACE-006
+
+页面或完整页面 Storybook fallback MUST 保留 `trim_only`：仅检测边缘连通的统一背景并裁切多余外缘，保留可用的目标留白。`trim_whitespace.py --margin-policy=require_margin` MUST 保留 CLI 参数兼容，但 MUST 在任何像素分析前返回 `action=blocked` 与 `reason=source_managed_surface_required`，不得裁切、补边或合成组件图。
+
+## Verification
+
+### VER-VISUAL-SURFACE-001
+
+- Method: inspect `$storybook-stories`, `$storybook-screenshots`, and `$ui-visual-evidence` contracts plus `skills_index_check.py`.
+- covers: REQ-VISUAL-SURFACE-001, REQ-VISUAL-SURFACE-002, REQ-VISUAL-SURFACE-003, REQ-VISUAL-SURFACE-004, REQ-VISUAL-SURFACE-005
+- Pass condition: selectors, opaque natural surface, formula, `[required_margin,48]` range, one-preflight boundary, no-mutation rules, and block/report states are explicit.
+
+### VER-VISUAL-SURFACE-002
+
+- Method: `python3 skills/ui-visual-evidence/scripts/test_trim_whitespace.py`.
+- covers: REQ-VISUAL-SURFACE-006
+- Pass condition: trim-only crop/no-op/internal whitespace regressions pass; `require_margin` blocks before pixel analysis, never crops or pads, and preserves the input bytes.
+
+### VER-VISUAL-SURFACE-003
+
+- Method: `python3 bin/spec_contract_check.py --path docs/specs/visual-evidence-whitespace-trim/SPEC.md` and the compatibility-copy comparison.
+- covers: REQ-VISUAL-SURFACE-001, REQ-VISUAL-SURFACE-002, REQ-VISUAL-SURFACE-003, REQ-VISUAL-SURFACE-004, REQ-VISUAL-SURFACE-005, REQ-VISUAL-SURFACE-006
+- Pass condition: canonical structure, normative requirements, verification traceability, ADR membership, and byte-identical stable/legacy Spec copies pass.
+
+## Related ADRs
+
+- [组件证据采用源管理展示面](../../adr/0007-source-managed-component-evidence.md)
+
+## References
+
+- `skills/storybook-stories/SKILL.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/ui-visual-evidence/SKILL.md`
+- `skills/ui-visual-evidence/scripts/trim_whitespace.py`

package/toolkit/skills/docs/vendor/dot-codex/specs/w7yqp-git-skill-convergence/HISTORY.md

@@ -0,0 +1,28 @@
+# Git skill convergence 演进历史（#w7yqp）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- Pure git/local repo operations are a separate layer from PR orchestration and flow recovery.
+- Deleted prompt and old skill names are removed outright instead of kept as compatibility shims.
+- Historical specs, replay, and fixtures may keep old names because they are evidence, not current runtime routing.
+
+## Key Reasons / Replacements
+
+- `create-worktree` and `remove-worktree` are replaced by `git-worktree`.
+- `update-baseline` is replaced by `git-sync`.
+- `pr-post-merge-cleanup` and generic cleanup prompt behavior are replaced by `git-cleanup`.
+- Native Codex Ticket Worktree lifecycle is intentionally outside `git-worktree` and `git-cleanup`; the local Git layer may record it, but never removes its internal directory.
+- Branch setup prompt behavior is replaced by `git-branch`.
+- `git-sync` keeps the old no-argument mainline-sync behavior for checked-out topic branches: resolve a reliable default base locally, then rebase, and ask only on ambiguity or rewrite-policy blockers.
+- A detached maintenance worktree is distinct from a topic branch: a clean one can move directly to a confirmed base commit and remain detached, while `BASE_REF` + `REMOTE` shared workflow calls continue to require the topic-branch rebase path.
+- Cleanup helpers are invoked relative to the loaded skill directory so repository-local and installed skill layouts both work; resumed post-merge cleanup must carry PR identity instead of calling cleanup bare.
+- Cleanup gates need explicit absence evidence as well as existence evidence; same-worktree PR cleanup passes `PR_WORKTREE_REQUIRED=no`, and local-merge recovery keeps the topic branch name.
+- A cleanup resume is not complete unless it preserves both the worktree requirement state and any required PR worktree paths.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#w7yqp`.

package/toolkit/skills/docs/vendor/dot-codex/specs/w7yqp-git-skill-convergence/IMPLEMENTATION.md

@@ -0,0 +1,50 @@
+# Git skill convergence 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: Git/local repo 操作已收敛为四个新 git skills，并保留 `git-remote-troubleshoot`。
+
+## Coverage / rollout summary
+
+- Added `git-branch`, `git-worktree`, `git-sync`, and `git-cleanup`.
+- Moved post-merge and local-merge closeout scripts/tests to `skills/git-cleanup/scripts`.
+- Removed old pure-git skills and retired prompt files.
+- Updated active orchestration skills to reference new git skills.
+- Converted `work-branch-and-design` into a design-only prompt.
+- Preserved baseline-sync default resolution in `git-sync`: bare mainline sync requests resolve the remote default branch or unambiguous common branch before asking.
+- Added a direct `align-detached-base` path for clean maintenance worktrees: it fetches a confirmed base and leaves `HEAD` detached at the resolved commit without creating a branch, backup ref, or stash. It stops unless the old commit remains recoverable through target ancestry, an existing ref, or a HEAD reflog entry for that exact commit. Bare mainline-sync requests rebase only on attached topic branches; the shared `BASE_REF` + `REMOTE` rebase contract remains unchanged.
+- Added a disposable-repository integration test for detached alignment, idempotency, dirty-worktree and unrecoverable-head blocking, exact reflog recovery, action selection, and remote/branch preservation.
+- Made `git-cleanup` helper examples resolve scripts from the loaded skill directory and made `$flow-continue` carry post-merge PR cleanup context into `MODE=post-merge-pr`.
+- Preserved cleanup recovery state by passing explicit PR worktree requirement facts from `$pr-merge` and exposing local-merge `topic_branch` in status output.
+- Completed PR cleanup handoff state by carrying required PR worktree paths whenever `PR_WORKTREE_REQUIRED=yes` and preserving that requirement fact on `$flow-continue` resume.
+- Added Codex-managed Worktree protection to `git-worktree`, `git-cleanup`, and closeout context/gate scripts. Native Ticket paths are recorded as archive-only, excluded from manual removal, and covered by unit tests.
+
+## Remaining Gaps
+
+- None for the current migration scope.
+
+## Related Changes
+
+- `skills/git-branch/SKILL.md`
+- `skills/git-worktree/SKILL.md`
+- `skills/git-sync/SKILL.md`
+- `skills/git-cleanup/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/pr-merge/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/fast-flow/SKILL.md`
+- `skills/local-merge-flow/SKILL.md`
+- `skills/global-port-manager/SKILL.md`
+- `skills/wave-thread-flow/SKILL.md`
+- `skills/README.md`
+- `prompts/work-branch-and-design.md`
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`