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

package/toolkit/skills/docs/vendor/dot-codex/specs/multi-task-flow/native-handoff-compatibility.json

@@ -0,0 +1,43 @@
+{
+  "schema_version": 1,
+  "kind": "persistent-state-migration-record",
+  "migration": {
+    "description": "Add immutable exec-attempt parameters, monotonic creation observations, early observed thread identity and development baseline; use persistent native notification claims and matching attempt/provider receipts.",
+    "release_unit_description": "multi-task-flow source Skill; installation and real-run migration excluded",
+    "version_impact": "minor"
+  },
+  "durable_state": {
+    "description": "JSON ledger operations, immutable requests, events and notification attempts",
+    "storage_implementation": "existing atomically replaced ledger.json and request records",
+    "source_compatibility_range": {
+      "from_program_versions": "schema-1 legacy/contract-1 read-only; schema-2 contract-1 read-only; schema-2 contract-2 writable",
+      "to_program_version": "native-worktree-desktop-handoff candidate",
+      "direct_major_skips_supported": false
+    }
+  },
+  "database_migration": {
+    "applicable": false,
+    "ddl_structural_changes": [],
+    "dml_changes": [],
+    "historical_data_backfill_or_transformation": []
+  },
+  "rollout_observability": {
+    "operations_must_remain_separate": true,
+    "operation_sequence": ["claim native attempt", "persist observed identity", "verify exit and bind", "native message receipt", "workspace readiness"],
+    "progress_signals": ["dispatch_thread_observed", "dispatch_creation_resolved", "notification_delivery_reconciled", "lifecycle_recorded", "task_started"],
+    "pause_points": ["after any durable attempt; unknown retains capacity and forbids blind retry"]
+  },
+  "recovery": {
+    "deployed_migrations_immutable": true,
+    "program_rollback_state_behavior": "does-not-automatically-reverse-compensate-or-down-migrate",
+    "faulty_release_recovery": "forward-repair-by-a-new-program-version; reuse native request and observed identity; replay never respawns or sends",
+    "backup_restore_role": "separate-disaster-recovery"
+  },
+  "validation": {
+    "source_state_tests": ["migrate.test.ts", "maintenance-compatibility.test.ts", "codex-thread-create.test.ts", "notification-delivery.test.ts", "engine.test.ts"],
+    "stopped_release_reentry": "unknown dispatch/request replay and SIGKILL notification claim preserve identity and exclude duplicate side effects",
+    "public_api_impact": "minor: existing creation payload retained; notification-send now prepares a native send intent requiring explicit platform receipt",
+    "persistent_state_impact": "minor: candidate reads historical evidence; older binaries need not read dispatch_thread_observed and must not be used to continue native dispatches",
+    "downgrade": "not supported for newly written native dispatch state; no installation or downgrade performed"
+  }
+}

package/toolkit/skills/docs/vendor/dot-codex/specs/p6m2r-pr-live-github-truth-source/HISTORY.md

@@ -0,0 +1,20 @@
+# PR live GitHub 真相源 演进历史（#p6m2r）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `2aa616a` docs(pr): require live GitHub blocker diagnosis
+- `5603121` docs(pr): tighten blocked-state diagnosis
+- `9317980` docs(pr): fix blocked-state owner wording
+- `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: `#p6m2r`.

package/toolkit/skills/docs/vendor/dot-codex/specs/p6m2r-pr-live-github-truth-source/IMPLEMENTATION.md

