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

package/toolkit/skills/docs/vendor/dot-codex/specs/storybook-skill-upgrade/SPEC.md

@@ -0,0 +1,189 @@
+# Storybook skill 增强与 docs-first 交付规范
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## Context and Scope
+
+This canonical spec governs the repository-local Storybook skills and their shared full-page visual-evidence routing. The page fallback rule below is limited to canonical skills, metadata, replay coverage, and related implementation status; legacy ID-prefixed specs and HISTORY remain unchanged.
+
+## Requirements
+
+### REQ-STORYBOOK-PAGE-FALLBACK-EXCEPTION
+
+Full-page or page-flow Storybook fallback MUST require both an absent qualified `ui_demo` and an existing explicit owner, project, or active-spec page exception. The absence of `ui_demo` alone MUST NOT authorize the fallback, and an owner-locked non-Storybook source MUST continue to block it.
+
+## Verification
+
+### VER-STORYBOOK-PAGE-FALLBACK-EXCEPTION covers: REQ-STORYBOOK-PAGE-FALLBACK-EXCEPTION
+
+Verify the canonical skills, three affected `agents/openai.yaml` files, implementation status, and focused replay cases. The replay checker must emit `FULL_PAGE_STORYBOOK_FALLBACK_WITHOUT_EXPLICIT_EXCEPTION` for the no-exception case, preserve direct owner, project-documentation, active-spec, and direct English grant exception passes, preserve component and owner-lock outcomes including English owner-source locks, reset prior page authorization or missing-`ui_demo` state when any new user full-page request begins even when it also names a component, bind missing-demo facts, authorization, and owner locks to the named page, retain every page-scoped owner lock in one user event, require a unique page target for an otherwise ambiguous multi-page Storybook route, reject a multi-page route that names only one page and would inherit that page's grant, permit an explicit owner lock withdrawal for that same page, treat an explicitly unavailable qualified `ui_demo` as missing but do not treat conditional absence wording as confirmed evidence, require qualified or stable availability before clearing missing-demo state, give current qualified `ui_demo` evidence precedence when one message contains historical absence and current availability, recognize missing-demo wording without treating negated or unqualified availability as current availability, evaluate permission clauses within the same page/fallback clause so a later unambiguous page approval can supersede historical denial without importing unrelated approvals, retain denial cues across intervening wording, carry a conditional follow-up such as `This approval takes effect only after ...`, `This exception is conditional ...`, or `after owner approval` onto the preceding page authorization, treat a trailing page-specific exclusion such as `not for this page` as a denial for that page, require release approvals to mention the Storybook fallback itself, reject conditional approval wording including `only after`, reject derived English denial forms such as `disallowed`, and treat negated, not-yet-approved, or question wording as no authorization with exactly one expected blocker finding; a request explicitly limited to a reusable component must not create a full-page fallback context.
+
+After a component-only turn, an assistant's subsequent explicit page-level Storybook result must still pass the page exception gate and preserve that page's owner lock. Storybook evidence explicitly limited to the reusable component remains allowed.
+
+Only an explicit withdrawal of that page's source requirement may release its owner lock; revoking another page's source requirement or a Storybook fallback must not release the lock.
+
+## Related ADRs
+
+None
+
+## 背景 / 问题陈述
+
+- 当前 `storybook-stories` 只要求“补一个能渲染的 story”，更像最低合格线，不足以驱动 Web UI 项目的系统化展示、组件状态矩阵与交互验证。
+- 当前 `storybook-screenshots` 只支持 `storybook_canvas`，无法直接把 docs 页里的状态矩阵作为 PR 视觉证据。
+- `docs-plan` 模板、skills 索引与 workflow PR publication procedure 的来源枚举还没有同步 Storybook docs-first 的工作方式，导致 Storybook 更像可选附属物，而不是稳定的 UI 交付面。
+
+## 目标 / 非目标
+
+### Goals
+
+- 将 `storybook-stories` 升级为组件/片段优先的 Storybook 交付 skill：默认补 stories、聚合 docs 页、主要状态矩阵与关键 `play` 交互验证。
+- 将 `storybook-screenshots` 升级为同时支持 `storybook_canvas` 与 `storybook_docs` 两类 mock 视觉证据来源。
+- 同步 workflow PR publication procedure、`docs-plan` 模板、skill 元数据与 skills 索引，使 Storybook 相关约束在 UI 任务中可被稳定发现与复用。
+- 保持现有 skill 名称与入口不变，避免把既有调用链打碎。
+- 明确完整页面/流程默认通过稳定 `ui_demo` 取证；只有缺少合格 `ui_demo` 且 owner、project 或 active spec 已明确授权页面级例外时才 fallback 到完整页面级 Storybook，缺少 `ui_demo` 本身不构成授权。
+
+### Non-goals
+
+- 不新增第三条顶层 Storybook workflow skill。
+- 不引入新的截图后端、视觉回归平台或额外的外部依赖。
+- 不修改任何具体业务仓库的 Storybook 配置或示例代码。
+
+## 范围（Scope）
+
+### In scope
+
+- `skills/storybook-stories/**`
+- `skills/storybook-screenshots/**`
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md`
+- `skills/docs-plan/templates/SPEC.md`
+- `skills/README.md`
+- `docs/specs/README.md`
+
+### Out of scope
+
+- PR body image helper 的 URL 改写机制
+- 业务仓库里的组件、页面、测试实现
+- 与 Storybook 无关的 UI 交付技能
+
+## 需求（Requirements）
+
+### MUST
+
+- `storybook-stories` 必须把“新/改 UI 组件、片段或可复用状态 => stories + docs/state gallery + 必要交互验证”定义成默认交付。
+- 若仓库支持 Storybook docs，组件/片段必须默认补聚合 docs 页，且 docs 以静态展示为主，不默认依赖 Controls/可调参面板。
+- 组件/片段必须默认覆盖主要状态矩阵。
+- 页面内部 UI 若具备独立状态、交互或复用价值，默认应抽成组件/片段并补 Storybook；纯布局、文案或无交互的一次性 glue UI 可由 `ui_demo` 页面证据覆盖。
+- 完整页面/流程默认不要求新增页面级 Storybook；视觉证据默认来自合格 `ui_demo`。
+- 当缺少合格 `ui_demo` 且存在 owner、project 或 active spec 已明确授权的页面级例外时，允许 fallback 到完整页面级 Storybook，并要求关键验收行为的 `play` 覆盖；没有该例外时必须报告 blocker。
+- 若主人显式锁定完整页面/流程的最终证据来源为 `web demo`、`ui_demo` 或其他非 Storybook 来源，Storybook skill 只能维持组件/片段覆盖或报告 blocker/fallback 背景，不得把 Storybook 结果表述成满足该锁定要求。
+- `storybook-screenshots` 必须支持 `source_type=storybook_canvas|storybook_docs`，两者都归类为 mock 证据。
+- workflow PR publication procedure 的视觉证据来源枚举必须同步新增 `storybook_docs`。
+- `docs-plan` 模板里的 Storybook 质量门槛必须显式覆盖 stories、docs pages、play/interactions。
+- `storybook-screenshots` 与 `docs-plan` 模板在讲 PR 图片选择器时，必须只使用 `PR: include` / `PR: none` 两种语义；像 `Recommended PR subset...` 这类自然语言提示不得再被描述成有效 selector。
+- `storybook-stories` 与 `storybook-screenshots` 都必须有匹配的 `agents/openai.yaml`，且文案与增强后的职责一致。
+
+### SHOULD
+
+- `storybook-stories` 应把状态覆盖矩阵与 docs 布局准则拆到独立 reference，避免 `SKILL.md` 过长。
+- `storybook-screenshots` 应优先推荐 docs 网格截图用于多状态证明，单一状态或交互节点继续优先 canvas 截图。
+- `skills/README.md` 应把两条 Storybook skill 都列为可发现入口。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- UI 组件/片段变更时，`storybook-stories` 先检测 Storybook 与 docs 能力，再按仓库现有约定补充或更新：
+  - 独立 stories；
+  - 聚合 docs 页；
+  - 适用的 `play` 交互测试。
+- docs 页必须以适合浏览的静态陈列为主，推荐 1-3 列响应式网格，一页展示多个主要状态；每个展示状态仍要保持为可独立访问的 story。
+- 完整页面/流程默认用稳定 `ui_demo` 提供视觉证据；Storybook 只承担其中可复用组件/片段的状态覆盖。
+- 若缺少合格 `ui_demo` 且已有 owner、project 或 active spec 明确授权页面级例外，页面/流程 Storybook fallback 必须代表完整页面，并在 `play` 中覆盖关键验收路径；例外不存在时必须报告 blocker。
+- `storybook-screenshots` 在生成 PR 证据时：
+  - 多状态总览优先允许从 docs 内容区域截图；
+  - 单状态、动效前后对比或交互节点继续允许从 canvas 截图。
+
+### Edge cases / errors
+
+- 若仓库检测到 Storybook 但没有 docs/autodocs/MDX 能力，`storybook-stories` 不得静默跳过 docs；必须要求补齐既有栈支持的 docs 路径，或明确报 blocker。
+- 若页面/流程缺少合格 `ui_demo` 且已有明确页面级例外需要 Storybook fallback，`storybook-stories` 必须要求先查仓库既有 mock/provider 约定，不允许现编私货式方案；没有明确例外时必须报告 blocker。
+- 若页面/流程已经被主人显式锁定为非 Storybook 证据来源，`storybook-stories` 与 `storybook-screenshots` 不得把 Storybook fallback 写成最终成功态。
+- 若 `storybook_docs` 用作截图来源，`storybook-screenshots` 仍不得截入 Storybook chrome、地址栏或无关 UI。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| `storybook-stories` workflow contract | skill | internal | Modify | in-spec | Codex skills | UI implementation turns | 新增 docs-first、状态矩阵、`play` 约束 |
+| `storybook-screenshots` source types | skill | internal | Modify | in-spec | Codex skills | PR visual evidence flows | 新增 `storybook_docs` |
+| `ui_demo` page evidence boundary | skill | internal | New | in-spec | Codex skills | UI visual evidence flows | 完整页面/流程默认使用稳定 mock-only demo surface |
+| workflow PR publication visual evidence source enum | procedure | internal | Modify | in-spec | Codex skills | PR setup flow | 接受 `storybook_docs` |
+| `docs-plan` Storybook quality gate | template | internal | Modify | in-spec | Codex skills | specs authors | 模板要求 stories + docs + interactions |
+
+### 契约文档（按 Kind 拆分）
+
+- None. 本计划只修改内部 skill/template 契约，以上表与对应 `SKILL.md`/模板正文即为真相源。
+
+## 验收标准（Acceptance Criteria）
+
+- Given `storybook-stories` When skill 被用于 Web UI 组件、片段或可复用状态任务 Then 文本必须把 stories、docs 页与适用的 `play` 测试都视为默认交付，而不是可选建议。
+
+- Given 当前变更是完整页面/流程视觉证据 When 存在稳定 mock-only `ui_demo` Then 不得强制新增完整页面级 Storybook；应从 `ui_demo` 取证。
+
+- Given 当前变更是完整页面/流程视觉证据 When 缺少合格 `ui_demo` 且存在 owner、project 或 active spec 明确授权的页面级例外 Then 允许使用完整页面级 Storybook fallback，并覆盖关键验收行为；若没有该例外则报告 blocker。
+
+- Given 主人已显式要求最终证据来自 `web demo` / `ui_demo` When 页面/流程 later 只能从 Storybook 取图 Then Storybook skill 不得把该结果报告为满足锁定要求；必须把控制权交回统一视觉证据门禁以报告 blocker 或等待主人改口。
+
+- Given `storybook-stories` When 仓库支持 Storybook docs Then skill 必须要求为组件/片段提供静态状态画廊型 docs 页，并说明 docs 默认不以 Controls playground 为主。
+
+- Given `storybook-screenshots` When 任务需要 Storybook 视觉证据 Then skill 必须接受 `storybook_canvas` 与 `storybook_docs` 两种来源，并给出对应的 capture / metadata 规则。
+
+- Given `storybook-screenshots` 或 `docs-plan` 模板 When 文本描述 PR 图片选择器 Then 只能教 `PR: include` / `PR: none`，不得再把自然语言 `Recommended PR subset...` 之类的说明表述成有效选择器。
+
+- Given workflow PR publication procedure When 读取视觉证据来源枚举 Then 必须能看到 `storybook_docs` 被支持并指向 `$storybook-screenshots`。
+
+- Given `skills/README.md` When 浏览 Storybook 相关 skill Then 必须同时看到 `storybook-stories` 与 `storybook-screenshots`，且简介能反映 docs-first 与视觉证据职责。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-stories`
+- `python3 skills/.system/skill-creator/scripts/quick_validate.py skills/storybook-screenshots`
+- `python3 skills/.system/skill-creator/scripts/generate_openai_yaml.py skills/storybook-stories --interface ...`
+- `python3 skills/.system/skill-creator/scripts/generate_openai_yaml.py skills/storybook-screenshots --interface ...`
+- `git diff --check`
+
+### UI / Storybook (if applicable)
+
+- Stories to add/update: `storybook-stories` contract, `storybook-screenshots` capture contract, `ui-visual-evidence` source enum, workflow PR publication source enum, `docs-plan` Storybook gate
+- Visual regression baseline changes (if any): None
+
+### Quality checks
+
+- Skills 索引与 agents metadata 文案对齐
+- Storybook 新旧来源兼容性人工 review
+
+## Visual Evidence
+
+## 方案概述（Approach, high-level）
+
+- 继续沿用现有两条 Storybook skill 的职责边界，但把 `storybook-stories` 收敛为组件/片段/可复用状态的 UI 交付真相源，把 `storybook-screenshots` 抬升为 docs/canvas 双来源证据源。
+- 完整页面/流程的默认视觉证据由稳定 `ui_demo` 承担，Storybook 页面级覆盖只作为缺少合格 `ui_demo` 且存在现有明确页面级例外时的 fallback；缺少 `ui_demo` 单独不授权页面级 Storybook。
+- 用一份轻量 reference 承载状态矩阵与 docs 布局建议，避免核心 `SKILL.md` 变成大杂烩。
+- 所有联动点只做必要增量兼容，不引入新的 top-level flow 或新的外部工具依赖。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若业务仓库已有特殊 Storybook 约定，skill 需要优先继承仓库现有写法，不能把这里的 fallback 当成强制实现样式。
+- 风险：`storybook_docs` 进入截图来源后，若调用方仍只识别旧枚举，可能需要补更多联动点；本轮先覆盖 workflow PR publication procedure 入口。
+- 假设：增强后的 Storybook 规范主要用于 Web UI 仓库；非 UI 仓库检测不到 Storybook 时仍按 skip 路径工作。
+
+## 参考（References）
+
+- `skills/storybook-stories/SKILL.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/project-engineering-workflow/references/pr-publication-procedure.md`
+- Storybook official docs: docs blocks / MDX / `play` / mocking

