create-yss-spec 3.5.6 → 3.5.9

package/template/.agents/skills/code-review/SKILL.md

@@ -3,7 +3,7 @@ name: code-review
 description: 审查分支、PR、固定候选或工作树改动，按仓库规范、Spec 及适用 UI 还原要求报告有证据的缺陷。
 ---
 
-Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
+Review a pinned candidate: all applicable axes initially, then affected conclusions and dependencies:
 
 - **Standards** — does the code conform to this repo's documented coding standards **and**, for YSS slices, the specialist check inputs compiled in [yss-review-standards.md](references/yss-review-standards.md)?
 - **Spec** — does the code faithfully implement the originating issue / spec?
@@ -11,13 +11,13 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 
 普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
-If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+角色表编译 `review_context` / `skill_source.review_skills`（只读）；见协作规则，不授予实现权限。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## 文档写作
 
-撰写审查报告时，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+撰写审查报告时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。作用域仅限当前产物，派发时传递条件及引用。
 
 ## Process
 
@@ -38,27 +38,35 @@ Look for the originating spec, in this order:
 
 Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `.template-spec/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
-For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
+Resolve backend roots from the registered project and Slice scope; exclude frontend, vendor, unrelated submodules and unregistered roots. Assess both `yss-repository` and `yss-mybatis` for every backend candidate, including impact, selected Profile and current component source index per the standards reference. Without persistence impact, record concrete `not-applicable` reasons for both.
 
-Every backend candidate must explicitly assess `yss-repository` and `yss-mybatis`. When the candidate changes persistence structure, Mapper/XML, SQL, pagination, batch operations, scanning/configuration or data-source behavior, read both skills and the selected Repository Profile; exact component claims also require a current `yss-mybatis` source index. When no persistence impact exists, record a concrete `not-applicable` reason for both instead of silently skipping them.
-
-Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`, remains a source. It does **not** replace YSS or Alibaba specialist inputs.
+Repo coding documents remain sources alongside mandatory YSS / Alibaba inputs.
 
 Standards 检查代码 diff 时读取 [Fowler smell baseline](references/smell-baseline.md)。仓库明确标准优先；smell 只作 judgement call，不升级为硬违规，机器已覆盖项不重复判断。
 
 ### 4. Complete each applicable review axis
 
-默认由当前独立 Reviewer 连续完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
+默认由独立 Reviewer 完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
 
 执行 Standards / Spec 轴时读取 [逐轴检查提纲](references/review-axis-checklists.md)；单 Reviewer 同样使用它。实际派发时传入相同候选、证据和完整 smell baseline；Spec 缺失按提纲明确报告。
 
-普通审查只复验修复影响的结论及其依赖；候选摘要变化后仍须重新绑定当前候选，不能沿用过期证据。未受影响项记录依据后复用。已明确采用下节历史候选/多轴合同的审查继续遵守其约定。
+首轮完整覆盖；修复后依差异、受影响结论 / 行为及依赖定向复验并绑定当前候选，未受影响项有依据地复用。摘要、UI 或 `new_impacts` 不触发全轴兜底，未知先调查。历史两轮同样适用；细则见 [finding 闭环](references/yss-review-standards.md)。
 
 ### 5. Aggregate
 
 仅任务包携带 `review_round`、明确采用历史冻结候选协议时，读取 [两轮收敛合同](references/legacy-convergence.md)。普通审查不因此新增候选冻结或额外审查者。
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+#### 报告与阻断
+
+按 `## Standards`、`## Spec` 分别呈现原报告或等义整理后的结论；UI 影响另列 `## UI fidelity`。专项表填写在 `.template-spec/templates/review-report-template.md` 的 Standards 证据中，不增加第四轴，也不合并或跨轴重排 findings。适用专项行空白、遗漏 `required_skills` 或 mandatory violation 未关闭时，结果为 `blocked`，不能写 `completed`。
+
+#### 修复后复审
+
+Reviewer 保持只读，将 `violation`、机器检查失败和适用行空白交回原合同路径的实施者。修复后比较差异、重新捕获候选，复审受影响结论与依赖，并明确重新绑定未受影响的证据；不在审查会话中写实现来关闭 finding。
+
+#### 合同失效与延期
+
+`drift`、`new_impacts` 或 `required_skills` 不匹配时，将合同标为 `stale` 并回到 实现合同编译器 调查受影响要求；停止使用旧合同实现，不默认全轴重审。`not-applicable` 只用于未触发影响。mandatory 门禁不能豁免；按原合同修复，或在原流程允许延期时提供完整 `seam-deferred` 记录。
 
 For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 

