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

package/toolkit/skills/docs/vendor/dot-codex/specs/agent-vm/contracts/cli.md

@@ -0,0 +1,82 @@
+# Agent VM command contract
+
+The installed executable is `agent-vm` (Python 3). A session is selected from `CODEX_THREAD_ID`; absence fails before remote mutation. The client sends a versioned JSON request on stdin to one-shot control over `ssh agent-vm-host`. No credential contents belong in arguments. Local help/version do not require a VM.
+
+## Commands
+
+| Command | Behavior |
+| - | - |
+| `doctor` | Dependencies, protocol, pinned VM image, native components and CT-local capacity facts; no lease allocation or PVE storage access. |
+| `version` / `help` | Local version/protocol or command help; no session or host access required. |
+| `acquire [--cpu N] [--memory SIZE] [--disk SIZE]` | New VM uses supplied sizes or 2 vCPU/4 GiB/20 GiB defaults. Cache retains omitted sizes and applies explicit fields before startup, never shrinking disk. Active equal sizes reuse; differences fail with resize guidance. No implicit renewal. |
+| `status` | Server time, lease state, native guest state/availability, resources, actual deadline, cache age, mappings and admission diagnostics. |
+| `renew` | Add 15 minutes with a two-hour remaining cap; expired or drained requests fail. |
+| `release` | End lease, revoke mappings/flows, stop; keep disk as disposable cache. |
+| `destroy` | Explicitly discard the current session's VM after authorized data loss. |
+| `restart` | Restart an active guest without extending deadline; explicitly renew first if less than five minutes remain. Agent and IPv4 readiness share that five-minute monotonic budget after native start. |
+| `resize [--cpu N] [--memory SIZE] [--disk SIZE] [--allow-restart]` | At least one size; only disk growth. Default changes require restart: without allowance return an unapplied plan before reclaim or mutation. |
+| `resize --memory SIZE --live` | Explicit native live balloon/hotplug; memory only, incompatible with CPU/disk flags or restart allowance. No automatic restart fallback; deadline unchanged. |
+| `ssh-info --format json\|ssh-config` | Current root connection and verified host-key/config material; expired access fails. |
+| `ssh [-- <ssh-arguments>]` | Native OpenSSH with generated strict configuration. |
+| `exec -- <argv>` | Native SSH execution with arguments quoted individually and remote exit status retained. Shell syntax requires explicit `sh -lc`. |
+| `sync --name NAME` | Invoke the archived synchronization helper from the current Git worktree. |
+| `upload SOURCE DESTINATION` | Online native transfer to the guest; does not renew. |
+| `download SOURCE DESTINATION` | Online native transfer from the guest; does not renew. |
+| `export PATH` | Tar stream on stdout, diagnostics only on stderr; no guest/CT archive file. |
+| `port add NAME --guest-port N [--protocol tcp\|udp] [--host-port N]` | Native NAT; default auto free-pool port. Same-name same-config is idempotent. |
+| `port list` / `port remove NAME` | Inventory or exact removal with flow cleanup, without renewing/stopping guest. |
+| `admin status` | Host/native component health and maintenance status. |
+| `admin drain enter\|status\|exit` | Refuse new leases/extensions; active leases may retrieve/release and expire normally. |
+| `admin session list` | Managed session inventory. |
+| `admin reconcile [--apply]` | Dry-run by default; explicit bounded native/state reconciliation. |
+| `admin gc [--apply]` | Dry-run by default; all eligible stopped caches, with no minimum idle age; explicit application rechecks eligibility. |
+
+Flags not listed here must come from the installed `--help`, rather than invented command layouts. `sync_worktree.py --name NAME` is also independently invocable and uses only `ssh-info --format ssh-config`.
+
+## Reclamation selection
+
+Manual `admin gc [--apply]` selects all managed stopped caches without an effective lease and with confirmed access cleanup, regardless of idle age. Dry-run is the default; applying cleanup reacquires object locks and rechecks current generation, identity and eligibility. A resumed cache, valid lease, transitional object or unaccounted native mapping is protected. Candidate errors identify incomplete deletion rather than asserting capacity was released. The native age timer independently selects caches idle at least `cache_seconds` (default 86400); that threshold is not a retention guarantee.
+
+Protocol 3 broadens manual selection from protocol 2's age-only behavior. Both CLI and control reject incompatible protocol requests before replay or mutation, preserving durable state and operation journals. No old request is converted or replayed under the broader semantics.
+
+## Management response and retries
+
+Management JSON must expose protocol version, server time, session, generation, actual state/deadline, operation identity and outcome. Acquire, restart and restart-capable resize use a 600-second local SSH management timeout; other management commands retain 240 seconds. Remote stderr is forwarded while the request is running, and stdout remains the single JSON response stream. Errors identify retryability, the actual failure phase, cleanup result and partial transitions. A transport failure must not be printed as a successful JSON response. A mutation retry must reuse its operation ID and expected generation; generations and lease expiry reject late commits, and queries must not repair/extend a lease invisibly. Exact wire field names are owned by the archived client/control protocol and must be versioned together.
+
+Protocol 4 uses request fields `protocol`, `action`, `session_id`, and (for mutations) `generation` and `operation_id`. Management command names map to actions in the archived CLI. Mutation commands accept `--operation-id`; the client writes the original request to a protected local operation journal before sending it, so an uncertain request can be retried with the same ID. A different payload with that ID fails. The control stores pending/completed outcomes durably; a pending outcome after interruption fails as `operation_incomplete` and requires status/reconciliation rather than repeating effects.
+
+Client and control must both use protocol 4; mismatches fail explicitly. Existing state, lease generations and operation records are retained. Old pending requests must be inspected and converged before upgrading; they are never rewritten or automatically replayed under the new protocol. Acquire resource fields are `cpu`, `memory_mib` and `disk_gib`; they use resize ranges (1–16 CPU, 512–65536 MiB, 20–4096 GiB) and the same CLI unit parsers. New creation and cache adjustment verify native disk size and guest filesystem capacity.
+
+Capacity responses have `scope: ct-filesystem` and one local filesystem layer, measured at the configured Incus pool path. Capacity admission and reclamation use these current CT-local observations; no backing-storage probes or PVE access are required or supported.
+
+Success envelopes contain `ok`, `protocol`, `server_time`, `action`, `session_id`, `generation`, `operation_id`, `outcome` and `result`. Replay adds freshly observed `current_state` while preserving the historical result. Only a committed explicit renewal changes the deadline; its deadline and replay record commit in one short transaction. An interrupted native timer rearm is recoverable from the recorded deadline. State summaries expose `effective_lease`, `lease_expires_at`, `inactive_since`, ports, verified resource records and any conservative `resource_reservation`. Error diagnostics are JSON on stderr with a nonzero exit. A CLI transport error includes the operation ID and never asserts whether its side effect completed.
+
+## Resource diagnostics
+
+`doctor.result.resources` and `status.result.admission` expose `verified`, `base`, `ratios`, `limits`, `allocated_and_reserved`, `remaining`, `ct_capacity` and `memory` (bytes: `limit_bytes`, `available_bytes`, `threshold_bytes`, with verified sources and observation time). Memory observation failures are structured `error` objects; component `ready` and `admission_ready` differ during admission refusal. Stopped caches do not count CPU/RAM; transitions use max(current,reserved) per object. A quota denial identifies `dimensions`, `requested`, `other_allocated`, `projected`, `base` and `limits`; actual pressure rejects admission without subtracting full virtual RAM. Logical reservations precede disk reclaim and native mutation.
+
+Status exposes `native_status` and `guest_available` separately from `effective_lease`. Unexpected stops are unavailable, with unknown cause unless attributable native evidence exists; a CT-wide OOM count is not attribution. Queries do not repair or restart a guest. Native failures preserve diagnostics and observed partial results. Project aggregate CPU/RAM quota conflicts fail admission and require explicitly authorized operations, not automatic config changes.
+
+## Live memory adjustment
+
+Protocol 4 adds the boolean `live_memory` resize field; protocol 3 peers fail explicitly before replay or effects. Live resize requires memory only, a running guest, intact recorded/native sizes and at least three minutes remaining. A same-size request returns an unchanged plan. Growth reserves max(current,target) and uses normal allocation/CT-pressure gates. Reduction preserves the old reservation until verified success but bypasses new-demand observations, including unavailable metrics. Drain still refuses resource changes. It performs no disk reclaim, NAT changes, lease extension or guest restart.
+
+Successful results expose `mode: live-memory`, `completed`, `native_attempts`, `verification.source: incus-live-update`, `configured_memory_mib` and unchanged `guest_boot_id`. Incus acknowledges its native balloon/hotplug operation; control verifies stored native sizes and a running responsive guest with the same boot identity before committing accounting. Linux MemTotal may stay unchanged after ballooning and is not the effective allocation measurement. Host headroom/RSS recovery and process continuity require real acceptance, not a configuration value alone.
+
+Only a memory reduction with the exact Incus balloon-convergence timeout reporting a current size above target permits one bounded same-target completion attempt within the original operation. It waits once for 45 seconds to let a large balloon converge, rechecking identity/generation, remaining lease, drain, native rollback, guest boot identity and conservative reservation before and after that interval (105 seconds required before waiting, 60 before the final update); native configuration already equal to the target is refused because a config no-op cannot acknowledge effective memory. Accounting stays conservative until an actual native acknowledgement. `native_attempts` preserves the first error and final outcome. Growth/hotplug and other failures are not retried automatically, and there is no third attempt or polling loop.
+
+Unsupported native growth/shrink, an unconfirmed timeout or continuity failure yields `resize_partial`, preserving the original error, completed stages and max(current,target) allocation. It does not stop an effective lease or promise rollback. Further live changes fail as `resize_incomplete`; inspect native/guest state and use explicitly allowed restarting resize or normal release for recovery. Existing operation IDs replay their recorded result rather than repeating effects.
+
+## SSH configuration
+
+The complete configuration uses `Host agent-vm`, root, `HostName 192.168.31.19`, the leased NAT port, explicit `IdentityFile`, `UserKnownHostsFile`, VM/generation-bound `HostKeyAlias`, `StrictHostKeyChecking yes` and `IdentitiesOnly yes`. Key material/config files are private. Renewal preserves ports; a new generation restores only SSH. Authentication refresh does not change the lease.
+
+## Output and data
+
+Management output is JSON; diagnostics go to stderr and slow-start observations are forwarded in real time. After native start, agent and IPv4 readiness use one shared 300-second monotonic budget, with one 120-second slow-start diagnostic boundary and at most one bounded continuation wait. Native start, disk/configuration mutation and post-check operations retain separate bounded timeouts. Native SSH/exec/transfer preserve their normal data and exit codes. Export stdout contains only tar bytes. CT and guest do not store export archives. Online files retained on the user's machine are chosen explicitly by the caller; there is no server-side artifact retention service.
+
+## Default admission and native inventory
+
+Doctor exposes `instances` with `verified`, `total`, `running`, `stopped`, `cached`, `other`, configured VM count `limits`, and `policy_compliant`. Status includes the same inventory under `admission.instances`. `limits.instances` and any configured `limits.virtual-machines` conflict with the managed policy; container-only restrictions are retained. New creation, cached restoration and resource growth reject a conflict before reservation or native effects. A verified memory-only live reduction can return capacity without new-demand policy checks; it never edits project policy. Existing lease queries, renewal, retrieval, release and equal-size acquire remain available.
+
+`doctor.ready` describes component health; `admission_ready` additionally requires direct admission of the default new 2-vCPU/4096-MiB/20-GiB guest. `default_admission` contains those `requested` sizes, `request_cost_bytes`, advisory `ready`, `reasons` and `reclaim_required`. Reasons separate policy conflict, `resource_insufficient` with dimensions/request/remaining, CT `memory_pressure`, `draining`, unavailable metrics and `disk_reclaim_required`. Default disk readiness accounts for current reservations and the configured creation cost. Doctor does not reclaim anything. A disk-reclaim indication permits normal acquire to evaluate eligible caches; this observation neither guarantees request success nor blocks reuse of an effective lease.

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

