create-yss-spec 3.5.3 → 3.5.5

package/template/.cursor/skills/diagnosing-bugs/references/investigation.md

@@ -0,0 +1,49 @@
+# 诊断调查与探针
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。Skill 自带的 bin/scripts 命令从 Skill 根目录执行；明确注明 repository root 的包装命令仍从项目根目录执行。
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Minimize further only while it removes meaningful uncertainty. Preserve representative conditions; do not spend effort proving every remaining element essential when the cause can already be tested directly.
+
+## Phase 3 — Hypothesise
+
+Generate enough competing falsifiable hypotheses to distinguish plausible causes. For a clear, bounded defect one directly testable hypothesis can be sufficient; complex or ambiguous failures need alternatives, without a fixed count.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.

package/template/.cursor/skills/git-commit-core/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/template/.cursor/skills/maintaining-skills/references/authoring.md

@@ -7,12 +7,16 @@ Use this reference when changing a skill's trigger, prompt structure or runtime
 - Front-load the distinctive capability and triggering task. Put implementation inventories, output formats and background in the body. Avoid universal triggers such as every code edit or every database mention.
 - Keep a working narrow description unchanged when shortening would lose its boundary. There is no universal character or line limit in this guidance.
 - For explicitly invoked compatibility entries, preserve existing invocation metadata and include `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for Codex. Keep any existing interface and dependency metadata. This policy controls implicit selection, not authorization to perform external actions.
+- Where the YSS registry opts into `invocation_contract.runtime_metadata_version: 1`, validate Codex `agents/openai.yaml` against the effective registry mode: `user` requires boolean `allow_implicit_invocation: false`; `model`/`both` permit the host default (omitted) or explicit `true`. Keep internal dependencies explicit-only, and retain action authorization in the public caller. Older registries without this marker remain compatible; a discovered entry is not proof of actual selection or enforcement on another host.
 - Keep source, projection and compatibility entry identities distinct. Do not delete generated runtime roots just because the current client also discovers the canonical root.
 
 ## Instructions
 
 - State the necessary inputs, result, fragile invariants and completion evidence. Let the agent choose routine steps within the authorized scope.
 - Put conditional examples and detailed variants in named reference sections; explain when to read each. Keep essential permission and correctness constraints visible in the entry.
+- Audit entry characters/bytes as well as lines: dense paragraphs can cost more context than a longer code example. Use size to prioritize inspection, not as a universal acceptance limit or a proxy for measured token savings.
+- Make each reference reachable from the entry with a concrete task condition. Do not replace a large entry with an instruction to read every reference; preserve the smallest useful route for the current task, including its prerequisites and stop conditions.
+- When moving detail, preserve conditions and examples, repair relative links and heading references, and state the command working directory. Check profile adaptations and packaged copies as well as the canonical entry; entry reduction alone does not prove lower total task context or better Agent decisions.
 - Reference the owning repository rule rather than repeating a second policy. Remove unavailable tool names and unregistered skill dependencies; describe the capability and fallback instead.
 - Preserve support for other models and runtimes. Do not encode a model name, reasoning effort or assumed tool availability into shared workflow rules unless the task is specifically a runtime configuration change.
 
@@ -25,3 +29,5 @@ Run the checks warranted by the change and the repository policy. After success,
 ## Sources
 
 Authoring guidance reviewed on 2026-09-16: [OpenAI's Astra Skills guidance](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra) and [Codex Skills documentation](https://developers.openai.com/codex/skills). These support concise discovery and conditional loading; repository-specific gates remain local decisions.
+
+本仓模板维护的定向反例与历史兼容按 `.template-spec/process/harness-process-tailoring.md` 及其引用的维护强度策略执行；不要把自检级别替代为新的通用人工批准要求。

package/template/.cursor/skills/prototype-review/SKILL.md

@@ -30,6 +30,8 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 | State coverage | loading, empty, error, readonly, disabled, no-permission, conflict, and dirty-form states are addressed or explicitly not applicable |
 | State transition coverage | 每个状态列出进入事件、允许转换、guard、动作和退出路径；不存在只能进入不能退出的状态 |
 | Permission coverage | Hidden vs disabled vs rejected actions are clear |
+| Content hierarchy | 必需内容有任务优先级、长度/空值变化与区域；动作有可见结果，来源与 actionKey 引用现有合同 |
+| Conditional comparison | 仅命中不确定性时比较；交互候选有实质差异且同输入/保真，标准先于选择，保留选择代价与用户决定引用 |
 | Data coverage | Visible fields, filters, sort, pagination, forms, tables, drawers, modals, and audit/version data are listed |
 | API implication | Request/response fields, error structure, pagination/filtering, permissions, and concurrency implications can be drafted |
 | Action contract coverage | Every primary page action has an `actionKey`, endpoint or explicit non-goal, permission behavior, state transition, idempotency/concurrency rule, and error codes |
@@ -43,6 +45,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - If the prototype hides business rules behind generic text such as "校验失败", require field-level errors and recovery behavior.
 - If a page shows a user action but the OpenAPI implication list lacks endpoint/non-goal mapping, block prototype profile selection, Spec calibration, or OpenAPI Draft.
 - If Spec P0 scope says a user can manage or configure an object but the design only shows read-only data, block until the write path or scope downgrade is explicit.
+- 对比方案仅换色、隐藏关键状态或增加未批准业务规则时，指出受影响的具体决策；审美偏好与未来建议进入 Non-Blocking Suggestions，不替代行为缺陷判断。
 - If a state is intentionally out of scope, record why and who owns the decision.
 - If implementation dependencies are unclear, route to `yss-implementation-contract-compiler` only after the prototype passes this review.
 
@@ -75,3 +78,11 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 ```
 
 Use `.template-spec/design/templates/prototype-review-checklist.md` when writing a persistent review artifact.