package/template/.agents/skills/code-review/references/candidate-capture.md

@@ -28,6 +28,6 @@ commit_list_command: <command>
 
 For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
 
-For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New template-maintenance captures use a previously nonexistent external `maintenance:candidates/<id>/` directory, resolved through the workspace maintenance storage, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. New template-maintenance captures reject explicit exclusions: the historical archive-path allowlist is retired, and maintenance material lives outside the repository. Historical schema v1 exclusion lists remain read-only compatible. Candidate manifest schema v2 uses `reference_base: bundle`, the workspace identity, and package-relative stream/diff references. The original candidate byte stream and digest remain unchanged; schema v1 remains read-only compatible. Project-instance and Slice candidates keep their registered repository scope and existing path permissions; the maintenance capture CLI does not grant external paths to them. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
 
 Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.

package/template/.agents/skills/code-review/references/legacy-convergence.md

@@ -2,4 +2,6 @@
 
 仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
 
-For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
+For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. First review covers all applicable checks. After Round 1 repairs, compare the old and new candidates, identify affected conclusions, behavior and dependencies, rereview only that scope, and bind every consumed conclusion to the new digest. Candidate byte changes invalidate the old candidate binding, not every underlying conclusion; reuse requires readable comparison evidence showing unchanged conditions, basis and dependencies. UI impact, `new_impacts` or unknown impact never selects all axes by default or as a fallback; investigate unknown impact before selecting the rereview scope.
+
+For this explicitly selected legacy contract, if Round 2 still has an open `violation`, `drift` or `new_impacts`, the existing evaluator returns `needs-human`; do not silently start Round 3 or rewrite historical states. This compatibility limit is not enabled for ordinary review. Return the unresolved findings and readable evidence to the orchestrator, which separates professional wait, repair / rerouting and missing real decisions, and continues independent authorized work. A new user request still requires a real missing decision or authorization and reviewable assets. No prior approval or report is rewritten.

package/template/.agents/skills/code-review/references/review-axis-checklists.md

@@ -2,6 +2,8 @@
 
 仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
 
+首轮完整覆盖每个适用轴。复审任务额外传入旧 / 新候选差异、受影响结论与行为、直接 / 传递依赖和待复验清单；下列提纲按该清单使用，未受影响结论保留比较证据并绑定当前候选。摘要变化、UI 或 `new_impacts` 不自动选择全部提纲；未知影响先调查。
+
 **Standards sub-agent prompt** — include:
 
 - The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.

package/template/.agents/skills/code-review/references/yss-review-standards.md

@@ -55,8 +55,10 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 
 | 类型 | 动作 |
 |---|---|