@@ -0,0 +1,23 @@
+# Storybook skill 增强与 docs-first 交付规范 演进历史（#ar7tp）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `444fd8d` feat(storybook): strengthen docs-first skill coverage
+- `b39a914` docs(specs): adopt topic-level spec model
+
+## Legacy Change Log
+
+- 2026-03-17: 新建规格，锁定 docs-first Storybook skill 升级范围与验收口径。
+- 2026-03-17: 完成 Storybook skills、联动模板、索引与元数据升级，并通过本地 skill 校验。
+- 2026-05-29: 将 Storybook 强制边界收敛到组件、片段与可复用状态；完整页面/流程默认改由稳定 `ui_demo` 取证，缺少 `ui_demo` 时才使用完整页面级 Storybook fallback。
+- 2026-05-29: 收紧 `storybook-screenshots` 输出合同：该 skill 只能报告 `storybook_docs` / `storybook_canvas` 证据，`ui_demo` 成功态必须由 `$ui-visual-evidence` 的 demo/browser 路径报告。
+- 2026-06-21: 补上 owner 显式非 Storybook 来源锁定合同，要求 Storybook skill 在整页/流程场景下只能作为“缺少合格 `ui_demo` 且无锁定冲突”时的合法 fallback。
+- 2026-07-20: 配套收紧 Storybook 截图与模板入口的 PR 选择器语义，只保留 `PR: include` / `PR: none`，并明确自然语言 `Recommended PR subset...` 不再是有效 selector。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#ar7tp`.

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