package/toolkit/skills/docs/vendor/dot-codex/specs/syj6s-pr-convergence-batching/HISTORY.md

@@ -0,0 +1,27 @@
+# PR convergence batching 演进历史（#syj6s）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- 统一首轮 `CI-Operator` sub-agent 的模型偏好为 `gpt-5.6-luna + low`，绑定单一 PR head SHA，并要求主 agent 通过阻塞式等待接收结果；模型或 effort override 不可用时回退到继承配置，同时保持 review profile 不变；重复的 tracker 不变量集中到 CI tracking short contract。
+- `d443ac1` fix(flow): batch PR convergence before remote churn
+- `71c44e5` fix(review): preserve convergence budgets across repair pushes
+- `f565cff` fix(flow): enforce resumable PR convergence gates
+- `281b1cd` fix(flow): honor no-write PR proof gates
+- `b4544c8` fix(review): rerun stale pre-pr proofs on new heads
+- `3b0afb3` fix(review): bind proof budget to current PR batch
+- `90e80dd` fix(docs): persist PR budget bindings consistently
+- `2c11073` fix(review): harden proof-only convergence rules
+- `4895098` docs(review): add pragmatic stop-loss after repeated reviews
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#syj6s`.

package/toolkit/skills/docs/vendor/dot-codex/specs/syj6s-pr-convergence-batching/IMPLEMENTATION.md

