create-yss-spec 2.1.11 → 2.1.13

package/template/wiki/raw/lifecycle-registry.yaml

@@ -0,0 +1,369 @@
+schema_version: 1
+registry_id: yss.lifecycle
+status: shadow
+description: >-
+  YSS 生命周期结构化事实源。Phase 1 以 shadow/check 方式派生结构表并校验漂移，
+  不切换任何运行时状态 schema 或人工批准语义。
+id_policy:
+  pattern: '^(stage|gate|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*$'
+  published_ids_immutable: true
+  baseline: docs/process/lifecycle-registry-baseline.json
+  deprecated_ids: [work-unit.fresh-verification, work-unit.independent-review]
+
+stages:
+  - id: stage.entry-triage
+    name: 入口分诊
+    goal: 确认仓库身份、问题范围和影响面。
+    exit_criteria: yss-project.yaml 合法，影响面和最近可信阶段可解释。
+  - id: stage.discovery
+    name: Discovery
+    goal: 澄清问题、用户、约束和机会。
+    exit_criteria: 问题边界、关键假设和待确认项已记录。
+  - id: stage.spec-architecture
+    name: Spec / 功能架构
+    goal: 固化解决方案和功能边界。
+    exit_criteria: Spec 基线和功能边界可审查。
+  - id: stage.product-design
+    name: 产品设计
+    goal: 在存在产品设计影响时校准页面流和状态。
+    exit_criteria: 命中的设计门禁通过；未命中项记录 not-applicable 及原因。
+  - id: stage.system-data-engineering
+    name: 系统 / 数据架构与工程契约
+    goal: 固化系统、数据、工程基线和 API 契约。
+    exit_criteria: 受影响工程契约冻结或记录无 API 影响；required 脚手架证据齐全。
+  - id: stage.ticket-formalization
+    name: Ticket 正式化
+    goal: 将冻结范围拆为可追踪的父 Ticket 和垂直切片。
+    exit_criteria: 工作单元窄、依赖清晰、验收和测试 seam 可执行。
+  - id: stage.vertical-slice-implementation
+    name: 垂直切片实现
+    goal: 以批准合同驱动 TDD 实现和跨仓库协作。
+    exit_criteria: 允许写路径、禁止模式、证据和验证命令全部满足。
+  - id: stage.verification-release-retrospective
+    name: 验证 / 发布 / 复盘
+    goal: 完成 fresh verification、发布和回顾。
+    exit_criteria: 所有命中门禁通过，人工审查点已完成，checkpoint 可追溯。
+
+evidence:
+  - id: evidence.impact-assessment
+    name: 影响面分析记录
+    description: 受影响仓库、资产、风险与最近可信阶段。
+  - id: evidence.maintenance-intensity-checkpoint
+    name: 模板维护强度 checkpoint
+    description: template-source 变更的 L1 / L2 / L3 分级、触发项、最低验证证据、review 模式和升级记录。
+  - id: evidence.repository-identity-check
+    name: 仓库身份校验结果
+    description: yss-project.yaml 的合法性与 repository_mode 裁决。
+  - id: evidence.approval-record
+    name: 人工批准记录
+    description: 对需要人工批准的 Spec、设计、契约或发布裁决的可追溯记录。
+  - id: evidence.design-review-result
+    name: 设计审查结果
+    description: API、架构或产品设计审查意见及处理结果。
+  - id: evidence.prototype-review-result
+    name: 原型评审结果
+    description: 低保真页面、流程、状态与 API 反推的独立评审结论和阻断项。
+  - id: evidence.antd-cli-validation
+    name: Ant Design CLI 校验证据
+    description: 设计语言、组件、demo、token、semantic 与 lint 的实际 CLI/目标版本和可读输出引用。
+  - id: evidence.browser-prototype-verification
+    name: 浏览器原型验证证据
+    description: 高保真原型的非空渲染、主流程、异常状态、视口和控制台验证记录。
+  - id: evidence.prototype-confirmation
+    name: 原型用户确认记录
+    description: 高保真原型、验证清单和进入下游阶段范围的人工确认结论。
+  - id: evidence.openapi-draft-review
+    name: OpenAPI Draft 审查记录
+    description: P0、错误、分页、幂等和契约测试审查记录。
+  - id: evidence.contract-approval
+    name: Slice 合同批准记录
+    description: 生命周期编排器批准且已持久化的当前版本合同引用。
+  - id: evidence.yss-skill-execution-result
+    name: YSS Skill Execution Result
+    description: 专项 skill 的合同版本、写入、验证、延期 seam 与偏离证据。
+  - id: evidence.frontend-implementation-verification
+    name: 前端实现还原验证证据
+    description: UI 实现相对冻结原型和 Spec 的桌面/窄屏视觉、状态、交互、控制台与 pnpm 验证记录。
+  - id: evidence.fresh-verification
+    name: Fresh Verification 记录
+    description: 本轮实际执行的验证命令、结果和时间。
+  - id: evidence.checkpoint-and-rollback
+    name: Checkpoint 与回滚点
+    description: 可追溯的变更边界、发布记录和恢复动作。
+
+gates:
+  - id: gate.repository-identity-valid
+    name: 仓库身份校验
+    stage: stage.entry-triage
+    trigger: 每次进入流程。
+    evidence: [evidence.repository-identity-check]
+  - id: gate.spec-baseline-approved
+    name: Spec 基线批准
+    stage: stage.spec-architecture
+    trigger: 新功能、行为变化或范围扩大进入 Spec 基线。
+    evidence: [evidence.approval-record]
+  - id: gate.prototype-reviewed
+    name: 原型评审
+    stage: stage.product-design
+    trigger: 命中产品设计影响，且低保真页面、流程、状态或 API 反推需要独立评审。
+    evidence: [evidence.prototype-review-result]
+  - id: gate.prototype-verified
+    name: 高保真原型验证
+    stage: stage.product-design
+    trigger: 需要高保真 HTML 原型进行视觉与交互校准。
+    evidence: [evidence.antd-cli-validation, evidence.browser-prototype-verification]
+  - id: gate.user-confirmation
+    name: 用户确认
+    stage: stage.product-design
+    trigger: 产品设计影响尚未被人工确认。
+    evidence: [evidence.prototype-confirmation]
+  - id: gate.openapi-draft-reviewed
+    name: OpenAPI Draft Review
+    stage: stage.system-data-engineering
+    trigger: 有 API 影响且 Draft 已生成。
+    evidence: [evidence.openapi-draft-review]
+  - id: gate.design-reviewed
+    name: 设计审查
+    stage: stage.system-data-engineering
+    trigger: API 或架构影响。
+    evidence: [evidence.design-review-result]
+  - id: gate.openapi-frozen
+    name: OpenAPI Freeze
+    stage: stage.system-data-engineering
+    trigger: API 进入实现。
+    evidence: [evidence.approval-record]
+  - id: gate.engineering-baseline-accepted
+    name: 工程基线
+    stage: stage.system-data-engineering
+    trigger: 后端、前端或高风险工程变化。
+    evidence: [evidence.fresh-verification]
+  - id: gate.architecture-reviewed
+    name: 架构审查
+    stage: stage.system-data-engineering
+    trigger: 高风险或跨边界变化。
+    evidence: [evidence.design-review-result]
+  - id: gate.slice-contract-approved
+    name: Slice Implementation Contract 批准
+    stage: stage.ticket-formalization
+    trigger: Agent 进入实现；脚手架完成后每个后续生成代码工作单元。
+    evidence: [evidence.contract-approval]
+  - id: gate.slice-ready-for-agent
+    name: 垂直切片实现就绪
+    stage: stage.ticket-formalization
+    trigger: 垂直切片具备直接实现条件。
+    evidence: [evidence.contract-approval, evidence.approval-record]
+  - id: gate.frontend-implementation-verified
+    name: 前端实现还原验证
+    stage: stage.verification-release-retrospective
+    trigger: UI 影响切片完成实现并准备合并、发布或阶段完成。
+    evidence: [evidence.frontend-implementation-verification]
+  - id: gate.release-ready
+    name: 发布就绪
+    stage: stage.verification-release-retrospective
+    trigger: 合并、发布或阶段完成。
+    evidence: [evidence.fresh-verification, evidence.checkpoint-and-rollback]
+    requires_gates: [gate.frontend-implementation-verified]
+
+artifacts:
+  - id: artifact.impact-assessment
+    name: 影响面分析
+    stage: stage.entry-triage
+    trigger: 每次变更。
+  - id: artifact.discovery-record
+    name: Discovery 记录
+    stage: stage.discovery
+    trigger: 新问题或边界不清。
+  - id: artifact.spec
+    name: Spec
+    stage: stage.spec-architecture
+    trigger: 新功能、行为变化或范围扩大。
+  - id: artifact.product-overview
+    name: 产品总体设计
+    stage: stage.spec-architecture
+    trigger: 进入 Spec 基线。
+  - id: artifact.functional-architecture
+    name: 功能架构
+    stage: stage.spec-architecture
+    trigger: 新模块或跨边界变化。
+  - id: artifact.interaction-spec
+    name: 交互说明
+    stage: stage.product-design
+    trigger: 命中产品设计影响。
+  - id: artifact.low-fidelity-prototype
+    name: 低保真原型
+    stage: stage.product-design
+    trigger: 命中产品设计影响。
+  - id: artifact.state-matrix
+    name: 状态矩阵
+    stage: stage.product-design
+    trigger: 存在状态流转、异常或恢复。
+  - id: artifact.high-fidelity-html-prototype
+    name: 高保真 HTML 原型
+    stage: stage.product-design
+    trigger: 需要视觉与交互校准。
+  - id: artifact.prototype-review
+    name: 原型评审记录
+    stage: stage.product-design
+    trigger: 命中 gate.prototype-reviewed。
+  - id: artifact.prototype-confirmation
+    name: 原型确认记录
+    stage: stage.product-design
+    trigger: 命中 gate.user-confirmation。
+  - id: artifact.openapi-draft
+    name: OpenAPI Draft
+    stage: stage.system-data-engineering
+    trigger: 有 API 影响。
+  - id: artifact.openapi-freeze-record
+    name: OpenAPI Freeze 记录
+    stage: stage.system-data-engineering
+    trigger: API 进入实现。
+  - id: artifact.data-architecture
+    name: 数据架构
+    stage: stage.system-data-engineering
+    trigger: 数据模型、存储或一致性变化。
+  - id: artifact.engineering-baseline
+    name: 工程基线记录
+    stage: stage.system-data-engineering
+    trigger: 后端、前端或高风险工程变化。
+  - id: artifact.architecture-review
+    name: 架构审查记录
+    stage: stage.system-data-engineering
+    trigger: 高风险或跨边界变化。
+  - id: artifact.spec-delta
+    name: Spec Delta
+    stage: stage.spec-architecture
+    trigger: 已有冻结 Spec 的高风险行为变化。
+  - id: artifact.parent-ticket
+    name: 功能父 Ticket
+    stage: stage.ticket-formalization
+    trigger: 每个进入追踪的功能。
+  - id: artifact.vertical-slice-ticket
+    name: 垂直切片 Ticket
+    stage: stage.ticket-formalization
+    trigger: 进入实现前。
+  - id: artifact.slice-implementation-contract
+    name: Slice Implementation Contract
+    stage: stage.ticket-formalization
+    trigger: Agent 进入实现。
+  - id: artifact.frontend-implementation-plan
+    name: 前端实现还原计划
+    stage: stage.ticket-formalization
+    trigger: UI 影响切片提升 ready-for-agent 前。
+  - id: artifact.frontend-implementation-verification
+    name: 前端实现还原验证记录
+    stage: stage.verification-release-retrospective
+    trigger: UI 影响切片完成实现并准备合并、发布或阶段完成。
+  - id: artifact.retrospective
+    name: 复盘记录
+    stage: stage.verification-release-retrospective
+    trigger: 发布后或阶段性完成后满足复盘触发条件。
+
+work_units:
+  - id: work-unit.entry-triage
+    name: 入口分诊
+    scope: template-source
+    input: 用户请求、仓库身份。
+    output: 影响面与最近可信阶段。
+    completion: 身份和影响面可解释。
+  - id: work-unit.ssot-update
+    name: 单一事实源更新
+    scope: template-source
+    input: 变更合同。
+    output: 权威文档或脚本。
+    completion: 其他投影可由脚本生成。
+  - id: work-unit.skill-projection-sync
+    name: 技能投影同步
+    scope: template-source
+    input: .agents/skills。
+    output: Agent root 投影、skills lock。
+    completion: --check 通过。
+  - id: work-unit.template-snapshot-build
+    name: 模板快照构建
+    scope: template-source
+    input: 固定模板 commit。
+    output: CLI bundled snapshot。
+    completion: commit 与 tree hash 可追踪。
+  - id: work-unit.attach-sync-integration
+    name: attach / sync 集成
+    scope: template-source
+    input: 目标仓库、dry-run 计划。
+    output: 受管资产和 metadata。
+    completion: 验证通过或完整回滚。
+  - id: work-unit.intensity-aware-verification
+    name: 分级 Fresh verification
+    scope: template-source
+    input: 变更仓库、强度分级与对应最低证据。
+    output: 命令输出与证据。
+    completion: L1 相关检查、L2 最小反例与 fresh verification、L3 完整 RED / GREEN / REFACTOR 与 fresh verification 按命中等级通过。
+  - id: work-unit.intensity-aware-review
+    name: 分级审查
+    scope: template-source
+    input: 变更 diff、强度分级与验证证据。
+    output: L1 self-check / 人工 checkpoint、L2 聚焦独立审查或 L3 正式独立审查结论。
+    completion: 已按命中等级完成审查且无未处理阻断项；L1 不强制独立 reviewer。
+  - id: work-unit.release-and-rollback
+    name: 发布与回滚
+    scope: template-source
+    input: 已审查 commit。
+    output: release note、观察信号、回滚点。
+    completion: 两仓库顺序和恢复动作明确。
+  - id: work-unit.discovery-opportunity
+    name: 机会调研
+    scope: project-instance
+    input: 用户问题、市场/竞品事实需求和现有上下文。
+    output: Discovery 机会结论、证据、替代方案和关键假设。
+    completion: 机会继续/停止建议可审查；事实已 research 或记录为假设。
+  - id: work-unit.discovery-requirements
+    name: 需求分析
+    scope: project-instance
+    input: 机会结论、用户反馈和领域词汇。
+    output: 用户、MVP、非目标、成功标准、测试 seam 和未决项。
+    completion: frontier 清空；用户确认；无 runnable blocker。
+  - id: work-unit.spec-synthesis
+    name: Spec 综合
+    scope: project-instance
+    input: 已确认的 Discovery 记录和测试 seam。
+    output: Spec、产品总体设计和功能架构。
+    completion: Spec 内容完整并进入 ready-for-human；下游推进仍需 gate.spec-baseline-approved。
+  - id: work-unit.prototype-design
+    name: 原型设计与验证
+    scope: project-instance
+    input: Spec、产品设计影响和状态矩阵。
+    output: 交互说明、低/高保真原型、评审、AntD CLI 和浏览器证据。
+    completion: 原型评审、高保真验证和用户确认门禁均通过。
+  - id: work-unit.technical-analysis
+    name: 技术分析与契约冻结
+    scope: project-instance
+    input: Spec、原型、API/数据/工程影响面。
+    output: OpenAPI、数据架构、工程基线、架构审查和 Slice 合同草案。
+    completion: 命中契约已冻结；无 API 影响有可读记录；工程基线通过。
+  - id: work-unit.ticket-decomposition
+    name: 垂直切片 Ticket 正式化
+    scope: project-instance
+    input: 冻结 Spec、设计、契约和阻塞关系。
+    output: 功能父 Ticket、垂直切片和批准的 Slice Implementation Contract。
+    completion: 切片可独立验证；生命周期复算后才能 ready-for-agent。
+  - id: work-unit.slice-implementation
+    name: 垂直切片实现
+    scope: project-instance
+    input: 当前版本 Slice Implementation Contract 和允许写路径。
+    output: 前后端实现、TDD 和 YSS Skill Execution Result。
+    completion: 行为通过 `behavior-tdd`；UI 影响完成还原验证计划；无 drift/violation。
+  - id: work-unit.frontend-implementation-verification
+    name: 前端实现还原验证
+    scope: project-instance
+    input: 冻结原型、状态矩阵、实现候选和视觉验收用例。
+    output: 桌面/窄屏视觉、状态、交互、console 和 pnpm 验证证据。
+    completion: 关键场景无未解释差异；独立 Reviewer 通过 UI fidelity 轴。
+  - id: work-unit.code-review
+    name: 独立代码审查与验证
+    scope: project-instance
+    input: 不可变候选快照、Spec、Ticket、合同和执行结果。
+    output: Standards、Spec、UI fidelity 三轴 Review 与 fresh verification。
+    completion: findings 已处理；修复后重新捕获候选并全量复审。
+  - id: work-unit.release-and-retrospective
+    name: 发布与复盘
+    scope: project-instance
+    input: 已审查候选、发布窗口和回滚点。
+    output: 发布/回滚证据和复盘记录。
+    completion: 人工发布裁决、fresh verification 和治理回流均完成。