@@ -0,0 +1,68 @@
+# Storybook skill 增强与 docs-first 交付规范 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 将 Storybook 交付升级为组件/片段优先：主要状态矩阵、关键 play 测试、docs/canvas 双来源截图，并把完整页面证据默认分流到 `ui_demo`
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-03-17
+- Legacy last-tracked: 2026-03-17
+- Current lifecycle: active
+- Catalog note: 将 Storybook 交付升级为组件/片段优先：主要状态矩阵、关键 play 测试、docs/canvas 双来源截图，并把完整页面证据默认分流到 `ui_demo`
+
+## Delivery Milestones
+
+- [x] M1: 建立 `docs/specs/storybook-skill-upgrade/SPEC.md` 规格并更新 specs 索引
+- [x] M2: 升级 `storybook-stories` 与 supporting reference / metadata
+- [x] M3: 升级 `storybook-screenshots` 并同步 `pr-create`
+- [x] M4: 更新模板、skills 索引并完成校验与本地提交
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `docs/specs/README.md`: 新增 `docs/specs/storybook-skill-upgrade/SPEC.md` 规格索引
+- `skills/storybook-stories/SKILL.md`: 升级为 docs-first Storybook 交付规范
+- `skills/storybook-stories/references/state-coverage.md`: 新增状态矩阵与 docs 布局参考
+- `skills/storybook-stories/agents/openai.yaml`: 刷新 skill UI 元数据
+- `skills/storybook-screenshots/SKILL.md`: 扩展 docs/canvas 双来源截图规则
+- `skills/ui-visual-evidence/SKILL.md`: 新增 `ui_demo` 页面/流程证据源并按对象分流
+- `skills/storybook-screenshots/agents/openai.yaml`: 新增 skill UI 元数据
+- `docs/specs/shared-ui-visual-evidence-gate/replay/*`: 复用主视觉证据 spec 的 focused replay 覆盖 Storybook 边界回归
+- `skills/pr-create/SKILL.md`: 扩展视觉证据来源枚举
+- `skills/docs-plan/templates/SPEC.md`: 更新 Storybook 质量门槛描述
+- `skills/README.md`: 补充 `storybook-stories` 并刷新 Storybook 相关简介
+
+### Plan assets
+
+- Directory: `docs/specs/storybook-skill-upgrade/assets/`
+- In-plan references: None
+- PR visual evidence source: not used for this docs/skill change
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `444fd8d` feat(storybook): strengthen docs-first skill coverage
+- `b39a914` docs(specs): adopt topic-level spec model
+- Current policy update: route full-page visual evidence through `ui_demo`
+- Current policy update: keep `storybook-screenshots` final source reporting limited to Storybook evidence sources
+- Current policy update: Storybook skills must preserve owner-explicit non-Storybook evidence locks instead of reframing fallback as success
+- Current policy update: Storybook screenshot/template entrypoints now teach only `PR: include` / `PR: none`; free-text PR subset hints are no longer valid selector guidance
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

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