+
+评审恢复路径时区分“保留草稿”“重新加载”“合并”，按既有状态矩阵核对最终字段和再次提交结果。候选初始化确认只证明声明的初始输入，不能替代实际操作；发现仅出现按钮但结果未核验时记为证据缺口。
+
+涉及组件组合、分页/选择、字段错误或浮层时，按需读取 [组件检查与六轴 QA](references/component-qa.md)，并入现有评审，不另建门禁。
+
+涉及企业多页工作区时，按原型技能 `references/enterprise-workspace.md` 核对导航退出、dirty 页签关闭、跨页保留与场景重置的区别，并检查隐藏页浮层清理和窄屏可达性；工程证据、视觉观察及偏好建议分别记录。
+
+涉及搜索选择或日期范围时，按 [组件检查](references/component-qa.md) 核对搜索词/已选值、半完成范围、取消保值与隐藏浮层焦点；研究问题按可观察任务交接，不把模拟结果记成用户证据。

package/template/.cursor/skills/prototype-review/references/component-qa.md

@@ -0,0 +1,32 @@
+# 组件检查并入现有评审与六轴 QA
+
+低保真只核对任务、数据、入口/出口、状态、选择范围及恢复规则，不要求提前确定组件外观。高保真消费已评审行为；组件接入导致业务行为变化时回到受影响的低保真评审。
+
+| 现有 QA 轴 | 本轮组件检查 |
+|---|---|
+| visual | 当前 DESIGN 角色与计算样式；compact/comfortable、正文、Field/InputGroup 内外边框；文字及状态对比度；同内容、同状态、同视口前后截图 |
+| layout | 分组、筛选/结果/选择反馈；详情侧栏和操作区；390px 摘要/单列；表格内滚动；保持项不得自动重排 |
+| interaction | 分页与筛选/空态/跨页选择一致；菜单禁用和执行结果；失败重试、取消确认、完整重载及再次保存；切换/重置清除临时状态 |
+| content | 标签/帮助/错误关联；权限与部分失败原因持续显示；加载/空态下一步明确；未模拟动作禁用并说明 |
+| accessibility | 纯键盘、首错焦点；Sheet/Dialog 标题、Escape、关闭与焦点返回；菜单 Arrow/Enter/Escape；实际点击区域及相邻间距；200% 浏览器缩放；减少动效计算结果 |
+| cross-platform | Chromium 两个核心视口，WebKit 关键链路；独立目录断网 file://；资源、console、深链接与非法场景 |
+
+每项记录通过/失败/未执行/有理由的不适用。行为缺陷（例如草稿丢失、禁用项能执行）必须修复；视觉观察绑定规范或保持项和证据；偏好建议保留为非阻断建议。控件高度、组件库默认能力、初始化消息或 smoke 通过均不能替代适用检查。工程结论与用户视觉确认分开。
+
+## Vue 与组件真实性
+
+核对 `component_basis=vue-shadcn-prebuilt`、固定 shadcn-vue revision、Vue/Reka 依赖和实际使用源码清单；不能把 React 或原生 select 称为 Vue 组件。产品下拉、菜单和浮层优先实测组件交互；原生例外记录目的。Select 验证键盘选中、Escape、焦点返回和触发器宽度；Sheet 验证完整标题说明、取消路径和来源焦点。场景切换后不得遗留 Teleport 浮层。Blocks 的新行为与依赖必须有当前任务依据。
+
+## 企业多页工作区
+
+并入既有六轴：visual 核对 workspace 角色与标题层级；layout 检查流式工作区、空详情不占位、主/详情/表格滚动和窄屏 Sheet；interaction 覆盖导航同步、页签去重/关闭回退、dirty 取消/放弃、跨页保留和全量重置；content 明确内存草稿与来源场景；accessibility 检查页签键盘、隐藏页及 Teleport 不可抢焦点、关闭与详情返回；cross-platform 复验桌面/平板/窄屏及离线。发现草稿丢失、非法入口回退或未执行关键链路时保持阻塞。
+
+页面 Tag 补查：导航语义和 aria-current、按钮不嵌套、当前/悬停/焦点区分、方向键不自动切页、Enter/空格激活、Delete 和关闭按钮触发同一草稿确认；溢出后当前 Tag 与焦点可见，窄屏菜单能访问全部打开页面。收起导航检查图标对齐、当前项、Tooltip 背景/箭头一致及切换后清理。页内 Tabs 保留标准键盘语义和无填充指示线，不能与页面 Tag 混用。源码与构建检查不能充当实际焦点、计算样式或视觉验收。
+
+## 搜索、日期与研究增量
+
+- interaction：搜索文字不冒充已选 ID；中文组合输入不误提交；同名 ID 可区分；加载/失败保留旧值与搜索词。未完成或逆序范围不能应用；取消/Escape 不修改正式值；清空与应用分开。跨页保留草稿与条件，隐藏 Teleport 不抢焦点。
+- layout/accessibility：单独记录 320 CSS px 重排及实际 200% 缩放；外围筛选、分页、浮层与主操作可达，二维表格例外不外扩；实测点击区域/间距及焦点遮挡。原触发器消失时应有明确逻辑后继。按 `yss-design-system/references/search-date-theme.md` 选择读屏检查并记录版本及未执行项。
+- content：设计疑问写成无提示任务和可复核结果。真实研究与教学模拟分开，缺参与者或轨迹不能宣称收益。工程报告只引用到同一份 design-qa。
+
+维持行为缺陷、规范/保持项对应的视觉观察、非阻断偏好建议三种结论。缺环境导致的必要检查未执行必须阻断对应验收；工具成功不能替代人工视觉批准。