@@ -0,0 +1,62 @@
+# PR live GitHub 真相源 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 收紧 shared Step 5：当前 PR blocker 只能从 `gh CLI` 刷新的 GitHub 当前事实集推导，assistant 历史回答仅用于 promise-resume
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-12
+- Legacy last-tracked: 2026-04-12
+- Current lifecycle: active
+- Catalog note: 收紧 shared Step 5：当前 PR blocker 只能从 `gh CLI` 刷新的 GitHub 当前事实集推导，assistant 历史回答仅用于 promise-resume
+
+## Delivery Milestones
+
+- [x] M1: 明确 `gh CLI` 刷新的 GitHub 当前事实集是 PR blocker 真相源
+- [x] M2: 收紧 shared contract 与 Step 5 入口 skill
+- [x] M3: 同步无参数 `pr-*` prompts
+- [x] M4: 完成文档 spot-check 与 `git diff --check`
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `docs/specs/pr-live-github-truth-source/SPEC.md`
+- `skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/pr-merge/SKILL.md`
+- `prompts/pr-create.md`
+- `prompts/pr-merge.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `2aa616a` docs(pr): require live GitHub blocker diagnosis
+- `5603121` docs(pr): tighten blocked-state diagnosis
+- `9317980` docs(pr): fix blocked-state owner wording
+- `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/p6m2r-pr-live-github-truth-source/SPEC.md