@@ -0,0 +1,165 @@
+# Storybook skill 增强与 docs-first 交付规范
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前 `storybook-stories` 只要求“补一个能渲染的 story”，更像最低合格线，不足以驱动 Web UI 项目的系统化展示、组件状态矩阵与交互验证。
+- 当前 `storybook-screenshots` 只支持 `storybook_canvas`，无法直接把 docs 页里的状态矩阵作为 PR 视觉证据。
+- `docs-plan` 模板、skills 索引与 `pr-create` 的来源枚举还没有同步 Storybook docs-first 的工作方式，导致 Storybook 更像可选附属物，而不是稳定的 UI 交付面。
+
+## 目标 / 非目标
+
+### Goals
+
+- 将 `storybook-stories` 升级为组件/片段优先的 Storybook 交付 skill：默认补 stories、聚合 docs 页、主要状态矩阵与关键 `play` 交互验证。
+- 将 `storybook-screenshots` 升级为同时支持 `storybook_canvas` 与 `storybook_docs` 两类 mock 视觉证据来源。
+- 同步 `pr-create`、`docs-plan` 模板、skill 元数据与 skills 索引，使 Storybook 相关约束在 UI 任务中可被稳定发现与复用。
+- 保持现有 skill 名称与入口不变，避免把既有调用链打碎。
+- 明确完整页面/流程默认通过稳定 `ui_demo` 取证；只有缺少合格 `ui_demo` 时才 fallback 到完整页面级 Storybook。
+
+### Non-goals
+
+- 不新增第三条顶层 Storybook workflow skill。
+- 不引入新的截图后端、视觉回归平台或额外的外部依赖。
+- 不修改任何具体业务仓库的 Storybook 配置或示例代码。
+
+## 范围（Scope）
+
+### In scope
+
+- `skills/storybook-stories/**`
+- `skills/storybook-screenshots/**`
+- `skills/pr-create/SKILL.md`
+- `skills/docs-plan/templates/SPEC.md`
+- `skills/README.md`
+- `docs/specs/README.md`
+
+### Out of scope
+
+- `github-pr-body-images` 的 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` 时，允许 fallback 到完整页面级 Storybook，并要求关键验收行为的 `play` 覆盖。
+- 若主人显式锁定完整页面/流程的最终证据来源为 `web demo`、`ui_demo` 或其他非 Storybook 来源，Storybook skill 只能维持组件/片段覆盖或报告 blocker/fallback 背景，不得把 Storybook 结果表述成满足该锁定要求。
+- `storybook-screenshots` 必须支持 `source_type=storybook_canvas|storybook_docs`，两者都归类为 mock 证据。
+- `pr-create` 的视觉证据来源枚举必须同步新增 `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`，页面/流程 Storybook fallback 必须代表完整页面，并在 `play` 中覆盖关键验收路径。
+- `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 约定，不允许现编私货式方案。
+- 若页面/流程已经被主人显式锁定为非 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 |
+| `pr-create` visual evidence source enum | skill | 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` Then 允许使用完整页面级 Storybook fallback，并覆盖关键验收行为。
+
+- 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 `pr-create` 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, `pr-create` 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。
+- 用一份轻量 reference 承载状态矩阵与 docs 布局建议，避免核心 `SKILL.md` 变成大杂烩。
+- 所有联动点只做必要增量兼容，不引入新的 top-level flow 或新的外部工具依赖。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：若业务仓库已有特殊 Storybook 约定，skill 需要优先继承仓库现有写法，不能把这里的 fallback 当成强制实现样式。
+- 风险：`storybook_docs` 进入截图来源后，若调用方仍只识别旧枚举，可能需要补更多联动点；本轮先覆盖已知 `pr-create` 入口。
+- 假设：增强后的 Storybook 规范主要用于 Web UI 仓库；非 UI 仓库检测不到 Storybook 时仍按 skip 路径工作。
+
+## 参考（References）
+
+- `skills/storybook-stories/SKILL.md`
+- `skills/storybook-screenshots/SKILL.md`
+- `skills/pr-create/SKILL.md`
+- Storybook official docs: docs blocks / MDX / `play` / mocking

package/toolkit/skills/docs/vendor/dot-codex/specs/bb5xj-global-solutions-docs-migrate/HISTORY.md

@@ -0,0 +1,25 @@
+# 全局 solutions 复利模型与 docs-migrate 统一迁移技能 演进历史（#bb5xj）
+
+> 这里记录会影响 Agent 理解“为什么一步步变成现在这样”的关键演进；单次任务流水账不放这里，规范正文仍以 `./SPEC.md` 为准。
+
+## Decision Trace
+
+- `0250c7d` feat(workflow): add docs-migrate and solutions flow
+- `ff68b01` fix(review): keep plan-migrate compatibility shim
+- `ee8280a` docs(specs): close docs-migrate rollout
+- `8a262c7` docs(review): align proof startup with codex runtime
+- `b39a914` docs(specs): adopt topic-level spec model
+- `b21cbfe` feat(skills): add solution sync and spec sync
+
+## Legacy Change Log
+
+- 2026-04-12: 创建 spec，固定 `specs + solutions` 与 `docs-migrate` 的首轮实现范围。
+- 2026-04-12: 完成 `docs/solutions` 契约、`docs-migrate` skill 与全局入口接线；保留 `prompts/plan-migrate.md` 作为 compatibility shim，并收敛 solutions gate / legacy id 语义。
+- 2026-04-12: 完成最小夹具验证与本地 review 收敛，规格进入已完成。
+- Companion-doc spec 模型上线后，`MODE=specs` 也被补充为创建完整 spec 目录（`SPEC.md` + `IMPLEMENTATION.md` + `HISTORY.md`），避免 legacy-plan-only 仓库刚 canonicalize 完就撞上新的 drift gate。
+
+## References
+
+- `./SPEC.md`
+- `./IMPLEMENTATION.md`
+- Legacy compatibility identity: `#bb5xj`.

package/toolkit/skills/docs/vendor/dot-codex/specs/bb5xj-global-solutions-docs-migrate/IMPLEMENTATION.md