package/template/.cursor/skills/setup-matt-pocock-skills/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Scaffold the per-repo configuration that the engineering skills assume:
 
-- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Issue tracker** — where issues live (Local Markdown by default; GitHub and GitLab require an explicit project choice)
 - **Triage labels** — the strings used for the five canonical triage roles
 - **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
 
@@ -31,42 +31,7 @@ Look at the current repo to understand its starting state. Read whatever exists;
 
 ### 2. Present findings and ask
 
-Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
-
-Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip Section B entirely when `triage` isn't installed.
-
-**Section A — Issue tracker.**
-
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `docs/.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
-
-Path resolution is configuration-first: every Local-aware skill must read the
-persisted `tracker.root` from `.template-spec/agents/issue-tracker.md` before resolving an
-artifact path. If the field is absent, use `docs/.scratch` as the default. Do
-not infer a tracker or replace the configured root from `git remote`; the legacy
-`.scratch/` and `docs/requirements/tickets/` roots are read-only migration
-sources.
-
-The supported tracker choices in this template are exactly `local-markdown`, `github`, and `gitlab`. A `git remote` may be displayed as code-host context only; it must not choose or rank a tracker. Ask for one explicit project choice, with Local Markdown as the template default:
-
-- **Local markdown (recommended)** — issues live as files under `docs/.scratch/<feature>/` in this repo.
-- **GitHub** — use GitHub Issues and the `gh` CLI only when the user explicitly selects GitHub.
-- **GitLab** — use GitLab Issues and the [`glab`](https://gitlab.com/gitlab-org/cli) CLI only when the user explicitly selects GitLab.
-
-Do not offer an `Other` tracker or write an unsupported platform into the project configuration; extending the YSS tracker contract must happen before adding another platform.
-
-Record the choice in `.template-spec/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
-
-**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
-
-If it is installed, ask exactly one question:
-
-> Do you want to keep the default triage labels? (recommended: **yes**)
-
-The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
-
-**Section C — Business vocabulary and decisions.** The layout does not branch: every YSS Git repository has exactly one case-sensitive `CONTEXT.md` at its root. Multiple business responsibility areas share that glossary and are distinguished by each business term's `适用业务责任区` and stable `<ContextId>/<EnglishIdentifier>` reference. ADRs live under root `docs/adr/` and are created lazily when the first qualifying decision is accepted.
-
-If the root `CONTEXT.md` is missing, initialize it with `context_schema_version: 1`, the process-term table (`术语 | 含义 | 英文标识 | 避免 / 备注`) and the business-term table (`术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注`). Do not invent business terms during setup. If a lowercase, nested, duplicate, or mapped context layout exists, stop and report `migration-required`; do not preserve or extend it as a second supported layout.
+需要确认 tracker、triage 标签或根词汇布局时，读取 [配置决定](references/configuration-decisions.md)，按条件逐项确认。Tracker 只允许 `local-markdown`、`github`、`gitlab`；默认 Local Markdown，不从 remote 推断。嵌套、重复或大小写错误的 CONTEXT 布局返回 `migration-required`。
 
 ### 3. Confirm and edit
 