@@ -0,0 +1,66 @@
+# PR convergence batching 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 风险触发 pre-PR local proof、PR 批量收敛与 checks 缺席快速诊断
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-14
+- Legacy last-tracked: 2026-03-14
+- Current lifecycle: active
+- Catalog note: 风险触发 pre-PR local proof、PR 批量收敛与 checks 缺席快速诊断
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs/pr-convergence-batching/SPEC.md` 规格并登记索引
+- [x] M2: 在 shared Step 4/5 中前置风险触发的 `pre-PR local proof`
+- [x] M3: 固化 PR 批量收敛、current-SHA validation evidence 与 checks 缺席诊断门
+- [x] M4: 为自动收敛增加 `3` 次 repair permit 止损
+- [x] M5: 统一 `CI-Operator` sub-agent 的首选模型为 `gpt-5.6-luna + low`，绑定单一 PR head SHA，将主 agent CI 等待改为阻塞式 barrier，并把共享不变量集中到 CI tracking contract
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `skills/project-engineering-workflow/references/ci-tracking-short-contract.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/codex-review-loop/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/fast-flow/SKILL.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `d443ac1` fix(flow): batch PR convergence before remote churn
+- `71c44e5` fix(review): preserve convergence budgets across repair pushes
+- `f565cff` fix(flow): enforce resumable PR convergence gates
+- `281b1cd` fix(flow): honor no-write PR proof gates
+- `b4544c8` fix(review): rerun stale pre-pr proofs on new heads
+- `3b0afb3` fix(review): bind proof budget to current PR batch
+- `90e80dd` fix(docs): persist PR budget bindings consistently
+- `2c11073` fix(review): harden proof-only convergence rules
+- `4895098` docs(review): add pragmatic stop-loss after repeated reviews
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/syj6s-pr-convergence-batching/SPEC.md