-| `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；任何修复使候选失效，必须重新捕获并重跑 Standards、Spec、UI fidelity（若命中）和 fresh verification |
-| `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 实现合同编译器 或更早生命周期阶段；禁止在旧合同上继续编码 |
+| `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；比较差异及受影响结论、行为和依赖，重新捕获并定向复审 / 验证，未受影响项有依据地复用并绑定当前候选 |
+| `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，先调查实际变化及依赖，再回 实现合同编译器 或更早生命周期阶段更新受影响合同；禁止在旧合同上继续编码，不默认全轴复审 |
+
+首轮仍完整覆盖全部适用 Standards、Spec 和条件 UI fidelity。候选摘要变化、UI 影响或未知影响不构成全轴复审的默认或兜底；未知项先调查并阻断其依赖结论。复用证据必须可读，确认原检查条件、依据与依赖未变；当前完成结果重新绑定候选、合同和实际验证，不修改历史报告。
 
 `not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。
 

package/template/.agents/skills/competitive-intelligence/SKILL.md

@@ -1,94 +1,52 @@
 ---
 name: competitive-intelligence
-description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Plan, Spec, product strategy, or roadmap decisions.
+description: "执行竞品、市场定位、定价、功能差距与用户口碑调研；复用现有模板输出竞品功能矩阵和深度分析报告，向 Plan、Spec 与产品策略提供证据。"
 ---
 
 # Competitive Intelligence
 
-Source requested for this project: `anthropics/knowledge-work-plugins`, `sales/skills/competitive-intelligence`.
+本项目请求的上游来源：`anthropics/knowledge-work-plugins`，`sales/skills/competitive-intelligence`。保留 YSS 适配；上游更新不能直接覆盖当前合同。
 
-Use this skill when competitive or market facts are needed to shape product Plan, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
+竞品或市场事实影响 Plan、Spec 范围、定位、差异化、定价假设或路线取舍时使用本技能。`yss-research` 是统一入口和研究证据包所有者，本技能负责专项采集、比较与分析并回传引用结果。直接调用本技能时也按 `yss-research` 的 profile、模式和证据合同组织结果。
 
-## Core Rules
+文档输出按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；只作用于当前产物。正文用简体中文，产品名、来源 URL、API 与 metadata 保持原样。
 
-- Browse or verify current public sources before making factual claims about competitors, pricing, features, market position, funding, partnerships, product releases, or customer sentiment.
-- Separate facts, evidence, and inference. Do not present strategy guesses as verified competitor intent.
-- Prefer primary or near-primary sources: official product pages, docs, pricing pages, changelogs, release notes, filings, case studies, status pages, marketplace listings, reputable analyst reports, and dated customer reviews.
-- Record dates for time-sensitive claims. Pricing, packaging, roadmap, customer logos, and feature availability can change quickly.
-- Persistent project outputs should use Chinese body text by default. Keep competitor names, product names, URLs, API names, and quoted identifiers unchanged.
-- Do not bypass paywalls, scrape private systems, or use confidential information. Public evidence only unless the user explicitly provides internal material.
+## 模式与产物
 
-## Workflow
+读取 `.agents/skills/yss-research/references/competitive-analysis.md`，遵守以下输出选择：
 
-1. Define the intelligence question:
-   - Which product decision will this inform?
-   - Which competitors or substitute workflows are in scope?
-   - Which markets, user segments, regions, editions, or use cases matter?
-   - What must be decided after the research?
-2. Build an evidence plan:
-   - Official sources for product capabilities and pricing.
-   - Documentation and changelogs for depth and recency.
-   - Reviews, community posts, app marketplaces, and job posts for adoption and pain signals.
-   - Analyst, media, or public filings for market context when relevant.
-3. Capture evidence with source links and dates:
-   - Feature / capability evidence.
-   - Pricing / packaging evidence.
-   - UX / onboarding evidence.
-   - Integration / ecosystem evidence.
-   - Customer segment and positioning evidence.
-   - Complaints, workarounds, or unmet needs.
-4. Synthesize:
-   - Competitor positioning.
-   - Table-stakes capabilities.
-   - Differentiators and defensibility.
-   - Gaps and underserved jobs-to-be-done.
-   - Risks if we copy the competitor too closely.
-   - Product opportunities for Spec or roadmap.
-5. Hand off to lifecycle assets:
-   - Update Plan findings in `docs/.scratch/<feature>/plan/`.
-   - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
-   - Return stable user, pain, MVP, non-goal and success criteria to the current lifecycle/strategic owner for its native Plan and Spec work units. Compatibility entries remain explicit-user-only.
-   - Record uncertain claims as assumptions, not requirements.
+| 请求 | 模式 | 默认输出 |
+|---|---|---|
+| 普通竞品探索 | `quick` | 聊天简报＋精简功能矩阵，标明未审计 |
+| 深度、严格、可复现或可审计研究 | `evidence-audited` | 完整矩阵＋深度报告＋研究双文件 |
+| 明确只要矩阵或报告 | 按研究深度与用途确定 | 只输出指定阅读材料；审计模式保留研究双文件 |
+| 正式生命周期批准输入 | `evidence-audited` | 指定阅读材料＋可绑定证据包 |
 
-## Output Shape
+不因选择单一产物而降级审计，也不把普通探索自动升级。竞品策略使用 `strategy-evidence`；技术能力、框架和协议事实按 `technical-evidence` 的一手来源要求审计。
 
-For a quick brief:
+完整矩阵使用 `.template-spec/plan/templates/competitive-matrix-template.md`，报告使用 `.template-spec/plan/templates/competitive-analysis-template.md`。审计模式在同一目录保留 `<slug>-research-brief.md`、`<slug>-evidence.yaml` 和选定的 `<slug>-competitive-matrix.md` / `<slug>-competitive-analysis.md`。报告是附属阅读材料，不替代研究简报。
 
-```markdown
-## 竞品情报简报
+## 执行
 