@@ -0,0 +1,67 @@
+# 全局 solutions 复利模型与 docs-migrate 统一迁移技能 实现状态
+
+> 当前有效规范仍以 `./SPEC.md` 为准；这里记录实现覆盖、交付进度与 rollout 相关事实，避免这些细节散落到 PR / Git 历史里。
+
+## Current Status
+
+- Implementation: 已实现
+- Lifecycle: active
+- Catalog note: 收敛 docs-migrate / docs-solutions / 全局入口接线与 compatibility shim
+
+## Historical rollout snapshot
+
+- Legacy status snapshot: 已实现
+- Legacy created: 2026-04-12
+- Legacy last-tracked: 2026-04-12
+- Current lifecycle: active
+- Catalog note: 收敛 docs-migrate / docs-solutions / 全局入口接线与 compatibility shim
+
+## Delivery Milestones
+
+- [x] M1: 新增 `docs/solutions` 契约与最小 frontmatter/schema 说明。
+- [x] M2: 新建 `skills/docs-migrate/` 并承接 `plan-migrate` 的安全迁移能力。
+- [x] M3: 更新全局 AGENTS、核心 flow、docs-plan 与入口 prompt 对 `docs-migrate` / `solutions` 的引用。
+- [x] M4: 将 `prompts/plan-migrate.md` 收敛为兼容 shim，并完成最小夹具验证与本地 review 收敛。
+- [x] M5: `MODE=specs` 的 canonical bootstrap 已明确要求同时创建 `SPEC.md`、`IMPLEMENTATION.md`、`HISTORY.md`，与 companion-doc drift gate 对齐。
+
+## Rollout Artifacts
+
+### Docs touched
+
+- `.codex/AGENTS.md`: 加入 `docs/solutions` 与 `docs-migrate` 规则。
+- `docs/solutions/README.md`: 建立 canonical knowledge-store 契约与 frontmatter/schema 说明。
+- `skills/docs-migrate/**`: 新建迁移 skill 与 track-specific 参考。
+- `skills/docs-plan/SKILL.md`: 扩展 root-resolution 与知识库关系说明。
+- `skills/codex-review-loop/SKILL.md`: 加入 solutions knowledge pass 与 disposition hint 约定。
+- `skills/project-engineering-workflow/SKILL.md`: 写入 solutions 检索/处置/刷新门禁。
+- `prompts/goto-impl-branch.md`: 从 legacy 迁移提示切换为 `$docs-migrate`。
+
+### Plan assets
+
+- Directory: `docs/specs/global-solutions-docs-migrate/assets/`
+- In-plan references: `![...](./assets/<file>.png)`
+- Visual evidence source: maintain `## Visual Evidence` in this spec when owner-facing or PR-facing screenshots are needed.
+- If an asset must be used in impl (runtime/test/official docs), list it in `资产晋升（Asset promotion）` and promote it to a stable project path during implementation.
+
+### Asset promotion
+
+None
+
+## Related Changes
+
+- `0250c7d` feat(workflow): add docs-migrate and solutions flow
+- `ff68b01` fix(review): keep plan-migrate compatibility shim
+- `ee8280a` docs(specs): close docs-migrate rollout
+- `8a262c7` docs(review): align proof startup with codex runtime
+- `b39a914` docs(specs): adopt topic-level spec model
+- `b21cbfe` feat(skills): add solution sync and spec sync
+- `1ce2aff` fix(review): block incomplete associated specs
+
+## Remaining Gaps
+
+- None currently tracked.
+
+## References
+
+- `./SPEC.md`
+- `./HISTORY.md`

package/toolkit/skills/docs/vendor/dot-codex/specs/bb5xj-global-solutions-docs-migrate/SPEC.md