@@ -0,0 +1,147 @@
+# PR convergence batching
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 现有 PR 流程虽然已经具备 freshness gate、wait-state closeout 与首轮并行编排，但仍容易在 review-fix 阶段退化成“发现一条修一条、每修一次就整套再跑”的长尾收敛。
+- session `019cea6c-927c-79d2-83aa-50fb5073509e` 给出了明确样例：PR 创建约在 `2026-03-14T05:04:55Z`，最终收口说明约在 `2026-03-14T07:06:59Z`；后半段主要耗时不是单次 CI 排队，而是多轮 review-fix-validate-push 循环，以及 checks 缺席后的额外诊断。
+- 当前 shared workflow 只规定了“首轮并行、后续单写入、一轮一次 push”，但还没有把“哪些改动必须在 PR 前先做本地 proof”“如何把验证证据绑定当前 candidate”“什么时候应该停止自动收敛并上抛”写成硬规则。
+
+## 目标 / 非目标
+
+### Goals
+
+- 保留 PR 首轮 `checks + PR-stage review` 的真正并行优势，不把流程整体串行化。
+- 在高风险改动进入 PR 路径前，前置一次 `pre-PR local proof`，把明显的状态一致性/并发/契约问题留在本地解决。
+- 把 PR 阶段的修复策略固定成“按根因批量修复 + 一轮一次 push + 按当前改动和仓库要求选择验证”。
+- 当 checks/workflow 在最新 `head_sha` 上迟迟没有出现时，尽快进入诊断并报告，而不是继续空等。
+- 为自动收敛增加明确止损阈值，避免无界 review-fix-push 循环。
+
+### Non-goals
+
+- 不新增新的顶层三态字段。
+- 不取消现有 shared wait budget，也不重写 freshness gate / wait-state closeout 的既有语义。
+- 不修改 `gh CLI` 远端控制面，不引入新的远端自动化通道。
+- 不把 `$local-merge-flow` 默认改成 PR 路径。
+
+## 范围（Scope）
+
+### In scope
+
+- 更新 `$project-engineering-workflow` 的 Step 4/5 共享契约，并用 `ci-tracking-short-contract.md` 集中 CI tracker 不变量。
+- 收紧 `$codex-review-loop` 的批量修复与验证策略。
+- 收紧 `$pr-create` 的首轮并行与 checks 缺席诊断规则。
+- 对齐 `$fast-flow` 与 `$pr-create` 的自动收敛边界。
+- 更新 `docs/specs/README.md` 与本规格文档。
+
+### Out of scope
+
+- 变更任何运行时代码或 `gh CLI` 远端操作契约。
+- 新增自动化测试框架。
+- 修改 `Step 5L` 的本地合主干业务语义。
+
+## 需求（Requirements）
+
+### MUST
+
+- 对高风险改动进入 PR 路径时，必须在首个远端变更前完成一次 `pre-PR local proof`。
+- `pre-PR local proof` 不能替代 PR 阶段绑定当前 `PR.head.sha` 的 fresh review proof。
+- 从 `normal-flow` / `local-merge-flow` 的本地 `Step 4 Ready` 恢复进入 PR 路径时，也必须重新检查这道高风险 gate；不得因为“之前已到 Step 4 Ready”就跳过 `pre-PR local proof`。
+- 若当前 flow 尚未授权本地写入，`pre-PR local proof` 只能先以只读 proof 形式执行；只有主人已授权自动收敛时，才允许把它升级成会落本地修复提交的本地收敛。
+- 任何被描述为 read-only 的 PR/local proof，都必须走单次直接 `codex review` 证据路径；不得借用可写的 `$codex-review-loop` 再靠文字声明“这次当作只读”。
+- PR 首轮仍然允许 `CI-Operator` 与第一轮 PR-stage review 并行启动。
+- `CI-Operator` 必须服从共享 CI tracking contract；其默认模型为 `gpt-5.6-luna + low`，override 不可用时可继承主 agent 配置，但不得改变 tracker 的只读职责。
+- PR 阶段默认按根因批量修复；同一轮允许多 commit，但只允许一次 push。
+- 验证 receipt 必须绑定当前 candidate 的输入、命令、acceptance evidence 和 SHA；它没有第二套验证分类、独立预算或锁。repair push 产生的新 `PR.head.sha` 必须重新建立当前 SHA 的 evidence。
+- 若最新 `head_sha` 在 PR 创建或 push 后 `10 分钟` 内仍无 checks/workflow 证据，必须优先进入诊断；不得使用 dispatch，新 run 只允许在已有 run 明确属于瞬态基础设施失败时 rerun 一次。
+- 但若能证明当前仓库/当前 SHA 本来就不期望自动 checks，则 absence 只能记为事实，不得单独上抛 blocker。
+- 对同一个 open PR 的同一轮收敛会话，每个 review epoch 最多允许 `3` 个 repair permit；所有 code review wave（包括 repair）固定为 `4 x Luna+high` 加最多 `2` 条专项 lane。无进展可进入诊断，但不能在剩余 permit 尚未耗尽时使 epoch `NON_CONVERGENT`；repair push 产生的新 `PR.head.sha` 不会重置预算。
+- 当 PR 收敛未在当前 turn 终态结束时，必须把 `PR收敛修复轮次=<n>/3` 及其 `PR预算绑定base_sha` / `PR预算绑定workflow_facts` 写入状态输出，供后续续推恢复预算。
+- 若恢复时预算绑定缺失或已 stale，只能在能证明“当前 PR 事实集从未进入过自动 PR convergence / repair batch”时初始化 `0/3`；否则必须上抛 blocker，不得静默把在途 PR 的预算清零重开。
+- final merge proof 是当前 SHA 的单条 `Sol` lane。其有效 blocker 必须回到当前 epoch 的剩余 repair permit，形成新 SHA 后再次完成普通 code review wave 和 final proof；只有 permit 已耗尽时才进入 convergence drag blocker。
+
+### SHOULD
+
+- 高风险改动的判定口径应在 shared workflow、review-loop、PR skill/prompt 里保持一致。
+- 验证命令应由当前改动、仓库要求和已有 acceptance evidence 决定，并保持 receipt 的 current-SHA 绑定。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- Step 4 对于将要进入 PR 路径的 run，先判断是否命中高风险改动：
+  - 命中条件至少包括：共享可变状态/持久化状态变更、明显 race-prone 或异步状态机流程、前后端契约同轮变化、workflow/prompt/skill 规则改动。
+  - 命中后，进入 Step 5 前先执行一次本地 `pre-PR local proof`，并完成相关本地验证。
+- Step 5 的首轮并行保持不变：
+  - `main-agent` 负责首个 push / create-or-reuse PR；`CI-Operator` 只负责绑定当前 `PR.head.sha` 的 first-round CI tracking，并使用 `gpt-5.6-luna + low`。
+  - `main-agent` 启动 tracker 后必须进入阻塞式 `wait_agent`，tracker 返回前不得自行轮询 CI。
+  - `main-agent` 负责首轮 PR-stage review 与必要的本地修复。
+- 首轮并行后进入 main-only convergence：
+  - 合并本轮 review findings、CI failure pack 与 spec-sync 建议。
+  - 按根因分组修复。
+  - 按当前改动、仓库要求和 acceptance evidence 运行必要验证。
+  - 一轮只 push 一次。
+- 每份 validation receipt 只描述实际执行的输入、路径、命令、acceptance evidence 和 candidate SHA。相同 execution identity 可复用已通过的 receipt；任何新的 candidate SHA 都需要其自身的 evidence，且不消耗类别配额。
+- Checks absence fast diagnosis：
+  - 当最新 `head_sha` 在 PR 创建或 push 后 `10 分钟` 内没有 check runs / workflow evidence，必须优先读取 workflows / workflow runs / labels / trigger facts。
+  - 仅当已有 run 明确属于瞬态基础设施失败时，允许对同一 SHA 做一次 rerun；不得 dispatch 新 workflow。
+  - 若仍无证据，返回 actionable blocker，而不是继续视作纯等待态。
+
+### Edge cases / errors
+
+- `pre-PR local proof` 若在同一次本地 review-loop invocation 内完成修复并对最新 `head_sha` 给出 clear 结论，则该 proof 直接绑定最新 `head_sha`；只有当它对新 `head_sha` 没有给出最终 clear 结论时，旧 proof 才失效并需要重跑。
+- 首轮并行后若 `PR.head.sha` 或 `PR.base.sha` 变化，PR 阶段 proof 和 CI 状态都必须按最新 PR 事实重置；repair permit 只按合法 epoch 规则继承或重开。
+- `PR预算绑定workflow_facts` 只能包含稳定可重建的策略事实，不能包含 `checks_expected` 这类会随普通等待推进而变化的运行态诊断结果。
+- 当自动收敛因阈值触发停止时，不得再用“继续自动修一点点”掩盖；必须显式说明当前属于 convergence drag blocker。
+- 无进展诊断不会绕过或提前耗尽剩余 repair permit；只有三次 permit 用尽且仍有有效 blocker 才能进入 convergence drag blocker。
+
+## 验收标准（Acceptance Criteria）
+
+- Given 高风险改动即将从 Step 4 进入 PR 路径 When 命中风险判定 Then 流程必须先完成一次 `pre-PR local proof`，再允许首个远端变更。
+
+- Given 首个 PR round 刚启动 When checks 与 PR-stage review 可以并行 Then 流程仍应并行启动，而不是整体串行化。
+
+- Given 首轮仍需要创建 `CI-Operator` sub-agent When 外层流程启动该远端协作轨 Then 应使用 `model=gpt-5.6-luna` 与 `reasoning_effort=low`，并让 `main-agent` 通过阻塞式 `wait_agent` 等待 tracker 终态。
+
+- Given 同一轮 PR-stage review 返回多条 in-scope findings When 主代理处理本轮阻塞项 Then 必须先按根因合并为一个修复批次，再进行一轮验证，并且该轮只 push 一次。
+
+- Given 最新 `head_sha` 在 PR 创建或 push 后 `10 分钟` 内没有 checks/workflow 证据 When 流程评估当前门禁 Then 必须优先进入诊断路径；不得 dispatch 新 workflow，只有已存在的瞬态失败 run 才允许一次 rerun。
+
+- Given 同一个 open PR 的同一轮收敛会话里，`PR.base.sha` / workflow 事实不变 When 三个 repair permit 已耗尽且 final merge proof 或普通 wave 仍有有效 blocker Then 自动收敛必须停止，并输出显式 convergence drag blocker。
+
+- Given 当前 SHA 的 final merge proof 返回有效 blocker When 当前 epoch 仍有 repair permit Then 必须授权一个普通 repair wave；该 repair 产生的新 SHA 重新经历 `4 x Luna+high + 最多 2 条专项 lane` 的 code review，随后再运行新的单 lane final merge proof。
+
+- Given `normal-flow` / `local-merge-flow` 从本地 `Step 4 Ready` 续推到共享 PR 路径 When 当前改动命中高风险 gate，且当前本地 `HEAD` 还没有绑定当前 base 事实的 `pre-PR local proof` Then 必须先补这次本地 proof，再允许首个远端 push / PR 创建。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- Unit tests: N/A
+- Integration tests: 通过文档契约审阅与规则交叉检查验证
+- E2E tests (if applicable): N/A
+
+### Quality checks
+
+- `git diff --check`
+- 受影响 skill/prompt 中的 `pre-PR local proof`、`10 分钟`、`一次 push`、三次 repair permit 与 final merge proof 文案交叉检查
+
+## 方案概述（Approach, high-level）
+
+- 在 shared workflow 层定义何时前置 proof、何时进入 PR 并行、何时停止自动收敛。
+- 在 review-loop 与 PR skill/prompt 层把 shared contract 翻译成执行规则，保证所有入口一致。
+- 保留真正有价值的并行，把低效的小颗粒重复并行改成批量收敛。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：高风险改动判定过宽会增加本地 proof 次数；判定过窄则仍可能把明显问题拖到 PR 阶段。
+- 风险：不同仓库的 workflow 触发方式不同，checks 缺席诊断只能定义“先查，再对已存在的瞬态失败 run rerun 一次”的保守路径。
+- 需要决策的问题：None
+- 假设：`10 分钟` checks 缺席诊断阈值和每个 epoch `3` 次 repair permit 阈值适合作为默认规则。
+
+## 参考（References）
+
+- Session `019cea6c-927c-79d2-83aa-50fb5073509e`
+- `docs/specs/pr-freshness-gate/SPEC.md`
+- `docs/specs/pr-wait-state-closeout/SPEC.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/sz4cs-global-port-preview-governance/HISTORY.md

@@ -0,0 +1,28 @@
+# Global port preview governance 演进历史（#sz4cs）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `sz4cs` expanded from “preview URL provenance” into a broader `$browser-open-page` governance contract so isolated browser-state separation now follows the same topic-level policy surface.
+- `$browser-open-page` now treats `isolatedContext` as opt-in, task-scoped state isolation: shared context remains the default, every isolated task must declare `task_scope_id` + `isolation_reason`, and one task may reuse only one isolated context.
+- Current current-truth docs later renamed the formal browser entrypoint from `$browser-open-page` to `$browser-surface`; this history keeps the old name where it reflects the original rollout vocabulary.
+- The contract intentionally blocks a second `isolatedContext` in the same task instead of auto-rewriting the request, because silent rewriting would hide upstream task-modeling mistakes and weaken auditability.
+- Dashboard wrappers now claim empty-PID leases atomically through listener binding and reject duplicate startup rather than overwriting an active owner.
+- Startup failures now close any listener created before claim verification or persistence completes.
+- Default automatic port allocation uses `10000+` deterministic scope-random candidate blocks so new worktrees do not cluster around a fixed low starting block while still preserving reproducible `scope_id` behavior.
+- Earlier local-preview routing distinguished existing Chrome state from plain localhost validation. The current route instead defaults to `$agent-browser`; Chrome control and DevTools require explicit exception reasons.
+- The current browser policy does not permit a project-owned headless fallback after an `$agent-browser` failure, and synthetic debugging-browser bootstrap remains blocked by default.
+- `826a50f` docs: enforce local preview port governance
+- `c530b57` chore: retire legacy service manager stack
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#sz4cs`.