-### 研究问题
-- <本次情报要支持的产品决策>
+1. 明确研究要支持的决定、竞品 / 替代方案、用户、能力边界、地区、版本 / 套餐、截至日期和问题；优先消费用户提供或已登记材料，记录排除与访问失败。
+2. 核验当前公开资料：产品与定价页、官方文档、更新日志、第一方案例、备案 / 披露和可追溯数据。口碑、采用与痛点可用带日期的评论、社区、市场记录和可检查方法的行业报告，保留来源类别、抽样及独立性限制。
+3. 将事实、来源、观察和 Claim 回传统一证据台账，采集功能、定价 / 套餐、流程、集成、目标用户、定位、投诉与变通方案，寻找反向信号。
+4. 审计模式在 `competitive_analysis` 中登记比较范围、竞品、能力和每个竞品 × 能力结果；矩阵及报告消费同一组结果。`supported / partial / absent / unknown` 分开表达，未查到资料写未知；部分支持须写限制，明确不支持须有适用范围内的已审计依据。
+5. 审计模式从结构化结果渲染功能比较区，区外补充定位、流程、优势、风险、机会及 MVP 建议；`quick` 在聊天中综合简报与精简矩阵。结论引用 Claim / 来源，推断标明依据；来源冲突时保留冲突和置信度，不猜竞品意图。
+6. 审计模式执行研究包校验并交回 `yss-research`；`quick` 回传未审计结果。交接保留事实及审计状态、反向信号、缺口与补证计划、候选术语、产品机会、MVP / 非目标及成功标准建议、下游所有者。由接收者核验后用于其原生工作单元。
 
-### 范围
-- 竞品 / 替代方案：<list>
-- 用户 / 市场：<scope>
-- 时间范围：<date>
+审计模式从仓库根运行渲染与校验：
 
-### 关键结论
-- <fact or inference, clearly labeled>
-
-### 证据表
-| 结论 | 证据 | 来源 | 日期 | 置信度 |
-|---|---|---|---|---|
-
-### 竞品矩阵
-| 维度 | 竞品 A | 竞品 B | 我们的机会 |
-|---|---|---|---|
-
-### Spec 输入
-- 用户 / 痛点：
-- MVP 建议：
-- 非目标范围：
-- 验收或验证建议：
-
-### 风险与待验证假设
-- <assumption>
+```bash
+node .agents/skills/yss-research/scripts/render-competitive-outputs.mjs <slug>-evidence.yaml
+node .agents/skills/yss-research/scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
 ```
 
-## Guardrails
+## 分析边界
 
-- Do not treat competitive parity as a product requirement. Convert evidence into user value, MVP boundaries, and testable acceptance criteria.
-- Do not copy competitor UX, text, proprietary workflows, screenshots, or private materials into project artifacts.
-- If sources conflict, show both and mark confidence rather than forcing a false conclusion.
-- If current web access is unavailable, state the limitation and produce only a research plan or hypothesis list.
+- 比较结论记录产品、版本、套餐、地区与日期；未知范围明确写 `unknown`，不能默认为所有版本适用。
+- 默认不生成数字排名。用户明确要求评分时先确认量表、维度 / 权重和依据；未知记不评分，不能计低分或零分。
+- 功能对齐是证据信号，产品机会与优先级属于建议，不直接成为需求。候选术语回交 `domain-modeling`，Plan / Spec 由对应所有者更新；不写 `CONTEXT.md`、Spec、批准或 Ticket 状态。
+- 使用公开证据或用户明确提供的内部材料；不绕过付费墙或访问私有系统，不将竞品专有内容、文本、截图或工作流直接复制到项目产物。
+- 当前来源访问不可用时说明边界，仅根据可访问的固定资料作限定结论，或返回研究计划与假设；不声称已核验当前竞品事实。
+- 结构校验只证明格式、引用和跨文件一致性，来源是否支持结论与推断是否合理仍需研究审核。

package/template/.agents/skills/file-export-download/SKILL.md

@@ -31,7 +31,7 @@ description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 O
 
 ## 决策流程
 