@@ -79,42 +44,7 @@ Let them edit before writing.
 
 ### 4. Write
 
-**Pick the file to edit:**
-
-- If `AGENTS.md` exists, edit it.
-- If it is missing, ask before creating it.
-
-If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
-
-The block:
-
-```markdown
-## Agent skills
-
-### Issue tracker
-
-[one-line summary of where issues are tracked]. See `.template-spec/agents/issue-tracker.md`.
-
-### Triage labels
-
-[one-line summary of the label vocabulary]. See `.template-spec/agents/triage-labels.md`.
-
-### Domain docs
-
-[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See 根 `CONTEXT.md` 的消费规则.
-```
-
-Include the `### Triage labels` sub-block, and write `.template-spec/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
-
-Then write the docs files using the seed templates in this skill folder as a starting point:
-
-- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
-- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
-- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
-- [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
-- 根 `CONTEXT.md` 文首合同与消费规则 — domain doc consumer rules + layout
-
-For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `.template-spec/agents/issue-tracker.md`.
+草案已展示且用户确认后，读取 [配置写入与模板](references/write-configuration.md)。只更新已有区块并保留周围用户内容；不存在 AGENTS.md 时先取得创建授权。
 
 ### 5. Done
 

package/template/.cursor/skills/setup-matt-pocock-skills/references/configuration-decisions.md

@@ -0,0 +1,42 @@
+# 工程技能配置决定
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
+
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip Section B entirely when `triage` isn't installed.
+
+**Section A — Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, and `to-spec` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `docs/.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Path resolution is configuration-first: every Local-aware skill must read the
+persisted `tracker.root` from `.template-spec/agents/issue-tracker.md` before resolving an
+artifact path. If the field is absent, use `docs/.scratch` as the default. Do
+not infer a tracker or replace the configured root from `git remote`; the legacy
+`.scratch/` and `docs/requirements/tickets/` roots are read-only migration
+sources.
+
+The supported tracker choices in this template are exactly `local-markdown`, `github`, and `gitlab`. A `git remote` may be displayed as code-host context only; it must not choose or rank a tracker. Ask for one explicit project choice, with Local Markdown as the template default:
+
+- **Local markdown (recommended)** — issues live as files under `docs/.scratch/<feature>/` in this repo.
+- **GitHub** — use GitHub Issues and the `gh` CLI only when the user explicitly selects GitHub.
+- **GitLab** — use GitLab Issues and the [`glab`](https://gitlab.com/gitlab-org/cli) CLI only when the user explicitly selects GitLab.
+
+Do not offer an `Other` tracker or write an unsupported platform into the project configuration; extending the YSS tracker contract must happen before adding another platform.
+
+Record the choice in `.template-spec/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
+
+**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
+
+If it is installed, ask exactly one question:
+
+> Do you want to keep the default triage labels? (recommended: **yes**)
+
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
+
+**Section C — Business vocabulary and decisions.** The layout does not branch: every YSS Git repository has exactly one case-sensitive `CONTEXT.md` at its root. Multiple business responsibility areas share that glossary and are distinguished by each business term's `适用业务责任区` and stable `<ContextId>/<EnglishIdentifier>` reference. ADRs live under root `docs/adr/` and are created lazily when the first qualifying decision is accepted.
+
+If the root `CONTEXT.md` is missing, initialize it with `context_schema_version: 1`, the process-term table (`术语 | 含义 | 英文标识 | 避免 / 备注`) and the business-term table (`术语 | 含义 | 英文标识 | 适用业务责任区 | 避免 / 备注`). Do not invent business terms during setup. If a lowercase, nested, duplicate, or mapped context layout exists, stop and report `migration-required`; do not preserve or extend it as a second supported layout.

package/template/.cursor/skills/setup-matt-pocock-skills/references/write-configuration.md

@@ -0,0 +1,42 @@
+# 配置写入与种子模板
+
+仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- If `AGENTS.md` exists, edit it.
+- If it is missing, ask before creating it.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `.template-spec/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `.template-spec/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary: one root `CONTEXT.md`, with bounded contexts represented inside its business glossary]. See 根 `CONTEXT.md` 的消费规则.
+```
+
+Include the `### Triage labels` sub-block, and write `.template-spec/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+
+Then write the docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](.././issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-gitlab.md](.././issue-tracker-gitlab.md) — GitLab issue tracker
+- [issue-tracker-local.md](.././issue-tracker-local.md) — local-markdown issue tracker
+- [triage-labels.md](.././triage-labels.md) — label mapping (only if `triage` is installed)
+- 根 `CONTEXT.md` 文首合同与消费规则 — domain doc consumer rules + layout
+
+For an unsupported tracker request, stop and require a YSS tracker-contract extension; do not write an unsupported platform into `.template-spec/agents/issue-tracker.md`.

package/template/.cursor/skills/to-spec/SKILL.md

@@ -8,68 +8,15 @@ This explicit compatibility entry synthesizes confirmed context into a Spec draf
 
 If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
-## Process
+## 起草过程
 
-1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+1. 消费根 `CONTEXT.md`、已确认 Plan、当前决定和相关 ADR；复用已确认测试 seam，只对新增或实质变化的决定补充澄清。
+2. 使用仓库权威 `.template-spec/templates/spec-template.md`，与常规生命周期入口共享结构；按 `.template-spec/process/document-writing.md` 写作。故事数量由范围决定。FR/NFR/AC、来源、验收和未决项采用 `.template-spec/process/plan-spec-quality.md` 的表达约定。
+3. Spec 描述可观察行为、边界、例外和非目标。实现决策仅引用已确认上游约束；技术架构、OpenAPI Freeze 和实现任务交由既有下游阶段，不在本入口提前决定。
+4. 同时按 `.template-spec/process/business-tickets.md` 起草业务 Ticket 和 FR/AC 覆盖集合；每票放入 `business-tickets/`，Spec 只引用集合路径。复用已有稳定 ID，不等待工程、OpenAPI 或技术设计。草案未决项保留责任人和解决时点，运行 `scripts/verify-business-tickets <集合> --mode draft` 后一并回交验收。
+5. 将草稿按主控允许路径持久化；主 tracker 按项目配置使用，不从 Git remote 猜测。平台不可用时保留待发布草稿。Spec 使用 `ready-for-human`，起草者不批准、不设置 `ready-for-agent`。Design 校准同一组业务票，下游实现 Slice 仍放入 `issues/` 并保留工程和批准门禁。
+6. 可按需运行只读 `scripts/inspect-plan-spec check --root . --spec <Spec路径>` 辅助审阅；发现和未评估项不能转换为流转许可，原有 Context、决定和批准验证照常执行。
 
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+## 来源与适配
 
-Reuse already confirmed seams; ask only when a seam is new or materially changed.
-
-3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-human` triage label. Spec drafts need a human baseline approval before they are `approved`, and before implementation tickets may become `ready-for-agent`. Do not label the Spec itself `ready-for-agent`.
-
-<spec-template>
-
-## Problem Statement
-
-The problem that the user is facing, from the user's perspective.
-
-## Solution
-
-The solution to the problem, from the user's perspective.
-
-## User Stories
-
-A LONG, numbered list of user stories. Each user story should be in the format of:
-
-1. As an <actor>, I want a <feature>, so that <benefit>
-
-<user-story-example>
-1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
-</user-story-example>
-
-This list of user stories should be extremely extensive and cover all aspects of the feature.
-
-## Implementation Decisions
-
-A list of implementation decisions that were made. This can include:
-
-- The modules that will be built/modified
-- The interfaces of those modules that will be modified
-- Technical clarifications from the developer
-- Architectural decisions
-- Schema changes
-- API contracts
-- Specific interactions
-
-Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
-
-Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
-
-## Testing Decisions
-
-A list of testing decisions that were made. Include:
-
-- A description of what makes a good test (only test external behavior, not implementation details)
-- Which modules will be tested
-- Prior art for the tests (i.e. similar types of tests in the codebase)
-
-## Out of Scope
-
-A description of the things that are out of scope for this spec.
-
-## Further Notes
-
-Any further notes about the feature.
-
-</spec-template>
+保留 mattpocock 上游来源与锁定记录。YSS 适配仅统一权威模板、生命周期边界和本地持久化方式；不维护另一份内嵌模板。

package/template/.cursor/skills/to-tickets/SKILL.md

@@ -1,105 +1,39 @@
 ---
 name: to-tickets
-description: "显式调用时，将已确认的 Plan 或 Spec 拆成带依赖的垂直切片 Ticket，并按配置的 tracker 持久化。"
+description: 显式按当前生命周期拆分 Ticket；Spec/Design 起草业务票，研发侧承接业务票细化实现 Slice。
 disable-model-invocation: true
 ---
 
 # To Tickets
 
-Break an explicitly requested, confirmed plan or Spec into tracer-bullet Ticket drafts. Before any formal write, return to the active lifecycle orchestrator for repository identity, current inputs, allowed paths and applicable gates. Template-source maintenance does not create product Tickets. The explicit entry may write its prepared artifacts only within that preflight contract and returns them to the orchestrator for validation and acceptance; it cannot approve a Slice Contract or decide readiness.
+本兼容入口仅由用户显式调用。写入前回交当前生命周期主控，核验仓库身份、当前输入、允许路径和适用门禁。`template-source` 不生成产品票；起草者不批准 Slice 合同、不设置 `ready-for-agent`。保留 mattpocock 上游来源与锁定记录，采用以下 YSS 阶段适配。
 
-If the issue tracker or triage label vocabulary is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+## 先确定输出类型
 
-## Process
+按 `.template-spec/process/business-tickets.md` 和当前工作单元选择一种输出；目录是否存在不决定路线。
 
-### 1. Gather context
+| 当前范围 | 输出与依据 | 工程前置 |
+|---|---|---|
+| Spec / 产品设计 | 业务 Ticket 草案或校准；按用户行为、可验收结果、FR/AC、适用规则和场景拆分 | 不需要实现仓库、OpenAPI Freeze 或构建命令 |
+| 研发 | 消费正式业务集合，细化窄垂直实现 Slice；保留业务 Ticket 和原始 FR/AC 引用 | 技术分析可起草；正式化仍需当前工程契约及仓库准备 |
 
-Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+独立 Design profile 只允许第一种输出，完成业务正式化后进入战略交接。全生命周期使用本地已确认资产，不导出再导入自己的包。
 
-### 2. Explore the codebase (optional)
+## 起草与校准
 
-If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+1. 读取已有 Spec、根 `CONTEXT.md`、当前决定、集合及相关设计。先复用稳定 ID，再根据真实范围增删或细化；不重新生成一套票。
+2. 业务票用 `.template-spec/templates/business-ticket-template.md`，每票一个 `business-tickets/BT-<id>.md`。集合用 `business-ticket-set-template.yaml`，只保存引用、版本、摘要和覆盖处置。依赖表达业务前后置，禁止按 Controller / Service / Repository 分票，也不机械地一条 FR 一票。
+3. Design 按页面流、状态、失败和恢复路径校准。无产品设计影响时记录依据；不生成空原型。未决项保留责任人、解决时点及是否阻断，延期遵守既有决定协议。
+4. 研发输出用 `.template-spec/templates/vertical-slice-ticket-template.md`，放入 `issues/`；一个业务票可细化为多个 Slice。实现票保留 `kind: vertical-slice-ticket`、业务集合和业务票来源以及原始 AC 引用。
 
-Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+仅研发细化时按需查看已登记工程及 ADR。每个实现 Slice 贯通本次行为命中的技术层、可独立验证；不因模板枚举 schema / API / UI 就引入未命中的技术层。必要的机械重构按 expand → 分批迁移 → contract 排序；无法独立保持绿色的批次须明确共享集成验证边界，不能声称各批已独立完成。
 
-### 3. Draft vertical slices
+## 审阅与回交
 
-Break the work into **tracer bullet** tickets.
+展示每票的业务结果、范围、验收、依赖与未决项，以及集合覆盖情况。按实际缺口提问；等义细化沿既有授权延续协议核验，范围、规则或验收实质变化返回原决定边界。拆分本身不增加常规人工批准节点。
 
-<vertical-slice-rules>
+业务草案运行 `scripts/verify-business-tickets <集合> --mode draft`；正式化使用 `--mode formal`，并消费已有 Spec / 适用产品设计批准及当前独立专业审查。结构检查不代替语义审查或真实批准。阶段工作项完成、业务正式化和实现就绪分别回报。
 
-- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
-- A completed slice is demoable or verifiable on its own
-- Each slice is sized to fit in a single fresh context window
-- Any prefactoring should be done first
+主 tracker 以 `.template-spec/agents/issue-tracker.md` 为准，不从 Git remote 猜测。配置缺失时回交主控处理，不自动调用其他显式 Skill。远程不可用或未获发布授权时保留本地待发布草案；远程发布需用户明确授权。业务票保持 `draft` / `ready-for-human`，实现票只有主控完成正式门禁和当前合同批准后才可 `ready-for-agent`。
 
-</vertical-slice-rules>
-
-Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no dependency edges still needs a current approved Slice Contract and all applicable implementation gates before it can start.
-
-**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
-
-### 4. Quiz the user
-
-Present the proposed breakdown as a numbered list. For each ticket, show:
-
-- **Title**: short descriptive name
-- **Blocked by**: which other tickets (if any) must complete first
-- **What it delivers**: the end-to-end behaviour this ticket makes work
-
-Ask the user:
-
-- Does the granularity feel right? (too coarse / too fine)
-- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
-- Should any tickets be merged or split further?
-
-Reuse an existing approval that covers this same breakdown. Ask only about unresolved scope, granularity or dependency decisions; return accepted drafts and evidence to the orchestrator.
-
-### 5. Publish the tickets to the configured tracker
-
-Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes:
-
-- **Local files** → write one file per ticket under `docs/.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file.
-- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Keep drafts `ready-for-human`. Only the orchestrator may mark a narrow slice `ready-for-agent` after checking its current approved contract and applicable gates. Publishing to a remote tracker requires explicit authorization for that action.
-
-Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
-
-Do NOT close or modify any parent issue.
-
-<local-ticket-template>
-
-# <NN> — <Ticket title>
-
-**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
-
-**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — readiness still requires contract and gate verification".
-
-**Status:** ready-for-human
-
-- [ ] Acceptance criterion 1
-- [ ] Acceptance criterion 2
-
-</local-ticket-template>
-
-<issue-template>
-
-## Parent
-
-A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
-
-## What to build
-
-The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
-
-## Acceptance criteria
-
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-## Blocked by
-
-- A reference to each blocking ticket, or "None — readiness still requires contract and gate verification".
-
-</issue-template>
-
-In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+Spec、map 与父 Ticket 引用同一集合，不复制正文。本入口回交证据及待同步内容，由主控维护父 Ticket 状态；不得自行关闭父票或宣布功能完成。