package/toolkit/skills/docs/vendor/dot-codex/specs/sz4cs-global-port-preview-governance/IMPLEMENTATION.md

@@ -0,0 +1,75 @@
+# Global port preview governance 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 统一本地长驻服务的端口归属检查与冲突处理规则
+- Catalog note detail: 同时收口 `AGENTS.md` 中 `chrome-devtools` 例外路径的 `isolatedContext` 必要性门禁与单任务复用约束
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-13
+- Legacy last-tracked: 2026-03-13
+- Current lifecycle: active
+- Catalog note: 统一本地长驻服务的端口归属检查与冲突处理规则
+
+## Delivery Milestones
+
+- [x] M1: 建立全局端口治理 spec 并登记索引
+- [x] M2: 收紧全局长驻服务与端口冲突处理规则
+- [x] M3: 收紧本地预览相关浏览器禁忌，禁止系统 opener fallback
+- [x] M4: 将自动端口分配改为 `10000+` 按 scope 稳定随机候选顺序
+- [x] M5: 将 `chrome-devtools` 例外路径的 `isolatedContext` 治理纳入 `docs/specs/global-port-preview-governance/SPEC.md`，明确默认共享、必要性声明、单任务单实例复用与违规硬阻断
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `skills/global-port-manager/SKILL.md`
+- `docs/specs/global-port-preview-governance/SPEC.md`
+- `docs/specs/global-port-preview-governance/IMPLEMENTATION.md`
+- `docs/specs/global-port-preview-governance/HISTORY.md`
+- `docs/solutions/workflow-issues/browser-isolated-context-reuse.md`
+- `AGENTS.md`
+
+### Code touched
+
+- `bin/modules/workspace/port_registry.ts`
+- `bin/modules/workspace/port_registry_cli.ts`
+- `bin/tests/workspace/workspace.test.ts`
+- `skills/global-port-manager/scripts/port_registry.ts`
+- `skills/global-port-manager/scripts/test_port_registry.ts`
+
+Port lease registration and heartbeats now separate the recorded PID from its expected-owner guard. Dashboard wrappers atomically claim an empty-PID lease under the registry lock, bind before writing their PID, reject duplicate startup, and use the recorded port plus expected PID so stale processes cannot change or release replacement leases.
+
+The dashboard wrapper retains its listener cleanup handle before claim verification and persistence, so failed startup cannot leave an unmanaged local listener.
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `826a50f` docs: enforce local preview port governance
+- `c530b57` chore: retire legacy service manager stack
+- `b39a914` docs(specs): adopt topic-level spec model
+- Automatic allocation now defaults to stable scope-random ports at or above `10000`.
+- `AGENTS.md` 现在明确要求：默认浏览器入口是 `$ego-browser`；Chrome control 与 `chrome-devtools` 只保留显式例外路径。
+- `AGENTS.md` 现在明确要求：默认共享浏览器上下文；只有在共享状态会污染验证结果或引入不可接受副作用时，才允许在 `chrome-devtools` 例外路径里带 `task_scope_id` + `isolation_reason` 申请单一可复用的隔离上下文。
+
+## Remaining Gaps
+
+- 仅 `AGENTS.md` 记载的 `chrome-devtools` 例外路径受本次 `isolatedContext` 契约约束；其他直接 `chrome-devtools` consumer 仍需单独治理。
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`