create-yss-spec 2.1.10 → 2.1.13

package/template/wiki/raw/README.md

@@ -11,7 +11,8 @@
 ```text
 ├── .agents/                 ← 跨 Agent 共享 skills 的权威内容
 ├── .claude/                 ← Claude skills 投影与平台专属 skills
-├── .codex/                  ← Codex skills 投影与平台专属 YSS skills
+├── .codex/                  ← Codex skills 投影与平台专属 skills
+├── .cursor/                 ← Cursor skills 投影
 ├── .hermes/                 ← Hermes skills 投影与平台专属 skills
 ├── .pi/                     ← Pi skills 投影与平台专属 skills
 ├── .qoder/                  ← Qoder skills 投影与平台专属 skills
@@ -105,6 +106,7 @@ scripts/verify-template
 | [docs/user-guide/图示生成器使用指南.md](./docs/user-guide/图示生成器使用指南.md) | Excalidraw 可视化辅助 skill 使用手册 |
 | [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
+| [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |
 | [docs/process/harness-process-tailoring.md](./docs/process/harness-process-tailoring.md) | 小改动 / 中等变更 / 新模块的流程裁剪指南 |
 | [docs/process/harness-executive-blueprint.md](./docs/process/harness-executive-blueprint.md) | 面向业务方和管理者的 Harness 一页式蓝图 |
 | [docs/process/implementation-repo-integration.md](./docs/process/implementation-repo-integration.md) | 外部前端 / 后端实现仓库接入与跨仓库切片绑定 |
@@ -120,6 +122,7 @@ scripts/verify-template
 | 模板 | 用途 |
 |------|------|
 | [docs/templates/spec-template.md](./docs/templates/spec-template.md) | Spec，包含 OpenAPI 影响、测试决策、AI / 人工审查点 |
+| [docs/templates/local-parent-ticket-template.md](./docs/templates/local-parent-ticket-template.md) | Local Markdown 功能父 Ticket 与生命周期索引 |
 | [docs/templates/vertical-slice-ticket-template.md](./docs/templates/vertical-slice-ticket-template.md) | 垂直切片 Ticket |
 | [docs/templates/agent-brief-template.md](./docs/templates/agent-brief-template.md) | `triage` 产出的 Agent Brief |
 | [docs/templates/implementation-repo-registry-template.md](./docs/templates/implementation-repo-registry-template.md) | 外部实现仓库登记 |

package/template/wiki/raw/create-yss-spec-repository-mode-contract.md

@@ -0,0 +1,95 @@
+# `create-yss-spec` 接管与模板同步跨仓库契约
+
+本文定义模板源仓库与外部 `create-yss-spec` CLI 仓库之间的身份、资产边界、迁移、同步、验证和发布契约。
+
+## 契约目标
+
+- 模板源仓库保留 `repository_mode: template-source`。
+- CLI 创建或接管的产品仓库写入 `repository_mode: project-instance`。
+- CLI 只管理 manifest 声明的研发管理资产，不接管前后端运行时代码、业务目录、用户文件或 `.git`。
+- 通过模板快照和 40 位 `templateCommit` 使每次初始化、升级和回滚可追踪。
+- 新模板快照的实例门禁以 Node `>=22 <27` 运行；不得执行 `npm install`、`pnpm install` 或维护侧 vendor 构建。`scripts/vendor/` 必须随快照分发且可离线使用。
+
+## 生命周期接口
+
+### 空目录初始化
+
+初始化必须把模板身份转换为 `schema_version: 1`、`repository_mode: project-instance`，并执行目标仓库的：
+
+```bash
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+scripts/verify-template
+```
+
+### 已有项目 `attach`
+
+```bash
+npx create-yss-spec@latest attach \
+  --target-dir . \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --dry-run
+npx create-yss-spec@latest attach \
+  --target-dir . \
+  --project-name "项目名称" \
+  --business-domain "业务领域" \
+  --apply [--force]
+```
+
+`attach` 必须显式选择 dry-run 或 apply，已有 `.yss-template.json` 时拒绝并提示 `sync`。计划按 `missing`、`matched`、`conflict`、`unsafe` 分类；force 只能覆盖受管 conflict，不能绕过 unsafe 或迁移冲突。合法 `template-source` 可转换为 `project-instance`，合法 `project-instance` 保留并校验，非法身份在写入前阻断。
+
+### 持续同步 `sync`
+
+`sync` 只使用 CLI 包内置的模板快照。“最新”指用户执行 `npx create-yss-spec@latest` 所携带的最新已发布快照，不在运行时直接拉取模板仓库。普通同步新增缺失文件、更新 baseline 未被本地修改的文件、报告冲突和模板删除；`sync --force` 先备份再覆盖受管冲突，模板删除默认只报告。
+
+完成后必须重新执行三个模板门禁；任一门禁失败时回滚文件变更并保持旧 metadata 版本。
+
+模板把共享运行脚本从 Ruby 迁移到 Node 时，CLI 同步继续将模板删除按 `remove-report` 报告；不得静默删除既有实例的 `.rb` 文件。对新快照，CLI 必须验证公开入口、Node 版本失败信息、离线门禁和回滚均符合本契约。
+
+## metadata v2
+
+`.yss-template.json` 至少包含：
+
+```json
+{
+  "metadataSchemaVersion": 2,
+  "templateName": "create-yss-spec",
+  "cliVersion": "2.1.4",
+  "templateSource": "github:iloveZzz/yss-spec-project-template",
+  "templateCommit": "<40-char-commit>",
+  "managedFilesManifestVersion": "<manifest-hash>",
+  "managedFiles": {}
+}
+```
+
+`managedFiles` 是每个受管文件的 baseline。CLI apply 前把将被覆盖的文件保存到目标目录外的临时备份目录；验证成功后默认保留，失败按操作日志回滚，metadata 不更新。
+
+## 固定迁移规则
+
+CLI 必须遵循 [Spec / Ticket 迁移指南](../../docs/user-guide/规格与任务迁移指南.md) 的固定映射：旧 Spec / Ticket skill 和模板入口迁移为当前名称，旧规格文件、根 `.scratch/<feature>/` 迁移到当前路径；无法推断功能归属的扁平 Ticket 标记为 `unsafe` 并阻断。新旧目标内容不一致时标记 `conflict`，不得静默覆盖。
+
+## 跨仓库验收
+
+| 场景 | 必须验证 |
+|---|---|
+| 空目录初始化 | `project-instance`、metadata v2、固定 commit、六类 projection 和模板门禁 |
+| 任意已有项目 attach dry-run | 不写文件、不删除 `.git`，运行时代码和无关文件不变 |
+| attach apply | 缺失资产新增；matched 纳入 baseline；conflict 需 force；unsafe 不可 force 绕过 |
+| 旧资产迁移 | 规格 / Ticket 路径和根 scratch 安全迁移；目标冲突与扁平 Ticket fail closed |
+| sync | 新增、更新、冲突、迁移和删除报告完整；force 只作用于受管文件 |
+| post-sync | 三个门禁全部 fresh 通过；失败时文件和 metadata 回滚 |
+| Node 运行时迁移 | Node 22 / 24 下 init、attach dry-run/apply、sync 都无需安装依赖；缺失或不兼容 Node 必须 fail closed 且回滚 |
+| 遗留 Ruby | 新快照无活动 Ruby 脚本；既有实例遗留 `.rb` 仅 `remove-report`，不静默删除 |
+| 发布包 | 固定 commit 下 `npm test` 和 `npm pack --dry-run` 通过，包内含 `template.snapshot.json` |
+
+本变更只涉及模板治理和外部 CLI，不涉及 frontend、backend、OpenAPI 或运行时工程；这些范围为 `not-applicable`。
+
+## 发布顺序与阻断条件
+
+1. 模板恢复 `docs/process/*`、正式处理 `.qoder` 投影并通过 fresh verification，形成确定 commit。
+2. CLI 绑定该 commit，完成 attach / sync 跨仓库测试和独立 review。
+3. 运行固定 commit 的 `npm test`、`npm pack --dry-run`，确认包内快照和实例门禁通过。
+4. 发布 CLI `2.1.4`，并回写版本、验证证据、备份恢复路径和回滚点。
+
+模板引用仍为浮动 ref、任一共同验证失败、独立 review 未完成或打包失败时，只能声明“本仓库实现完成，跨仓库发布受阻”，不得声明整体可发布。本轮不执行 npm publish。

package/template/wiki/raw/harness-process-tailoring.md

@@ -0,0 +1,64 @@
+# Harness 流程裁剪与影响面判定
+
+本文件规定如何根据变更规模和风险选择最近可信阶段。裁剪只减少未触发的门禁，不得跳过已经命中的条件强制门禁。
+
+安全 / 权限不单独分诊。需求或冻结资产没有明确改变相关行为时不登记、不解释 `not-applicable`、不增加门禁；明确改变时只按实际 UI、API、Backend、Data、High-risk 影响复用普通流程。SQL / DDL / 迁移、上传 / 下载等技术载体继续由其数据或 API 影响决定路线，不自动升级为安全专项。
+
+## 1. 判定顺序
+
+1. 先读取 `yss-project.yaml`，非法、缺失或不支持的身份直接进入迁移检查。
+2. 判断是否为模板源维护、项目实例小改动、中等变更或全新产品 / 模块。
+3. 判断 UI、API、数据、后端、前端、跨仓库和高风险影响。
+4. 从最近可信阶段恢复；不要因为当前目录存在某类文件就猜测阶段已通过。
+
+## 2. 裁剪矩阵
+
+| 类型 | 默认入口 | 必需工作 | 可记录为 `not-applicable` |
+|---|---|---|---|
+| 模板源维护 | 影响面分析 | 修改单一事实来源、按验证与审查强度分级执行证据、必要的技能投影同步、fresh verification / review | 产品 Spec、产品设计、OpenAPI、运行时代码 |
+| 小改动 | 入口分诊 | 影响面、主 tracker 同步、fresh verification | Spec、架构、原型、切片（没有触发条件时） |
+| 中等变更 | 最近可信的 Spec / 架构阶段 | Spec、功能架构、必要工程审查、父 Ticket 和切片 | 未命中的 UI、数据或 API 门禁 |
+| 全新产品 / 模块 | Discovery | Discovery、Spec、产品总体设计、功能架构、必要设计 / 契约审查、父 Ticket 和切片 | 未命中的 UI、数据或 API 门禁 |
+| 高风险变更 | 既有冻结基线 | Spec Delta、架构 / 数据 / 工程审查、契约复核、切片和回滚设计 | 与风险证据无关的门禁 |
+
+任何裁剪都必须写明原因和证据，不生成空文档。对跨仓库变更，Harness 记录必须绑定实现仓库、分支、CI、验证命令、发布顺序和回滚点；没有前端、后端或 OpenAPI 影响时显式记录 `not-applicable`。
+
+## 3. 执行与证据
+
+同一独立执行者可以在一个连续工作单元内完成相邻的实现动作，但不能替代独立审查者。阶段证据在集中 checkpoint 回写，至少包含：范围、变更文件、受影响仓库、验证命令及结果、阻塞项、人工审查点、Ticket 状态和下一步。
+
+## 4. 模板维护验证与审查强度分级
+
+本节只适用于 `template-source` 的模板、流程规则和共享 skill 维护，不降低 `project-instance` 的 Spec、OpenAPI Freeze、垂直切片或高风险工程门禁。强度由错误逃逸损失和是否改变 Agent 行为决定，不由文件所在目录单独决定。
+
+| 强度 | 权威触发项 | 最低验证证据 | Review |
+|---|---|---|---|
+| L1 | `maintenance-intensity.yaml` 的 `levels.L1.triggers` | 至少一项与变更直接相关的实际检查 | `self-check` 或显式 `human-checkpoint` |
+| L2 | `maintenance-intensity.yaml` 的 `levels.L2.triggers`，或该策略的 `default_level` | 修改前可失败的最小反例，以及本轮 fresh verification | 一名非实施者执行 `focused-independent` 聚焦审查；结论可内联 checkpoint |
+| L3 | `maintenance-intensity.yaml` 的 `levels.L3.triggers` | 完整 RED、GREEN、REFACTOR、压力场景与本轮 fresh verification | 冻结候选后执行 `formal-independent` 正式独立审查；需要时使用完整 `code-review` |
+
+判定规则：
+
+1. 等级只由 `maintenance-intensity.yaml` 计算；未给出 trigger 时使用该策略的 `default_level`，未知 trigger 必须更新策略后才可验证。
+2. 实施者可先分级，不要求 L1/L2 预批准；发现新影响时立即更新 `escalation`、重新分级并补齐证据。
+3. 发布、合并或阶段完成时按整体候选重新判定；不得把共同改变整体语义的修改拆成多个 L1/L2 规避 L3。
+4. RED 用于证明行为差异。L1 不人为构造失败；L2 可使用已有失败、最小 fixture 或现有测试修改前失败；只有行为无法确定性表达时才运行聚焦压力场景。L3 使用 `maintaining-skills` 并执行本节定义的完整 RED、GREEN、REFACTOR 和压力场景要求。
+5. 模板发布候选固定按 L3 聚合验证，但不追溯补造每个既有 L1/L2 修改的独立 RED。
+
+每个模板维护 checkpoint 使用以下轻量合同；L1/L2 可直接写入主 Ticket 或集中 checkpoint，不要求新增独立文档：
+
+```yaml
+schema_version: 1
+intensity: L1 | L2 | L3
+classification_reason: <分级理由>
+triggers: [<可观察触发项>]
+changed_assets: [<路径或资产引用>]
+verification_evidence:
+  - kind: relevant-check | counterexample | red | green | refactor | pressure-scenario | fresh-verification | focused-independent-review | formal-independent-review
+    command: <本轮实际命令或可读取证据引用>
+    result: pass
+review_mode: self-check | human-checkpoint | focused-independent | formal-independent # L2/L3 还必须在 verification_evidence 中给出对应 review 证据引用
+escalation: none | <升级原因和原等级>
+```
+
+使用 `scripts/verify-maintenance-checkpoint <file>` 或通过 stdin 传入 YAML / JSON 做只读校验。触发项 ID 与最低等级只由 `docs/process/maintenance-intensity.yaml` 维护；校验器消费该策略。未知触发项必须先更新该权威策略和场景，不能静默接受。

package/template/wiki/raw/implementation-repo-integration.md

@@ -0,0 +1,62 @@
+# 实现仓库接入与跨仓库切片绑定
+
+本文件是 Harness 仓库连接外部实现仓库的事实源。当前 `yss-spec-project-template` 与 `create-yss-spec` 的模板接管 / 同步变更属于 Harness-only 加 release-only 影响，不创建前端、后端或运行时代码目录。
+
+## 1. 接入清单
+
+每个受影响实现仓库必须登记：仓库地址、分支、代码所有者、CI 入口、测试 / 构建命令、允许写路径、回滚点和 MR / PR。没有登记记录时，先完成 onboarding，不能用本仓库目录代替实现仓库。
+
+## 1.1 Harness 内实现项目路径策略
+
+当前 Harness 明确承载运行时代码时，统一使用以下多项目布局：
+
+```text
+apps/
+├── backend/<backend-project>/
+└── frontend/<frontend-project>/
+```
+
+- `apps/backend/` 和 `apps/frontend/` 是项目容器，不是可生成的工程项目根；后端、前端项目必须分别位于 `apps/backend/<project>/`、`apps/frontend/<project>/`，多个项目按 `<project>` 目录并列。
+- `app/backend/`、`app/frontend/` 及其所有子路径均禁止作为工程生成目标；单复数差异不能被视为等价路径。
+- `allowed_write_paths`、`expected_evidence_files` 和生成器输出位置必须能回指具体项目目录；直接放开 `apps/backend/` 或 `apps/frontend/` 属于路径策略违规。
+- 外部实现仓库不要求采用 Harness 的 `apps/` 布局，但仍必须登记该仓库内的实际项目根路径；跨仓库切片的写路径不得用本 Harness 的占位路径冒充真实路径。
+
+每个 Harness 内项目至少登记 `project_type`、`project_name`、`project_root` 和 `repository_scope`。同一 Git monorepo 下的多个项目可以共用一条仓库登记，但必须逐项目列出根路径和独立验证命令；不同 Git 仓库必须分别登记。
+
+## 1.2 前端 / 后端验证命令
+
+登记和执行测试、编译时按工程类型选择命令，不要把模板源的 Node 工具链命令套到产品运行时工程。
+
+- **frontend**：依赖安装、测试、type-check 与构建优先使用 `pnpm`（例如 `pnpm test`、`pnpm type-check`、`pnpm build`）。不要默认 `npm` 或 `yarn`。
+- **backend**：校验、测试与编译优先使用项目根 `./mvnw`（例如 `./mvnw validate`、`./mvnw test`、`./mvnw package`）。不要默认裸 `mvn`。
+- Ticket、Slice Implementation Contract、CI 和 Review 证据必须写下实际执行的上述命令。既有仓库缺少 `pnpm` 或 Maven Wrapper 时，先记录受控例外、替代命令和责任人，再执行。
+- 本模板源仓库没有产品 frontend / backend 运行时；其 Node 校验仍按 `AGENTS.md` 的 Cursor Cloud 说明使用 `pnpm --dir .template-source/tooling/node`。
+
+## 2. 影响面路由
+
+| 影响面 | 必须绑定的记录 | 本变更结论 |
+|---|---|---|
+| Harness-only | change、文档路径、压力场景、fresh verification、checkpoint | required：模板仓库、CLI 仓库 |
+| release-only | release note、发布顺序、观察信号、rollback | required：模板 commit → CLI 包 |
+| backend-only | backend repo、分支、MR / PR、CI、API 影响 | `not-applicable`：无后端运行时代码 |
+| frontend-only | frontend repo、分支、lint / type-check / build | `not-applicable`：无前端运行时代码 |
+| contract-only | OpenAPI Draft / Freeze、消费者确认 | `not-applicable`：无 OpenAPI 变化 |
+
+## 3. 本变更的跨仓库合同
+
+- 模板仓库负责 `yss-project.yaml`、流程事实源、迁移指南、技能投影、模板校验脚本和快照可发布状态。
+- CLI 仓库负责 `attach`、`sync`、受管 manifest、快照 commit、metadata、迁移计划、备份 / 回滚、端到端测试和用户说明。
+- CLI 只写研发管理资产；不得创建或覆盖前后端运行时代码，不删除目标 `.git`。
+- 模板 commit 必须是 40 位不可变提交；开发测试可通过 `YSS_SPEC_TEMPLATE_REF` 覆盖，正式发布不得跟随浮动 `main`。
+
+## 4. Fresh verification 与 checkpoint
+
+模板仓库至少执行：
+
+```bash
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+scripts/verify-template
+```
+
+CLI 仓库至少执行固定 commit 的 `YSS_SPEC_TEMPLATE_REF=<pinned-commit> npm test`、`npm pack --dry-run`，并在解包后的 CLI 上验证 init、attach、sync、迁移冲突和回滚。共同发布前记录两个仓库的 commit、模板快照 hash、测试结果、独立审查结论和 rollback 路径。

package/template/wiki/raw/issue-tracker.md

@@ -0,0 +1,135 @@
+---
+tracker:
+  platform: local-markdown
+  root: docs/.scratch
+  legacy_roots:
+    - .scratch
+    - docs/requirements/tickets
+  remote_mirror: false
+---
+
+# Ticket 追踪平台：Local Markdown / GitHub / GitLab
+
+> 本文是项目 Ticket tracker 的单一事实来源。当前模板默认使用 `local-markdown`；GitHub / GitLab 只有在项目明确选择时才作为主 tracker。Git remote 是代码托管信息，不会自动覆盖显式 tracker 配置。
+
+## 当前项目配置
+
+| 字段 | 值 |
+|---|---|
+| `platform` | `local-markdown` |
+| `root` | `docs/.scratch/` |
+| `feature_layout` | 完整功能包 |
+| `remote_mirror` | 可选，默认关闭 |
+| `legacy_roots` | `.scratch/`、`docs/requirements/tickets/`（只读迁移来源） |
+
+上方 front matter 是机器可读的持久化配置；表格用于人和 Agent 阅读。初始化或迁移到 GitHub / GitLab 时，必须同时更新两处，并保留迁移记录。
+
+## 平台选择规则
+
+按以下优先级确定 Ticket tracker：
+
+1. 已写入本文件的项目配置优先；本模板默认配置为 `local-markdown`。
+2. 初始化或迁移时用户明确选择 GitHub / GitLab，则更新本文件后使用所选平台。
+3. Git remote 只用于代码托管、分支、PR / MR 和 CI；不能单独把 Ticket tracker 改成远程平台。
+4. 多个持久化配置声明不同平台时返回 `conflict`，暂停并要求迁移，不覆盖任何配置。
+5. 选定 GitHub / GitLab 但凭据或平台暂不可用时，先在 `docs/.scratch/<feature>/` 生成“待发布平台”草案；`parent-ticket.md` 保留目标平台、标记 `publication: pending` 和 `pending_publication_to`；不得自动改投另一远程平台。
+
+## Local Markdown 主 tracker
+
+Local 主 tracker 的完整功能包结构如下：
+
+```text
+docs/.scratch/<feature>/
+├── map.md
+├── discovery/
+├── spec.md
+├── spec-delta/
+├── parent-ticket.md
+├── design/
+├── api/
+├── architecture/
+├── gates/
+├── verification/
+└── issues/01-<slug>.md
+```
+
+- `parent-ticket.md` 汇总 Spec、设计、契约、门禁、阻塞边和阶段证据。
+- `issues/01-<slug>.md` 等文件是垂直切片或 Wayfinder 子 Ticket；不得把多个 Ticket 合并成一个文件。
+- 每个 Ticket 在顶部附近使用 `Status:` 记录 Matt 五态之一：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
+- 评论和对话追加在 `## Comments` 下；状态变化必须保留原因、证据引用和下一步。
+- Wayfinder 的临时子问题可以沿用 Matt 的 `Status: claimed/resolved` 工作状态；它不是交付 Ticket 的五态角色，进入正式切片前必须转换为上述五态之一。
+- Local 主 tracker 不要求远程 Ticket 存在；`ready-for-agent` 仍必须满足生命周期门禁、阻塞边关闭、实现上下文和 Slice Implementation Contract 要求。
+- YSS active 调用 `to-tickets` 时，新建垂直切片的初始 `Status:` 固定为 `ready-for-human`；只有生命周期编排器核验完整就绪公式后才能改为 `ready-for-agent`。
+- GitHub / GitLab 可以作为显式开启的镜像，在功能包中记录 URL、编号和最近同步时间；镜像失败不改变 Local 主 tracker 的权威性。
+- 根目录 `.scratch/` 与 `docs/requirements/tickets/` 是旧路径，只允许用于只读迁移检查；不再作为新 Ticket 或阶段证据的写入目录。
+- 仅发现旧路径资产时，readiness 不得进入 `ready`，必须保留 `migration_ref` 并先完成迁移；新旧路径同时存在时返回 `conflict`，不得静默覆盖或合并。
+
+## 生命周期状态同步
+
+Spec、生命周期和交付任务状态必须同步到当前主 tracker：
+
+- `local-markdown`：写入 `docs/.scratch/<feature>/`，本地文件即 Ticket 和阶段证据的权威载体。
+- `github`：使用 GitHub Issues，并在本地功能包记录 URL / 编号和最近同步时间；平台不可用时保留 `tracker: github`、`publication: pending`、`pending_publication_to: github`。
+- `gitlab`：使用 GitLab Issues，并在本地功能包记录 URL / IID 和最近同步时间；平台不可用时保留 `tracker: gitlab`、`publication: pending`、`pending_publication_to: gitlab`。
+
+所有平台都保留相同的父 Ticket、垂直切片、阻塞关系、验收标准、测试 seam、人工审查点和 `ready-for-agent` 语义。平台差异只影响存储和操作方式，不改变生命周期阶段或门禁。
+
+Git checkpoint 必须说明主 tracker、同步状态、验证命令、剩余风险和下一步。Local 主 tracker 的“已同步”表示本地功能包已更新；远程镜像只有明确启用时才需要同步。
+
+## GitLab Issues
+
+当平台为 GitLab 时，优先使用 `glab` 或项目快捷入口 `scripts/gitworks`。
+
+常用命令：
+
+- Create an issue: `glab issue create --title "..." --description "..."`
+- Read an issue: `glab issue view <iid> --comments`
+- List issues: `glab issue list --state opened`
+- Comment on an issue: `glab issue note <iid> --message "..."`
+- Apply labels: `glab issue update <iid> --label "ready-for-agent"`
+- Close an issue: `glab issue close <iid>`
+
+GitLab 相关配置和 MR / CI 工作流见 `docs/agents/gitlab-workflow-skills.md`。
+
+## GitHub Issues
+
+当平台为 GitHub 时，使用 `gh` CLI。
+
+常用命令：
+
+- Create an issue: `gh issue create --title "..." --body "..."`
+- Read an issue: `gh issue view <number> --comments`
+- List issues: `gh issue list --state open --json number,title,body,labels,comments`
+- Comment on an issue: `gh issue comment <number> --body "..."`
+- Apply or remove labels: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- Close an issue: `gh issue close <number> --comment "..."`
+
+## Local Markdown 操作
+
+- 创建或发布 Ticket：创建 `docs/.scratch/<feature>/`，按上述结构写入 `parent-ticket.md`、`spec.md` 或 `issues/NN-<slug>.md`。
+- 读取 Ticket：优先读取用户提供的 `docs/.scratch/<feature>/` 或具体 Ticket 路径；如果引用旧路径，进入迁移检查，不把旧路径当作新写入目标。
+- 更新状态：修改文件顶部的 `Status:`，并在 `## Comments` 追加原因和证据。
+- Wayfinder map：使用 `docs/.scratch/<feature>/map.md`，子 Ticket 放在 `issues/`。
+
+## Triage Surface
+
+Ticket 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平台和用户请求：
+
+- GitLab 项目：可按需读取 GitLab Issues、Merge Requests 和 Pipeline 状态。
+- GitHub 项目：可按需读取 GitHub Issues、Pull Requests 和 Actions 状态。
+- 用户只要求 issue triage 时，不主动扩展到 MR / PR。
+
+## Publishing
+
+当 skill 说 “publish to the issue tracker” 时：
+
+1. 读取本文件的 `platform` 配置。
+2. `local-markdown` 直接在 `docs/.scratch/<feature>/` 创建或更新 Ticket。
+3. `github` / `gitlab` 在对应平台创建或更新 Ticket，并在本地功能包记录 URL / 编号和最近同步时间。
+4. 选定远程平台不可用时，在 `docs/.scratch/<feature>/` 创建并标注“待发布平台”的草案；在 `parent-ticket.md` 写入 `publication: pending` 和 `pending_publication_to`，恢复后优先补同步。
+
+当 skill 说 “fetch the relevant ticket” 时：
+
+- Local Markdown：读取引用的 `docs/.scratch/<feature>/...` 文件；旧路径引用必须先经过迁移检查。
+- GitLab：使用 `glab issue view <iid> --comments`。
+- GitHub：使用 `gh issue view <number> --comments`。