@@ -0,0 +1,122 @@
+# PR live GitHub 真相源
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 这轮问题不是缺少某一条 `behind` / `dirty` 规则，而是 agent 在解释“PR 为什么现在不能 merge”时，仍会把历史 assistant 回答、旧状态总结或空 reviews 之类弱信号当成当前 blocker 依据。
+- 通过 `gh CLI` 刷新的 GitHub 当前事实面已经足够给出当前 blocker：`gh pr view --json state,closed,mergedAt,isDraft,mergeable,mergeStateStatus,headRefOid,baseRefOid,reviewDecision,statusCheckRollup` 提供 PR 状态、mergeability 与 head/base SHA 等核心事实，`gh api` / `gh run` 提供 checks、workflow 与 review-policy 事实。
+- live 样本已经说明旧做法会误导：
+  - `IvanLi-CN/codex-vibe-monitor#144`：通过 `gh CLI` 刷新的事实集里 reviews 为空，但 `Review Policy Gate=success`，不能把空 reviews 报成 approval blocker。
+  - `IvanLi-CN/codex-vibe-monitor#323`：通过 `gh CLI` 读取时 PR 已 `merged=true` / `state=closed`，不应该再把历史 blocker 口径延续到当前结论里。
+
+## 目标 / 非目标
+
+### Goals
+
+- 把“当前 PR blocker 真相源”明确收敛到 `gh CLI` 刷新的 GitHub 当前事实集，而不是 assistant 历史回答。
+- 统一 shared Step 5、`$flow-continue`、`$pr-create`、`$pr-merge` 与 `pr-*` prompts 的口径。
+- 明确历史 assistant 文本只能用于 promise-resume / stop condition，不得用于当前 blocker inference。
+
+### Non-goals
+
+- 不恢复 replay 驱动的诊断策略，也不新增 replay fixtures。
+- 不改 `gh CLI` 远端控制面，不新增外部服务。
+- 不重写整个 Step 5 工作流，只收紧 blocker 真相源与 reducer 顺序。
+
+## 范围（Scope）
+
+### In scope
+
+- `skills/project-engineering-workflow/references/pr-diagnosis-short-contract.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/pr-merge/SKILL.md`
+- `prompts/pr-create.md`
+- `prompts/pr-merge.md`
+- `docs/specs/README.md`
+
+### Out of scope
+
+- `bin/pr_skill_replay_check.py`
+- focused replay fixtures / cases
+- 业务仓库代码实现
+
+## 需求（Requirements）
+
+### MUST
+
+- 在报告“PR 当前为什么不能 merge”前，必须先用 `gh CLI` 刷新当前 GitHub 事实集，最少包括：
+  - `gh pr view --json state,closed,mergedAt,isDraft,mergeable,mergeStateStatus,headRefOid,baseRefOid,reviewDecision,statusCheckRollup`（或等价 `gh api` 字段）
+  - `gh api` / `gh run` 提供的 current commit status、check runs、workflow runs 与 review-policy 事实
+- 只有当 live status 仍把 review policy 留作真实候选 blocker 时，才继续读取 reviews / review comments。
+- 历史 assistant 回答、旧状态总结、流程锚点都不得直接作为“当前 PR blocker”证据。
+- 历史 assistant 文本只允许用于：
+  - 续接已经承诺的下一步分支
+  - 保留当前 stop condition / merge intent
+- shared reducer 必须先看 live `state/merged/draft/mergeable/mergeable_state/head.sha/base.sha`，再判定 draft / conflict / behind / blocked / checks / review。
+- `mergeable_state=blocked` 只能视为顶层 gate shape，必须继续按 live `checks/workflows -> review policy -> review threads -> deployments/merge queue/rules` 下钻；若当前 live surfaces 仍未显出具体 gate，只能报告“GitHub 当前仍将该 PR 标记为 blocked，但具体门禁尚未在可见状态面中显出”或等价当前事实描述，不得猜成 approval blocker。
+- `approval not required` / `approval satisfied` / `Review Policy Gate=success` 这类 live 正证据优先于空 reviews、空 comments、旧 prose。
+- `PR.head.sha` 或 `PR.base.sha` 一旦变化，旧 blocker 口径、checks/proof/spec verdict 失效，必须按新的 live fact set 重算。
+
+### SHOULD
+
+- shared contract 与入口 skill 顶部 100-150 行内应直接出现“当前 blocker 以 `gh CLI` 刷新的 GitHub 当前事实集为准”的约束。
+- prompts 也应把这条约束写成无参数执行前置条件，避免入口遗漏。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Live truth-source reducer
+
+- 对 open PR，当前 blocker 只由当前通过 `gh CLI` 刷新的 GitHub 当前事实集推导。
+- `state=closed && merged=true`：报告已合并，不再诊断当前 blocker。
+- `state=closed && merged=false`：报告已关闭未合并，不再虚构“仍在等待”的 blocker。
+- `draft=true`：draft gate 优先。
+- `mergeable=false` 或 `mergeable_state=dirty`：冲突 gate 优先。
+- `mergeable_state=behind`：freshness / branch update 优先。
+- `mergeable_state=blocked`：继续下钻当前 live checks / review / rules；`blocked` 本身不是最终解释。
+- `mergeable_state=blocked` 的下钻顺序固定为：先 checks/workflows，再 review policy，再 unresolved review blockers，再 deployments/merge queue/rules；若都没显出来，也只能停在“GitHub 当前仍将该 PR 标记为 blocked，但具体门禁尚未在可见状态面中显出”。
+- 若因 `mergeable_state=blocked` 停下且细因仍未显出，对外固定话术应为：`GitHub 当前仍将该 PR 标记为 blocked，但具体门禁尚未在可见状态面中显出`；下一门禁固定写成“继续刷新当前 PR 的 live checks/review/rules surfaces”或等价 live-refresh 语句。
+- open PR 的 `mergeable=null` 或 `mergeable_state=unknown` 不是 approval/check failure 的直接证据；必须继续看 live status surfaces，而不是用历史 assistant 口径补空白。
+
+### Promise-resume boundary
+
+- `继续 / 推进流程 / 你直接做吧` 仍可继承最近一次已承诺分支。
+- 但继承的是“下一步走哪条路”，不是“当前 blocker 是什么”。
+- 一旦进入 PR 阶段，blocker 解释必须重新从 live PR facts 起算。
+
+## 验收标准（Acceptance Criteria）
+
+- Given `IvanLi-CN/codex-vibe-monitor#144` When 通过 `gh CLI` 刷新的 GitHub 事实集显示 reviews 为空且 `Review Policy Gate=success` Then skill / prompt 契约不得再把 approval 缺失写成默认 blocker。
+
+- Given `IvanLi-CN/codex-vibe-monitor#323` When 通过 `gh CLI` 刷新的 GitHub 事实集显示 `state=closed` 且 `merged=true` Then 契约必须把它归为“已合并”，而不是沿用旧 blocker 口径。
+
+- Given 已缓存的 assistant 文本仍在说“可能缺 review” When 当前通过 `gh CLI` 刷新的 GitHub 事实集显示 `mergeable_state=behind` Then 下一门禁必须回到 freshness / branch update，而不是继续报 approval blocker。
+
+- Given 当前通过 `gh CLI` 刷新的 GitHub 事实集只显示 `mergeable_state=blocked` When checks/workflows 与 review-policy live surfaces 仍未暴露具体负证据 Then 契约只能输出“GitHub 当前仍将该 PR 标记为 blocked，但具体门禁尚未在可见状态面中显出”或继续刷新，不得把 `blocked` 直接翻译成“缺 approval”。
+
+- Given 当前通过 `gh CLI` 刷新的 GitHub 事实集仍停在 `mergeable_state=blocked` 且细因未显出 When agent 需要对外停下并给主人一个恢复锚点 Then 结论必须使用固定话术“GitHub 当前仍将该 PR 标记为 blocked，但具体门禁尚未在可见状态面中显出”，且下一门禁必须指向继续刷新 live surfaces，而不是猜测性的 approval/checks 结论。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- `git diff --check`
+- 人工 spot-check：shared contract、`$flow-continue`、`$pr-create`、`$pr-merge` 与两个 `pr-*` prompts 顶部片段
+
+### Quality checks
+
+- grep/spot-check 确认相关入口都出现了 “当前 blocker 以 `gh CLI` 刷新的 GitHub 当前事实集为准 / assistant 历史回答不能当 blocker 依据” 的硬规则
+
+## 风险 / 假设
+
+- 风险：若未来新增其他 PR 入口而未引用 shared contract，可能重新引入“看 assistant 旧回答猜 blocker”的回归。
+- 假设：`gh CLI` 继续稳定提供读取 PR 状态、checks/workflows 与 review-policy 所需的字段与事实面。
+
+## 参考（References）
+
+- `gh CLI` live sample: `IvanLi-CN/codex-vibe-monitor#144`
+- `gh CLI` live sample: `IvanLi-CN/codex-vibe-monitor#323`
+- `docs/specs/pr-skill-diagnosis-thinning/SPEC.md`
+- `docs/specs/pr-freshness-gate/SPEC.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/parallel-pr-flow/HISTORY.md

@@ -0,0 +1,5 @@
+# History
+
+## Lifecycle
+
+The topic was introduced as the bounded direct-PR alternative to Initiative. It preserves the existing direct PR and merge contracts and does not migrate existing Initiative runs.

package/toolkit/skills/docs/vendor/dot-codex/specs/parallel-pr-flow/IMPLEMENTATION.md

@@ -0,0 +1,16 @@
+# Implementation
+
+## Status
+
+已实现。
+
+## Coverage
+
+- `bin/plan_contract_check.sh` validates `parallel-pr` routing and frozen task contracts.
+- The default-route proof accepts equivalent Chinese and English expressions for independent direct PR slices.
+- `skills/parallel-pr-flow/` defines the coordinator and task envelope.
+- `workflow PR publication procedure` and `workflow PR merge procedure` retain direct PR ownership while carrying and checking cohort metadata.
+
+## Validation
+
+Run the focused plan fixtures, spec contract checker, skill index checker, and instruction architecture checker from the repository root.

package/toolkit/skills/docs/vendor/dot-codex/specs/parallel-pr-flow/SPEC.md

@@ -0,0 +1,41 @@
+# Parallel Direct PR Flow
+
+## Context and Scope
+
+Independent direct PRs do not need Initiative's Ticket, integration, or aggregate lifecycle. They still need a frozen ownership contract, durable recovery facts, and a safe boundary for optional merge delegation.
+
+## Scope
+
+This specification covers plan routing, native task envelopes, milestone reporting, metadata recovery, and direct merge-mode delegation for a `parallel-pr` cohort. It does not change Initiative's state machine or add a PR delivery role.
+
+## Requirements
+
+### REQ-PARALLEL-001 - Route only independent direct slices
+
+The planner MUST select `parallel-pr` only for 2..8 independently acceptable direct PR tasks with one exact base, no dependency, no shared integration, and no aggregate acceptance.
+
+### REQ-PARALLEL-002 - Freeze task contracts
+
+Every `task:pr-<slug>` MUST declare disjoint `owned_surfaces`, named `consumed_contracts`, `depends_on=none`, and `merge_mode`. The task budget equals the frozen topology count.
+
+### REQ-PARALLEL-003 - Use milestone coordination
+
+The parent MUST create native tasks and accept implementation, Step 5C, merge/post-merge, blocked, and scope-change milestones. It does not maintain an active polling loop after implementation starts.
+
+### REQ-PARALLEL-004 - Recover from durable metadata
+
+Task titles and direct PR bodies MUST carry `parallel_cohort` and `parallel_task`. Task and PR metadata are sufficient to reconcile an existing task; no local cross-cohort ledger is required.
+
+### REQ-PARALLEL-005 - Keep merge delegation fail-closed
+
+Tasks MUST stop at `Step 5C Ready` by default. `merge-on-green` requires the frozen task identity, current direct PR metadata, current-head preflight, and safe repository-native merge/release serialization.
+
+## Verification
+
+- VER-PARALLEL-001: `bin/plan_contract_check.sh --cases` proves explicit and default routing, 2..8 bounds, exact task mapping, no dependency, and disjoint ownership. (covers: REQ-PARALLEL-001, REQ-PARALLEL-002)
+- VER-PARALLEL-002: flow inspection and replay fixtures prove milestone-only parent coordination, scope-change revalidation, isolated failure, and metadata recovery. (covers: REQ-PARALLEL-003, REQ-PARALLEL-004)
+- VER-PARALLEL-003: PR skill inspection and merge-mode fixtures prove direct role retention, ready-only default, and fail-closed merge delegation. (covers: REQ-PARALLEL-005)
+
+## Related ADRs
+
+- [0011-parallel-direct-pr-flow](../../adr/0011-parallel-direct-pr-flow.md)

package/toolkit/skills/docs/vendor/dot-codex/specs/pj4fz-pr-post-open-scope-freeze/HISTORY.md

@@ -0,0 +1,23 @@
+# PR post-open scope freeze 演进历史（#pj4fz）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `b577074` fix(flow): freeze post-open PR scope
+- `01a4501` fix(flow): generalize same-pr reopen scope
+- `c39563c` fix(flow): extend reopen and freeze guardrails
+- `7552826` fix(flow): persist same-pr reopen state
+- `4986a57` fix(flow): bind reopen recovery to pr context
+- `03654c5` fix(flow): tighten reopen recovery bindings
+- `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: `#pj4fz`.