@@ -0,0 +1,168 @@
+# 全局 solutions 复利模型与 docs-migrate 统一迁移技能
+
+> 当前有效规范以本文为准；实现覆盖与当前状态见 `./IMPLEMENTATION.md`，关键演进原因见 `./HISTORY.md`。
+
+## 背景 / 问题陈述
+
+- 当前全局工程流程把 `docs/specs/**` 作为主规范，但没有与之对等的全局经验知识库入口。
+- 历史上存在 `docs/notes` 一类经验笔记诉求，也存在 `prompts/plan-migrate.md` 这种只覆盖 spec/planning 文档的迁移入口。
+- 若继续维持“spec-only + prompt-era migration”，知识无法在开工前检索、收口时沉淀，也无法在重构后被系统刷新。
+
+## 目标 / 非目标
+
+### Goals
+
+- 将全局文档模型收敛为 `specs + solutions`：`specs` 管长期 topic-level spec，`solutions` 管跨任务经验。
+- 用正式 skill `docs-migrate` 取代 `plan-migrate` 的主入口职责，统一覆盖 `specs / solutions / auto` 三种迁移模式；legacy prompt 仅保留兼容 shim。
+- 在全局 AGENTS 与核心 flow 中加入 solution lookup、solution disposition、solution refresh 三道门禁，并补一个日常使用的 `$solution-sync` 入口。
+- 新 Spec 采用 slug-only path；已有 ID path 保留读取兼容，目录规范化只在显式 `$docs-migrate MODE=specs-hygiene` 确认后执行。
+
+### Non-goals
+
+- 不为 `solutions` 引入独立 id、全局台账或额外 README 级索引。
+- 不批量迁移业务仓库中的历史 notes/spec 文档。
+- 不改变 `implement-only` 的 spec-gate 语义。
+
+## 范围（Scope）
+
+### In scope
+
+- 新增 `docs/solutions/README.md` 与分类目录、solution frontmatter 与状态约定。
+- 新建 `skills/docs-migrate/` 并迁移 `prompts/plan-migrate.md` 能力。
+- 更新 `.codex/AGENTS.md`、`skills/docs-plan/SKILL.md`、`skills/project-engineering-workflow/SKILL.md`、`skills/solution-sync/SKILL.md`、`prompts/goto-impl-branch.md` 等入口。
+- 把 legacy `prompts/plan-migrate.md` 收敛成只负责转发到 `$docs-migrate` 的兼容 shim。
+
+### Out of scope
+
+- 外部项目仓库中的实际 docs 迁移执行。
+- 为 `solutions` 引入独立 id 或强制索引台账。
+
+## 需求（Requirements）
+
+### MUST
+
+- `docs/solutions/**` 成为全局显式知识库，路径固定为 `docs/solutions/<category>/<slug>.md`。
+- `solutions` 默认不使用 id；身份由 `category + slug + frontmatter` 提供。
+- `docs-migrate` 必须保留 docs-only、删除前确认、一对一迁移、引用检查等安全边界。显式 docs 迁移任务默认需要主人确认候选集合；但 shared Step 2 mandatory gate 下，对确定性的 task-relevant legacy docs 子集允许无额外确认自动迁移。若 legacy source 是 notebook-style / monolithic catch-all note（尤其根 `docs/notes.md`），允许把当前任务直接相关的 subsection(s) / slice 提升为 canonical `docs/solutions/**`，而不强迫整份文档一次性整体迁完。
+- `docs-migrate` 的 `specs` 模式必须继续兼容 legacy `docs/plan/** -> docs/specs/**` 迁移，并直接产出 `docs/specs/<topic>/`；`$docs-plan-id` 只保留显式 legacy compatibility shim。
+- `docs-migrate` 的 `specs` 模式在建立 canonical `docs/specs/**` 时，必须一次补齐 `SPEC.md`、`IMPLEMENTATION.md`、`HISTORY.md`，不能只留下孤立 `SPEC.md`。
+- `docs-migrate` 的 `specs` 模式不得把 `docs/plan/README.md` 这类 legacy index/landing 文档误判成一对一 spec 候选。
+- 即便 `docs/plan/README.md` 不是一对一 spec 候选，`docs-migrate` 的 `specs` 模式在 legacy-plan-only 仓库里仍必须能 bootstrap canonical `docs/specs/README.md`，避免 Step 2 因缺 canonical spec root 而卡死。
+- `docs-plan` 的 root-resolution 必须在 dedicated docs/topic branch 或隔离 worktree 上调用 `$docs-migrate MODE=specs`；受保护分支保持只读，不能绕过该保护写入 canonical spec。
+- 当 `docs-migrate` 只是为了清掉 shared Step 2 / `goto-impl` 的 canonical spec gate 时，若删除 legacy 源文档仍需主人确认，允许先保留旧路径并继续；但必须把 canonical `docs/specs/**` 视为权威输入，并显式记录 `pending delete approval`，不得把 cleanup 说成已完成。
+- `docs-migrate` 的 `solutions` 模式必须支持 `docs/notes/**/*.md`、根 `docs/notes.md`，以及常见的 `docs/troubleshooting/**` / `docs/workflow/**` / `docs/learnings/**` 一类知识文档迁移到 `docs/solutions/**`。
+- 当同一 monolithic legacy knowledge doc 在一轮里拆出多个 subsection / slice 时，`solutions` 轨必须为每个迁移单元生成不同的 canonical slug/path；不得因为共用源标题或文件名而发生目标路径碰撞。
+- 当 `docs-migrate` 只是为了清掉 shared Step 2 / review 前置 knowledge gate 时，`solutions` 轨也必须允许先建立 canonical `docs/solutions/**`、再把 legacy notes 保留为 `pending delete approval`；不得让 delete approval 反过来堵死 mandatory solution gate。
+- 全局流程必须显式要求：开工前查 solutions、收口前判定 `solution_disposition`、重构/迁移后 refresh solutions。
+- `$solution-sync` 必须成为 shared solution gate 的 canonical 日常入口：focused lookup、`solution_disposition` 判定与 canonical `docs/solutions/**` 写入/refresh 都优先走它；legacy knowledge 的迁移仍由 `$docs-migrate` 负责。
+- `/prompts:goto-impl-branch` 若发现 task-relevant legacy knowledge docs（`docs/notes/**/*.md`、`docs/notes.md`、`docs/troubleshooting/**/*.md`、`docs/troubleshooting.md`、`docs/workflow/**/*.md`、`docs/workflow.md`、`docs/learnings/**/*.md`、`docs/learnings.md`），不得把 solutions migration gate 仅当作提示交给主人；它必须先在 handoff 前清掉该 shared Step 2 gate（允许停在 canonical 已建立但 legacy delete 仍 `pending delete approval` 的检查点）。
+- 当 focused Solution Lookup 明确未命中任何 task-relevant canonical solution 或上述 legacy knowledge docs 时，共享流程必须允许把 `solution_disposition` 初始化为 `none`，而不是在 Step 4 因 `未检查` 被无条件卡死。
+- legacy-plan-only 仓库必须先在非受保护分支完成 `docs/specs/<topic>/` canonicalization；实现分支命名不再依赖 `SPEC_ID`。
+- `/prompts:plan-migrate` 作为兼容 shim 时，必须继续保留 trailing text 的过滤语义，并把它传给 `$docs-migrate` 作为 `PATH_HINTS`；不得把旧调用静默扩成 repo-wide 扫描，也不得把旧有“迁移 planning/spec 文档”的默认语义改写成 `solutions` / `auto` 分流。
+
+### SHOULD
+
+- `docs-migrate` 支持 `auto` 模式，按 planning/spec 与知识文档特征自动分流。
+- `docs/solutions/README.md` 提供最小 frontmatter schema、目录选择规则与何时更新/替换/作废 solution 的说明。
+- 旧 prompt-era 文案应被清理，避免未来 run 继续把 `/prompts:plan-migrate` 当成 canonical 入口；若保留 shim，也只允许用于兼容。
+
+### COULD
+
+- 提供少量示例路径或示例 frontmatter，帮助后续仓库对齐。
+
+## 功能与行为规格（Functional/Behavior Spec）
+
+### Core flows
+
+- 当主流程命中 spec gate 时：仍以 `docs/specs/**` 为 topic-level spec；若需要迁移 legacy 计划文档，则调用 `$docs-migrate` 的 `specs` 或 `auto` 模式，而不是 prompt。
+- 当主流程或 `goto-impl` 只是为了先建立 canonical spec 输入时：允许在 delete-confirm checkpoint 前先停在“canonical spec 已建立、legacy cleanup 待批准”的状态，但必须显式报告 pending cleanup。
+- 当任务需要复用既有经验时：全局规则与共享工程流会把 `docs/solutions/**` 视为默认检索入口。
+- 当一次实现/评审收口发现新经验、补强旧经验或大改导致旧经验漂移时：主流程要求声明 `solution_disposition=none|update|create|refresh`。
+- 当用户显式要求迁移 docs 体系时：`$docs-migrate` 根据 `mode` 执行 `specs`、`solutions` 或 `auto` 迁移，并在 docs-only 边界内完成链接修复与旧文档删除。
+
+### Edge cases / errors
+
+- 若候选文档无法明确归入 planning/spec 或 knowledge/solution，`docs-migrate` 必须阻断并要求主人确认，而不是猜。
+- 若候选文档是 ADR/RFC/Architecture/Design 等设计文档，默认排除迁移。
+- 若 `solutions` 迁移发现高重叠目标，v1 仅允许阻断/提示；不在首次迁移中自动合并多篇来源。
+
+## 接口契约（Interfaces & Contracts）
+
+### 接口清单（Inventory）
+
+| 接口（Name） | 类型（Kind） | 范围（Scope） | 变更（Change） | 契约文档（Contract Doc） | 负责人（Owner） | 使用方（Consumers） | 备注（Notes） |
+| - | - | - | - | - | - | - | - |
+| docs-migrate | skill | internal | New | None | codex-global | 主工程流程 / docs 迁移任务 | 取代 `plan-migrate` 的主入口职责 |
+| solution-sync | skill | internal | New | None | codex-global | 主工程流程 / PR 收敛 / 日常 solution 维护 | canonical 日常 solution gate 入口 |
+| docs/solutions | docs taxonomy | internal | New | None | codex-global | 主工程流程 / 未来仓库 | 默认知识库入口 |
+| solution_disposition | workflow field | internal | New | None | codex-global | project-engineering-workflow / local-merge-flow / normal-flow / fast-flow | 收口前必须判定 |
+
+### 契约文档（按 Kind 拆分）
+
+None
+
+## 验收标准（Acceptance Criteria）
+
+- Given 当前 `.codex` 仓库仍有 `prompts/plan-migrate.md`，When 本轮实现完成，Then 它最多只保留为兼容 shim，且仓库内不再把 `/prompts:plan-migrate` 当成 canonical docs 迁移入口。
+- Given 一个只包含 legacy `docs/plan/**` 的 planning/spec 文档场景，When 使用 `$docs-migrate` 的 `specs` 模式，Then 能迁移到 slug-only `docs/specs/<topic>/`、保持 README 创建顺序与删除前确认。
+- Given 同一 legacy planning/spec 场景通过 `$docs-migrate MODE=specs` 完成 canonicalization，When 下一轮 shared Step 2 / drift gate 读取新建的 `docs/specs/**`，Then 对应 spec 目录已经包含 `SPEC.md`、`IMPLEMENTATION.md`、`HISTORY.md`，不会因为 companion docs 缺失被立即阻断。
+- Given 同一场景里还存在 `docs/plan/README.md` When `$docs-migrate` 发现 specs 候选 Then 不得把该 legacy index README 当成一对一 spec 候选或生成伪造的 canonical Spec。
+- Given 一个 legacy-plan-only 仓库里只剩 `docs/plan/README.md` 而尚无 `docs/specs/README.md` When `$docs-migrate` 执行 `MODE=specs` Then 它仍必须先 bootstrap canonical `docs/specs/README.md`，即使没有任何可做一对一迁移的 spec 候选，也不能把仓库留在“没有 canonical specs root”的状态。
+- Given 主人在受保护默认分支上开启一个 legacy-plan-only 仓库的 planning session When `docs-plan` 做 specs-first root resolution Then 它必须先进入 dedicated docs/topic branch 或隔离 worktree；未切走前只做预演，不能在默认分支旁路写入。
+- Given 一个包含 `docs/notes/**/*.md`、根 `docs/notes.md` 或常见 `docs/troubleshooting/**` / `docs/workflow/**` / `docs/learnings/**` 知识文档的场景，When 使用 `$docs-migrate` 的 `solutions` 模式，Then 会生成 `docs/solutions/<category>/<slug>.md`、补齐 frontmatter、修复 docs 引用，并且不会创建 solution id。
+- Given `solutions` 迁移是为了清掉 shared Step 2 / review 前置 knowledge gate，且旧 notes 删除仍需主人确认 When `$docs-migrate` 执行 `MODE=solutions` Then 它可以先建立 canonical `docs/solutions/**` 并把旧 notes 标记为 `pending delete approval`，而不是因为“尚未删除旧文件”卡死在 gate 前。
+- Given 根 `docs/notes.md` 或其他 legacy note 是 monolithic catch-all 文档，且只存在一个与当前任务直接相关的 subsection / slice When shared Step 2 或 `$docs-migrate` 的 `solutions` 轨为当前任务清 gate Then 允许只把这段 task-relevant subsection / slice 提升为 canonical `docs/solutions/**`，并保留其余无关内容在原 legacy 文档中，不能要求把整份混装文档一次性整体迁完。
+- Given 同一 monolithic legacy note 在一轮里要拆出多个 task-relevant subsection / slice When `$docs-migrate` 规划 canonical `docs/solutions/**` 映射 Then 每个 subsection / slice 都必须带有稳定的子标题/anchor 区分符，从而得到不同的 slug/path，而不是互相覆盖到同一个 canonical solution 文件。
+- Given monolithic legacy note 只被部分抽取，而旧文档仍保留其余主题内容 When `$docs-migrate` 处理 Markdown 入站链接 Then 不得把所有旧链接一刀切改写到新 canonical solution；只有那些能明确证明原本就在引用被抽取 subsection / slice 的链接才允许重写，其余链接必须继续指向保留的 legacy note。
+- Given 核心工程流程继续推进实现任务，When 流程进入开工前、收口前与重构后刷新阶段，Then 全局规则已能明确提示 solution lookup、solution disposition 与 solution refresh，且 shared Step 2 上的确定性 legacy-docs 迁移不会把自动流程降级成必须停下来等主人确认。
+- Given 当前 run 命中了已有 solution 或 review/CI 暴露出新的可复用经验，When main-agent 需要清掉 solution gate，Then 默认通过 `$solution-sync` 完成 focused lookup、`solution_disposition` 判定与 `docs/solutions/**` 写入/refresh；只有 legacy source 仍未 canonicalize 时才先切到 `$docs-migrate`。
+- Given `/prompts:goto-impl-branch` 发现 task-relevant legacy knowledge docs（`docs/notes/**/*.md`、`docs/notes.md`、`docs/troubleshooting/**/*.md`、`docs/troubleshooting.md`、`docs/workflow/**/*.md`、`docs/workflow.md`、`docs/learnings/**/*.md`、`docs/learnings.md`） When 它准备把 topic branch handoff 到实现阶段 Then 它必须先清掉 shared Step 2 的 solutions migration gate（允许 canonical 已建立但 legacy delete 仍 `pending delete approval`），而不是把未执行的 gate 只写进摘要后继续 handoff。
+- Given focused Solution Lookup 明确未命中任何 task-relevant canonical solution 或上述 legacy knowledge docs When 当前 run 继续推进到 Step 4 收口 Then 共享流程必须允许把 `solution_disposition` 记为 `none`，不得因为 `未检查` 而无条件阻断无关任务。
+- Given 当前工作命中一个只有 legacy `docs/plan/**` 且 canonical topic 尚未知的仓库 When 它需要把主人带到正确的实现分支 Then 它必须先在非受保护分支建立 canonical `docs/specs/<topic>/SPEC.md`，再进入实现分支；若旧 `docs/plan/**` 删除仍待主人确认，只能报告 `pending delete approval`，不能把 cleanup 伪装成已完成。
+- Given 旧的 `/prompts:plan-migrate` 调用仍携带附带路径/关键字（例如某个具体 legacy doc 路径） When 兼容 shim 把请求转交给 `$docs-migrate` Then 这些 trailing text 必须继续作为 `PATH_HINTS` 缩小候选范围，而不是被忽略导致 repo-wide 扫描。
+- Given 旧的 `/prompts:plan-migrate` 宏或习惯调用没有额外说明 taxonomy When compatibility shim 接手该调用 Then 它必须继续把这次调用解释为 planning/spec 迁移并转给 `$docs-migrate MODE=specs`；若要迁移 notes/learnings/troubleshooting 或混合 taxonomy，必须改为直接调用 `$docs-migrate`。
+- Given 后续 run 读取新的全局 AGENTS/skills，When 它们恢复旧 session，Then 现有 flow 锁定语义与 legacy ID path 的读取兼容性不被破坏。
+
+## 非功能性验收 / 质量门槛（Quality Gates）
+
+### Testing
+
+- Unit tests: 如为新脚本补辅助脚本，则至少做基础 CLI happy-path 与分类分流自检。
+- Integration tests: 用最小夹具覆盖 `specs`、`solutions`、`auto` 三种迁移模式。
+- E2E tests (if applicable): None。
+
+### UI / Storybook (if applicable)
+
+- Not applicable。
+
+### Quality checks
+
+- `python3 -m compileall`（若新增 Python 脚本）
+- 与本次改动直接相关的文本 grep / 入口检查
+- 必要时执行 `bash /Users/ivan/.codex/bin/plan_contract_check.sh` 等已有局部脚本
+
+## Visual Evidence
+
+None
+
+## 方案概述（Approach, high-level）
+
+- 先落 spec，把新文档模型与迁移 skill 契约钉死，再做 skill/规则改造。
+- `specs` 与 `solutions` 职责分离：前者继续是长期主题规范，后者是可检索、可更新、可替换的知识资产。
+- `docs-migrate` 只解决 taxonomy 迁移与安全边界，不在 v1 内承担大规模知识去重/合并。
+
+## 风险 / 开放问题 / 假设（Risks, Open Questions, Assumptions）
+
+- 风险：全局 AGENTS/flow 文案一旦写得过重，可能影响旧 session 恢复与未来默认路由。
+- 需要决策的问题：`docs/solutions` v1 分类是否先保持 3 类最小集。
+- 假设（需主人确认）：不需要为 `solutions` 额外引入 index 表或 id。
+
+## 参考（References）
+
+- `skills/docs-migrate/SKILL.md`
+- `skills/docs-migrate/references/specs-mode.md`
+- `skills/docs-migrate/references/solutions-mode.md`
+- `skills/docs-plan/SKILL.md`
+- `skills/project-engineering-workflow/SKILL.md`
+- `skills/solution-sync/SKILL.md`
+- `AGENTS.md`