package/template/wiki/raw/maintenance-intensity.yaml

@@ -0,0 +1,25 @@
+schema_version: 1
+default_level: L2
+levels:
+  L1:
+    triggers:
+      - textual-only
+      - link-only
+      - deterministic-projection
+  L2:
+    triggers:
+      - local-rule
+      - template-structure
+      - non-core-validator
+  L3:
+    triggers:
+      - lifecycle-gate
+      - ticket-state
+      - permission-boundary
+      - generation-semantics
+      - release-semantics
+      - cross-repo-contract
+      - core-validator
+      - historical-important-escape
+      - aggregate-behavior-change
+      - release-candidate

package/template/wiki/raw/skills-lock-names.md

@@ -0,0 +1,92 @@
+# skills-lock names
+
+Derived names only. Do not copy hashes, paths, or the lock file.
+
+## shared
+
+- `alibaba-java-code-style`
+- `ask-matt`
+- `code-review`
+- `codebase-design`
+- `competitive-intelligence`
+- `cross-repo-implementation-routing`
+- `diagnosing-bugs`
+- `dispatching-parallel-agents`
+- `domain-modeling`
+- `grill-me`
+- `grill-with-docs`
+- `grilling`
+- `handoff`
+- `high-fidelity-html-prototype`
+- `implement`
+- `implementation-repo-onboarding`
+- `improve-codebase-architecture`
+- `llm-wiki`
+- `lombok`
+- `loop-me`
+- `maintaining-skills`
+- `mapstruct`
+- `migrate-to-shoehorn`
+- `prototype`
+- `prototype-review`
+- `research`
+- `resolving-merge-conflicts`
+- `scaffold-exercises`
+- `setup-matt-pocock-skills`
+- `setup-pre-commit`
+- `setup-ts-deep-modules`
+- `tdd`
+- `teach`
+- `to-questionnaire`
+- `to-spec`
+- `to-tickets`
+- `triage`
+- `using-git-worktrees`
+- `wait-what`
+- `wayfinder`
+- `writing-beats`
+- `writing-for-agents`
+- `writing-fragments`
+- `writing-shape`
+- `yss-api-integration`
+- `yss-application`
+- `yss-audit-log`
+- `yss-cache`
+- `yss-components`
+- `yss-ddd-scaffold-generator`
+- `yss-design-system`
+- `yss-distributed-id`
+- `yss-domain`
+- `yss-dto`
+- `yss-excel-mvc`
+- `yss-exception`
+- `yss-formily`
+- `yss-formily-schema-generator`
+- `yss-frontend-scaffold-generator`
+- `yss-hook`
+- `yss-microapp-commit`
+- `yss-mybatis`
+- `yss-openapi-draft-review`
+- `yss-openapi-governance`
+- `yss-page-module-development`
+- `yss-product-lifecycle`
+- `yss-prototype-stage`
+- `yss-repository`
+- `yss-resilience4j`
+- `yss-router`
+- `yss-security-algorithm`
+- `yss-source-index`
+- `yss-ui`
+- `yss-up-springboot3`
+- `yss-use-table-height`
+- `yss-use-tree-height`
+- `yss-userinfo`
+- `yss-validation`
+- `yss-web-controller`
+
+## platform
+
+### `.codex/skills`
+
+- `data-analytics`
+- `product-design`