package/toolkit/skills/docs/vendor/dot-codex/specs/pj4fz-pr-post-open-scope-freeze/IMPLEMENTATION.md

@@ -0,0 +1,58 @@
+# PR post-open scope freeze 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: PR 打开后默认冻结范围，允许 behind/main-sync 必要兼容修复
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-15
+- Legacy last-tracked: 2026-03-15
+- Current lifecycle: active
+- Catalog note: PR 打开后默认冻结范围，允许 behind/main-sync 必要兼容修复
+
+## Delivery Milestones
+
+None
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- `skills/fast-flow/SKILL.md`
+- `skills/flow-continue/SKILL.md`
+
+### Plan assets
+
+None
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `b577074` fix(flow): freeze post-open PR scope
+- `01a4501` fix(flow): generalize same-pr reopen scope
+- `c39563c` fix(flow): extend reopen and freeze guardrails
+- `7552826` fix(flow): persist same-pr reopen state
+- `4986a57` fix(flow): bind reopen recovery to pr context
+- `03654c5` fix(flow): tighten reopen recovery bindings
+- `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/pj4fz-pr-post-open-scope-freeze/SPEC.md

@@ -0,0 +1,103 @@
+# PR post-open scope freeze
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 现有 `docs/specs/pr-convergence-batching/SPEC.md` 已经解决了 PR 阶段的批量收敛、validation 预算与 checks 缺席诊断，但还没有约束“PR 打开后是否还能继续往里塞新的验收/UI/Story 改动”。
+- session `019cea68-eaa5-75e0-aced-890e08d9b5c8` 暴露出一个典型问题：PR 很早就创建了，但后续长时间仍在同一个 PR 里继续做视觉/Story/交互收口，导致 PR 不只是收敛容器，而变成了持续开发容器。
+- 现有流程允许 freshness gate 在 PR 后再次对齐主干；这条路径是必要的，但如果没有额外规则，就容易把“main-sync 带来的必要兼容修复”和“顺手继续做新的界面优化”混在一起。
+
+## 目标 / 非目标
+
+### Goals
+
+- 在 PR 已打开后默认冻结范围，防止同一个 open PR 持续承载新的验收/UI/Story 扩张。
+- 明确保留白名单例外：review-fix、CI/blocker 修复、behind/main-sync 带来的必要兼容修复、spec-sync 与纯视觉证据补录。
+- 规定显式 same-PR reopen 的路径：允许主人明确要求“就在这个 PR 里继续扩范围”，但不能借此洗掉既有 PR convergence 预算。
+- 与 `docs/specs/pr-convergence-batching/SPEC.md`、`docs/specs/pr-freshness-gate/SPEC.md`、`docs/specs/pr-wait-state-closeout/SPEC.md` 保持分层：本规格只补 post-open scope freeze，不重写已有 freshness/wait-state/budget 语义。
+
+### Non-goals
+
+- 不修改运行时代码或 `gh CLI` 远端操作契约。
+- 不新增新的顶层三态字段。
+- 不把截图替换、spec 证据补录这类纯 visual evidence 流程误判成 scope expansion。
+
+## 需求（Requirements）
+
+### MUST
+
+- 一旦 `PR状态=存在` 且当前 PR 事实集已建立，默认进入 `post-open scope freeze`。
+- 在 freeze 状态下，允许留在同一个 PR 内继续推进的改动只包括：
+  - review-fix；
+  - CI / blocker code fix；
+  - `mergeable_state=behind`、`PR.base.sha` 前进、或 main-sync 导致的必要兼容修复；
+  - spec-sync；
+  - 不引入新产品行为/验收标准的 visual evidence 补录或替换。
+- 在 freeze 状态下，默认不得把以下改动继续混入当前 PR：
+  - 新功能或新增验收标准；
+  - 新的视觉优化、交互重设计、文案 polish；
+  - 新增 Story/示例/演示态，除非它们只是当前已接受行为的证据补录；
+  - 与当前 review/CI/main-sync 无直接因果关系的 UI 收口。
+- 泛化“继续 / 收尾 / 盯着 / 修一下”不能视为 scope reopen；只有主人显式要求“就在这个 PR 里继续做新的扩范围改动”时，才允许 same-PR reopen。
+- same-PR reopen 必须回到本地 Step 3/4 重新收口，再回到共享 Step 5；不得在冻结中的 PR convergence 回合里直接边跑 review-loop 边扩范围。
+- same-PR reopen 一旦显式批准，在“回到本地 Step 3/4 重新收口”的阶段内必须跨 turn 保持有效，直到同一个 open PR/topic branch 第一次带着这批 reopened work 回到共享 Step 5 并完成 publish-or-stop 判定，或被主人后续指令显式撤销/改成 follow-up PR。
+- 这段跨 turn reopen 必须落进可恢复状态：PR 阶段状态区至少要持久化 `same_pr_reopen=active/inactive` 与 `same_pr_reopen_binding=<PR #>:<PR.head.ref>:<PR.head.sha>|none`，供后续泛化“继续”只在正确的 open PR/topic branch / head revision 上恢复。
+- same-PR reopen 不会提供额外验证次数预算，也不会洗掉既有的 `PR收敛修复轮次`、repair permit 或 PR 绑定门禁；只有现有绑定规则已经认定 `PR.base.sha` / workflow 事实变化时，才允许按既有机制重建收敛状态。
+- 若主人希望干净预算，必须拆 follow-up PR，而不是在同一个 open PR 里通过 reopen 归零预算。
+
+### SHOULD
+
+- shared workflow、`$pr-create`、`$fast-flow`、`$flow-continue` 应使用相同的“允许留在当前 PR 的白名单”口径。
+- 同步主干后的 UI 调整应从严判定：只有被 main-sync 直接逼出来的兼容修复才算 in-scope，不能把“顺手优化界面”混入白名单。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core behavior
+
+- 进入共享 Step 5 后：
+  - `PR状态=存在` 前，仍按 Step 4 / freshness gate / PR 创建语义推进。
+  - `PR状态=存在` 后，默认冻结范围。
+- 对每一轮 PR 阶段写入前，agent 必须先判断当前待改动属于：
+  - `allowed same-PR fix`
+  - `scope expansion`
+- `allowed same-PR fix` 包括：
+  - 当前 review findings 的直接修复；
+  - 当前 CI/problem pack 的直接修复；
+  - freshness gate / branch update / main-sync 导致的必要兼容修复；
+  - drift/spec/evidence 补录；
+  - 已经明确属于当前验收标准的证据性 Story/screenshot 刷新。
+- `scope expansion` 包括：
+  - 当前 PR 之外的新视觉要求；
+  - 新的 Story 演示态；
+  - 交互布局/文案继续打磨；
+  - 与当前 review/CI/main-sync 无直接因果关系的“顺手再改一点”。
+- 显式 same-PR reopen：
+  - 主人明确要求继续在当前 PR 中扩范围时，允许退出冻结；
+  - 退出后先回到本地 Step 3/4 重新收口；
+  - 之后再回到该 open PR 的 Step 5，且继续沿用原 PR 的 convergence budget。
+
+### Edge cases
+
+- 若 `PR.base.sha` / workflow facts 改变，预算是否重建仍由既有 binding 规则决定；freeze/reopen 本身不提供额外预算豁免。
+- 若视觉证据刷新本身引入了新的产品行为或视觉要求，就不再属于 visual evidence exemption，必须按 scope expansion 处理。
+- 若 owner 只说“继续盯着”但同时提出新的 UI/Story 修改点，默认仍按 freeze 阻断，而不是自动视为 reopen。
+- merge path、proof regeneration、以及同分支 auto-push 也必须重新应用 freeze gate；不能因为入口是 `$pr-merge` 就绕过 post-open scope freeze。
+
+## 验收标准（Acceptance Criteria）
+
+- Given open PR 已存在 When 新待办属于 review-fix、CI fix、spec-sync 或 main-sync 必要兼容修复 Then 允许继续留在同一个 PR 内推进。
+
+- Given open PR 已存在 When 新待办属于视觉/交互/Story 的新增验收或 polish Then 默认按 scope expansion 阻断，不允许直接混入当前 PR。
+
+- Given open PR 已存在且主人只说“继续/收尾/盯着” When 当前新增待办本质上是新的验收/UI 扩张 Then 不得把这句泛化继续解释成 same-PR reopen。
+
+- Given open PR 已存在且主人明确要求“就在这个 PR 里继续做新的扩范围改动” When agent 执行 same-PR reopen Then 必须回到本地 Step 3/4 重新收口，并保留该 PR 已有的 convergence budget，不得归零。
+
+- Given open PR 因 `mergeable_state=behind` 或 `PR.base.sha` 前进而重新同步主干 When 当前界面必须联动调整才能保持兼容 Then 这些调整可以继续留在同一个 PR 中，且不视为 scope expansion。
+
+## 风险 / 假设
+
+- 风险：`main-sync 必要兼容修复` 的边界存在主观性；默认从严判定，避免 same-PR scope creep。
+- 风险：若主人坚持 same-PR reopen，PR convergence budget 会继续累计，可能更早触发 stop-loss；这是有意设计，不是副作用。
+- 假设：视觉证据刷新与产品行为变化可以通过“是否改变既有验收标准”进行区分。

package/toolkit/skills/docs/vendor/dot-codex/specs/pr-conflict-auto-heal/HISTORY.md

@@ -0,0 +1,22 @@
+# PR conflict auto heal 演进历史（#j4ha2）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `b282add` fix: auto-heal PR conflict diagnostics
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- No legacy change-log section was recorded for this spec.
+
+## Contract Notes
+
+- checks/workflow 缺席继续由 live mergeability 与共享 CI contract 共同判定；冲突优先于 absence，确认 manual-only 时也不使用 `workflow_dispatch` 制造自动证据。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#j4ha2`.