-1. 在 OpenAPI 中定位导出接口，优先把成功响应声明为二进制媒体类型和 `format: binary`。
+1. 在冻结 OpenAPI 中定位导出接口，核对成功响应的二进制媒体类型和 `format: binary`。需要修改声明时回交 `yss-openapi-governance`，完成现有 Draft / Freeze 与受控 JSON 派生链后再接入。
 2. 重新生成 API 后检查生成方法，而不是凭接口名称判断：
    - 已包含 `responseType: 'blob'`：业务调用不必重复传第二参数。
    - 未包含 `responseType: 'blob'`：业务调用必须传第二参数 `{ responseType: 'blob' }`。
@@ -57,78 +57,9 @@ description: "在 Vue3 YSS UI 中实现或修复文件下载与导出，处理 O
 - 必须用独立 loading 状态防止重复导出，并在 `finally` 中恢复。
 - 不得默认传 `skipBusinessError` 或 `skipErrorHandler`；只有明确需要业务自定义错误体验时才使用。
 
-## OpenAPI 标准代码骨架
-
-```json
-{
-  "responses": {
-    "200": {
-      "description": "导出成功",
-      "headers": {
-        "Content-Disposition": {
-          "schema": { "type": "string" }
-        }
-      },
-      "content": {
-        "application/octet-stream": {
-          "schema": {
-            "type": "string",
-            "format": "binary"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-根据文件类型可将媒体类型换成 `text/csv`、`application/pdf` 或 Excel 对应类型。跨域请求若读取不到文件名，后端还必须暴露 `Content-Disposition` 响应头。
-
-## 标准代码骨架
-
-### 生成方法已包含 responseType
-
-```typescript
-import { ref } from 'vue';
-import { handleBlobResponse } from '@yss-ui/utils';
-import { downloadAccessSecret } from '@/api/generated/quality';
-
-/** 微应用 mutator 返回的文件下载响应。 */
-type BlobDownloadResponse = {
-  data: Blob;
-  headers: Record<string, string>;
-};
-
-/** 文件下载进行中状态。 */
-const downloading = ref(false);
-
-/** 下载密钥文件。 */
-const downloadFile = async (key: string): Promise<void> => {
-  if (downloading.value) return;
-
-  downloading.value = true;
-  try {
-    const res = (await downloadAccessSecret(key)) as unknown as BlobDownloadResponse;
-    handleBlobResponse(res.data, res.headers);
-  } catch {
-    // mutator 已展示错误；此处只阻止 reject 继续向 UI 事件传播。
-  } finally {
-    downloading.value = false;
-  }
-};
-```
-
-### 生成方法缺少 responseType
-
-只改调用行，其他流程保持一致：
-
-```typescript
-const res = (await downloadAccessSecret(key, {
-  responseType: 'blob',
-})) as unknown as BlobDownloadResponse;
-```
-
-若 mutator 与 Orval 返回类型已经准确声明为 `{ data: Blob; headers: ... }`，直接使用生成类型，删除不必要的类型断言。
+## 按需示例
+
+核对二进制响应与文件名声明时，读取 [OpenAPI 二进制响应示例](references/binary-contract-example.md)。首次接入生成方法、或需判断是否补传 Blob 选项时，读取 [下载调用示例](references/download-call-example.md)，按生成方法的真实签名选择分支。
 
 ## 响应约定
 

package/template/.agents/skills/file-export-download/references/binary-contract-example.md

@@ -0,0 +1,26 @@
+## OpenAPI 标准代码骨架
+
+```json
+{
+  "responses": {
+    "200": {
+      "description": "导出成功",
+      "headers": {
+        "Content-Disposition": {
+          "schema": { "type": "string" }
+        }
+      },
+      "content": {
+        "application/octet-stream": {
+          "schema": {
+            "type": "string",
+            "format": "binary"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+根据文件类型可将媒体类型换成 `text/csv`、`application/pdf` 或 Excel 对应类型。跨域请求若读取不到文件名，后端还必须暴露 `Content-Disposition` 响应头。

package/template/.agents/skills/file-export-download/references/download-call-example.md

@@ -0,0 +1,45 @@
+## 标准代码骨架
+
+### 生成方法已包含 responseType
+
+```typescript
+import { ref } from 'vue';
+import { handleBlobResponse } from '@yss-ui/utils';
+import { downloadAccessSecret } from '@/api/generated/quality';
+
+/** 微应用 mutator 返回的文件下载响应。 */
+type BlobDownloadResponse = {
+  data: Blob;
+  headers: Record<string, string>;
+};
+
+/** 文件下载进行中状态。 */
+const downloading = ref(false);
+
+/** 下载密钥文件。 */
+const downloadFile = async (key: string): Promise<void> => {
+  if (downloading.value) return;
+
+  downloading.value = true;
+  try {
+    const res = (await downloadAccessSecret(key)) as unknown as BlobDownloadResponse;
+    handleBlobResponse(res.data, res.headers);
+  } catch {
+    // mutator 已展示错误；此处只阻止 reject 继续向 UI 事件传播。
+  } finally {
+    downloading.value = false;
+  }
+};
+```
+
+### 生成方法缺少 responseType
+
+只改调用行，其他流程保持一致：
+
+```typescript
+const res = (await downloadAccessSecret(key, {
+  responseType: 'blob',
+})) as unknown as BlobDownloadResponse;
+```
+
+若 mutator 与 Orval 返回类型已经准确声明为 `{ data: Blob; headers: ... }`，直接使用生成类型，删除不必要的类型断言。

package/template/.agents/skills/formily-foundation/SKILL.md

@@ -3,7 +3,7 @@ name: formily-foundation
 description: 指导 YFormily 基础表单开发；当创建或修复普通单页表单、字段校验、提交链路、查询表单布局、scope 表达式或导入边界时使用。
 ---
 
-# Formily Foundation Skill
+# YFormily 基础表单
 
 ## 触发条件
 
@@ -28,6 +28,7 @@ description: 指导 YFormily 基础表单开发；当创建或修复普通单页
 - 禁止业务层导入 `@formily/antdv`、`@formily/antd*` UI 组件。
 - 必须使用三层结构：`FormLayout -> FormGrid -> 字段`，禁止字段直接挂在根节点或单独以 `FormGrid` 作为顶层布局。
 - `Submit` 必须传 `onSubmit`，否则不触发表单提交。
+- 异步保存时 `onSubmit` 返回实际保存 Promise，以等待完成并传播 reject；`emit('submit')` 只发送事件，不能代表父回调的异步结果。
 - 标准业务列表/CRUD 查询区默认让 `YFormily` 只渲染字段；查询/重置按钮用外部 `YButton` 放在 `.xxx__search-actions`，由 hook 的 `handleSearch/handleReset` 控制分页重置和请求。
 - `AutoButtonGroup -> Submit/Reset` 仅用于纯 Formily 表单提交，不作为业务列表查询区默认方案。
 - 查询区禁止横向放“表单 + 按钮”后用大 `gap`、`align-items: flex-start` 或 `padding-top` 硬调位置；字段换行时按钮必须在搜索卡片右下角。
@@ -46,109 +47,9 @@ description: 指导 YFormily 基础表单开发；当创建或修复普通单页
   - 当前 YFormily 的 FormItem 适配层会在运行时归一化反馈：空值优先显示必填提示，非空值移除残留必填提示，多条相关消息只拼接一次。该兜底不替代正确的 Schema 校验职责拆分。
 - 分步需求默认走 `formily-step-flow`，不在本 skill 内给 `FormStep` 方案。
 
-## 标准代码骨架
-
-```vue
-<script setup lang="ts">
-import { YFormily, type ISchema } from '@yss-ui/components';
-
-/** 表单保存回调 Props。 */
-interface SaveFormProps {
-  onSave: (values: Record<string, any>) => Promise<void>;
-}
-
-/** 表单保存回调。 */
-const props = defineProps<SaveFormProps>();
-
-/** 校验通过后提交表单数据。 */
-const onSubmit = (values: Record<string, any>) => {
-  return props.onSave(values);
-};
-
-/** 基础表单 Schema。 */
-const schema: ISchema = {
-  type: 'object',
-  properties: {
-    layout: {
-      type: 'void',
-      'x-component': 'FormLayout',
-      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
-      properties: {
-        grid: {
-          type: 'void',
-          'x-component': 'FormGrid',
-          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
-          properties: {
-            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true, 'x-validator': [{ required: true, whitespace: true, message: '请输入名称' }] },
-            submit: {
-              type: 'void',
-              'x-component': 'Submit',
-              'x-content': '提交',
-              'x-component-props': { onSubmit: '{{ onSubmit }}' },
-            },
-          },
-        },
-      },
-    },
-  },
-};
-</script>
-
-<template>
-  <YFormily :schema="schema" :scope="{ onSubmit }" />
-</template>
-```
-
-## 业务查询区布局
-
-```vue
-<template>
-  <YCard class="demo-page__search-card" :padding="16">
-    <div class="demo-page__search-content">
-      <div class="demo-page__search-form">
-        <YFormily v-model="queryModel" :schema="searchSchema" />
-      </div>
-      <div class="demo-page__search-actions">
-        <YButton type="primary" @click="handleSearch">查询</YButton>
-        <YButton @click="handleReset">重置</YButton>
-      </div>
-    </div>
-  </YCard>
-</template>
-```
-
-```less
-.demo-page {
-  &__search-content {
-    display: flex;
-    flex-direction: column;
-    align-items: stretch;
-    gap: 16px;
-  }
-
-  &__search-form {
-    width: 100%;
-    min-width: 0;
-
-    :deep(.ant-formily-form-item) {
-      margin-bottom: 0;
-    }
-
-    :deep(.ant-formily-form-grid) {
-      width: 100%;
-    }
-  }
-
-  &__search-actions {
-    display: flex;
-    width: 100%;
-    flex: 0 0 auto;
-    align-items: center;
-    justify-content: flex-end;
-    gap: 12px;
-  }
-}
-```
+## 按需示例
+
+同步事件提交读取 [基础表单与提交](references/examples.md#1-基础表单与提交)；等待父回调完成的异步保存读取 [异步保存回调](references/async-save-example.md)。Orval 提交的 loading、reject 与错误提示读取 [错误处理](references/examples.md#8-orval-提交与错误处理)。实现业务列表查询区或排查窄屏按钮位置时，读取 [业务查询区布局](references/query-layout.md)。联动、模式和分步示例只在对应条件命中时读取，并服从实际命中的专项 Skill。
 
 ## 交付检查清单
 
@@ -173,4 +74,4 @@ const schema: ISchema = {
 
 ## 参考
 
-- 完整示例：`./references/examples.md`
+[示例库目录](references/examples.md#目录)按具体场景定位，不要求每次读取全部示例。

package/template/.agents/skills/formily-foundation/references/async-save-example.md

@@ -0,0 +1,57 @@
+# 异步保存回调
+
+等待父回调完成的保存场景读取本例。`onSubmit` 必须返回实际保存 Promise；发送 `emit` 事件只返回 void，不能等待父组件的异步请求。
+
+Orval 请求失败沿用 [错误处理](examples.md#8-orval-提交与错误处理)，由 mutator 统一提示，调用方恢复 loading 并传播 reject。
+
+```vue
+<script setup lang="ts">
+import { YFormily, type ISchema } from '@yss-ui/components';
+
+/** 表单保存回调 Props。 */
+interface SaveFormProps {
+  onSave: (values: Record<string, any>) => Promise<void>;
+}
+
+/** 表单保存回调。 */
+const props = defineProps<SaveFormProps>();
+
+/** 校验通过后提交表单数据。 */
+const onSubmit = (values: Record<string, any>) => {
+  return props.onSave(values);
+};
+
+/** 基础表单 Schema。 */
+const schema: ISchema = {
+  type: 'object',
+  properties: {
+    layout: {
+      type: 'void',
+      'x-component': 'FormLayout',
+      'x-component-props': { layout: 'horizontal', labelWidth: 120, labelAlign: 'right' },
+      properties: {
+        grid: {
+          type: 'void',
+          'x-component': 'FormGrid',
+          'x-component-props': { maxColumns: 3, minColumns: 1, minWidth: 260 },
+          properties: {
+            name: { type: 'string', title: '名称', 'x-decorator': 'FormItem', 'x-component': 'Input', required: true, 'x-validator': [{ required: true, whitespace: true, message: '请输入名称' }] },
+            submit: {
+              type: 'void',
+              'x-component': 'Submit',
+              'x-content': '提交',
+              'x-component-props': { onSubmit: '{{ onSubmit }}' },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+</script>
+
+<template>
+  <YFormily :schema="schema" :scope="{ onSubmit }" />
+</template>
+```
+