package/template/wiki/raw/skills-maintenance.md

@@ -0,0 +1,90 @@
+# Skills 维护说明
+
+本文说明项目级 skills 的权威目录、投影方式、锁文件语义和升级验证。Agent 实际加载的入口仍是各目录中的 `SKILL.md`。
+
+## 权威内容与投影
+
+- `.agents/skills` 是跨 Agent 共享技能的唯一权威内容。
+- `.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
+- Cursor 的契约运行时入口是 `.cursor/skills`。若客户端同时枚举 `.claude/skills`，仍以 `.cursor/skills` 为 Cursor 投影契约，不得把两套同名 skill 解释为两个来源。
+- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；该文件当前为 shadow，不改变 Agent 实际发现列表，也不允许 Router 按其裁剪闭包。
+- 只属于某个平台的 skill 继续保留在对应 root，并由 `skills-lock.json` 的 `platform` 分组记录。
+- 共享技能投影可以是指向权威目录的符号链接，也可以是完整同步副本；`scripts/sync-skills --check` 会检查链接目标或完整目录哈希。
+
+## 来源与锁定
+
+| 来源 | 固定版本 / 路径 | 用途 |
+|---|---|---|
+| `mattpocock/skills` | `0ab1b63a410a03d3627979a109c8695de27af954` / `skills/engineering` 及锁文件记录的关联路径 | 通用工程流程及关联 skills |
+| `anthropics/knowledge-work-plugins` | `sales/skills/competitive-intelligence` | 竞品与市场事实研究 |
+| 项目本地 | `.agents/skills` 或平台专属 root | YSS 适配与项目治理 skills |
+
+`skills-lock.json` 是技能清单、来源、上游哈希、当前有效内容哈希和投影目标的权威记录：
+
+- `upstreamHash`：能够追溯时记录未经项目适配的上游内容哈希。
+- `effectiveHash`：当前实际生效的完整 skill 目录树哈希。
+- `targets`：权威内容应投影到的 Agent roots。
+
+项目允许按 YSS 流程适配上游 skill，但必须同时保留可追溯的上游信息和适配后的有效哈希。
+
+当前 Matt 快照为 `0ab1b63a410a03d3627979a109c8695de27af954`。`ask-matt` 的关联入口包括 `to-questionnaire`、`wait-what`、`writing-for-agents` 和 `PHASE-BOUNDARIES.md`；这些支持文件随共享 skill 目录一起计算 `effectiveHash`，不得单独投影或维护。
+
+本轮升级还将生命周期适配固定为：阶段边界只写可选 `phase_boundary` 证据；`to-questionnaire` 使用 `external-input-required` 暂停并在答案回流后重新分类影响面；Matt `prototype` 使用 `prototype/<name>` 分支和单文件 HTML，YSS 高保真原型继续执行 Prototype Review、AntD CLI 校验和用户确认。人工 checkpoint 与 `diagnosing-bugs` 的输出必须脱敏，`wait-what` 不改变生命周期状态。
+
+## 维护流程
+
+1. 在临时目录读取或下载锁定来源，不直接覆盖工作区。
+2. 只在 `.agents/skills/<skill-name>/` 修改共享技能；平台专属技能只在所属 root 修改。
+3. 创建、修改或退役 skill 时使用 `maintaining-skills`，并先按 `docs/process/harness-process-tailoring.md` 判定验证与审查强度：L1 执行相关检查，L2 记录最小反例和 fresh verification，L3 记录完整 RED 基线、压力场景、GREEN 结果和 REFACTOR 检查。未定义分级的外部仓库按实际风险执行结构校验和针对性行为验证，不强制为每次普通修改构造失败基线。
+4. 生成共享投影并更新锁文件：
+
+   ```bash
+   scripts/sync-skills
+   scripts/update-skill-lock
+   ```
+
+   若来源来自可访问的 Matt checkout，还应显式校验锁定 revision 与每个上游目录哈希：
+
+   ```bash
+   scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
+   ```
+
+   新增共享 skill 时先显式登记：`scripts/update-skill-lock --add=<skill-name>`；新增平台专属 skill 使用 `scripts/update-skill-lock --add-platform=<root>:<skill-name>`。脚本不会把工作区中偶然出现的未跟踪目录自动纳入发布清单。
+
+5. 执行发布阻断校验：
+
+   ```bash
+   scripts/verify-template
+   ```
+
+   若模板维护引入或更新分发到实例的 Node 工具，先在 `.template-source/tooling/node/` 使用 `pnpm install --frozen-lockfile`，再运行 `pnpm build:vendor` 与 `pnpm check:vendor`；实例门禁不得安装依赖或重建 vendor。运行时、公开入口和跨仓回滚规则以 `.template-source/adr/0009-zero-install-node-tooling-runtime.md` 及对应契约为准。
+
+6. 需要重新加载技能的客户端在变更落地后重启或刷新项目。
+
+## 单独检查
+
+```bash
+scripts/sync-skills --check
+scripts/update-skill-lock --check
+# 可选：对照锁文件中的 mattpocock/skills revision 与上游目录哈希
+scripts/verify-upstream-skill-source --source-root <matt-skills-checkout>
+```
+
+前者检查所有共享投影是否指向或匹配权威内容，后者检查 `skills-lock.json` 是否与当前完整目录树一致。过时技能不会保留兼容别名；旧版项目按 `docs/user-guide/规格与任务迁移指南.md` 一次性迁移。
+
+## skills.sh 公开发布
+
+YSS 技能的公开发布仓库为 `iloveZzz/yss-spec-dev-skills`，它是本模板 `.agents/skills` 的单向发布投影，不是新的权威来源。
+
+- `yss-public-skills.json` 冻结允许公开的 YSS 技能清单；新增技能必须显式加入该清单。
+- `scripts/export-yss-skills --output <目录>` 从 canonical skills 生成公开目录；`--check --output <目录>` 只验证已有导出，不写入文件。
+- 公开仓库只包含 `skills/`、README、许可证、`skills.sh.json` 和发布校验；不得复制 `AGENTS.md`、`CONTEXT.md`、`skills-lock.json` 或各 Agent 投影目录。
+- 导出器会将本机绝对路径、Agent root 和模板内部路径转换为公开可移植形式，并阻断重复 skill 名、疑似凭据、符号链接和失效仓库内链接。
+- 发布顺序为：同步 canonical projections → 更新 lock → `scripts/verify-template` → 导出并检查 → 独立审查 → 在 `yss-spec-dev-skills` 提交人工 PR。不得从目标仓库反向覆盖 `.agents/skills`。
+- skills.sh 通过 `npx skills add iloveZzz/yss-spec-dev-skills` 的安装遥测自动发现技能，不需要手工注册；遥测可用 `DISABLE_TELEMETRY=1` 或 `DO_NOT_TRACK` 关闭。
+
+已退休、personal 或由 YSS 有意排除的条目（`design-an-interface`、`qa`、`request-refactor-plan`、`ubiquitous-language`、`edit-article`、`obsidian-vault`、`writing-great-skills`、`web-design-engineer`、`web-video-presentation`、`wireframe-prototype`、`wizard`、`git-guardrails-claude-code`、`claude-handoff`、`batch-grill-me`）不再进入 `.agents/skills`、六个共享投影根或 `skills-lock.json`。其中 `wizard` 是最新上游仍存在但 YSS 当前有意排除的人工步骤技能，不应描述为上游已退休。迁移时使用 `codebase-design`、`triage + to-tickets`、`to-spec + improve-codebase-architecture`、`domain-modeling`、`product-design:index`、普通人工 checkpoint 或 `handoff` 等现行路由，不创建兼容目录。
+
+## 外部工作流工具
+
+维护者可按需使用本机的 `gitlab-workflow`、`glab`、`gh` 或 `scripts/gitworks`。这些工具不是共享技能投影的一部分；平台选择与发布规则见 `docs/agents/issue-tracker.md`。

package/template/wiki/raw/spec-template.md

@@ -9,7 +9,7 @@ owner: ai
 
 ## 功能父 Ticket
 
-<GitHub / GitLab Ticket 链接或本地待发布 Ticket 路径>
+<Local：`docs/.scratch/<feature>/parent-ticket.md`；GitHub / GitLab：Issue URL / 编号>
 
 ## 问题陈述
 
@@ -34,7 +34,6 @@ owner: ai
 | 类别 | 需求 | 目标 |
 |---|---|---|
 | 性能 | | |
-| 安全 | | |
 | 可靠性 | | |
 
 ## 验收标准
@@ -50,7 +49,7 @@ owner: ai
 - 功能域与模块边界：
 - MVP / 非目标：
 - UI 影响：是 / 否
-- 产品总体设计：`docs/design/<feature>-product-overview-design.md`
+- 产品总体设计：`docs/.scratch/<feature>/design/<feature>-product-overview-design.md`
 
 > 只有存在 UI 影响时，才强制低保真页面草图、状态矩阵、高保真 HTML 原型和用户确认；否则记录 `not-applicable` 及原因。
 
@@ -58,7 +57,7 @@ owner: ai
 
 - [ ] 无
 - [ ] 需要 API 影响分析 / 契约草案
-- [ ] 需要 review-only OpenAPI Draft：`docs/api/specs/<feature>.yaml`
+- [ ] 需要 review-only OpenAPI Draft：`docs/.scratch/<feature>/api/<feature>.yaml`
 
 > OpenAPI Draft 在 OpenAPI Freeze 前仅用于评审和架构反审，不作为实现或生成客户端的稳定契约。
 

package/template/wiki/raw/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage 标签
+
+本文定义 Agent 分诊时使用的五种标准角色，以及它们在当前 Ticket tracker 中对应的标签。
+
+| 标准角色 | Tracker 标签 | 含义 |
+| --- | --- | --- |
+| `needs-triage` | `needs-triage` | 等待维护者评估 Ticket |
+| `needs-info` | `needs-info` | 等待报告者补充信息 |
+| `ready-for-agent` | `ready-for-agent` | 必要门禁已通过、阻塞边已清除，可由 Agent 直接实现的垂直切片 Ticket |
+| `ready-for-human` | `ready-for-human` | Spec、设计、契约草案或其他资产需要人工审查、判断或特权访问 |
+| `wontfix` | `wontfix` | 不会处理 |
+
+当 skill 提及某个标准角色时，使用表中对应的 Tracker 标签。
+
+Local Markdown 主 tracker 不调用远程标签：在 Ticket 文件顶部使用同名 `Status:` 值记录标准角色。Wayfinder 的 `claimed` / `resolved` 仅是临时工作状态，不属于本表五态；进入交付 Ticket 前必须转换为标准 `Status:`。