create-yss-spec 3.5.6 → 3.5.9

package/template/.agents/skills/yss-product-lifecycle/references/state-model.md

@@ -14,6 +14,8 @@
 
 Matt 五态不得扩义。资产的 `ready-for-human` 与 Ticket label 必须带命名空间表达。`paused-human-gate` 表示等待 `.template-spec/agents/digital-human-roles.yaml` 指定的会签人（数字人或生物人），不是「必须是生物人」。但 `user_decision_policy` 命中的关键决定还必须有真实用户回复，数字人会签不能解除该等待。
 
+等待态不自动产生用户问题。按编排合同 `blocking_disposition`，专业等待自主派发或核对现有任务并等待；验证失败修复 / 路由，未知影响先调查。只有真实决定、新授权或无法自主取得的必要输入缺失，才先展示可审阅材料后询问，同时继续无依赖工作。完成结论本身不新增暂停，状态值和历史记录不因该执行规则改写。
+
 Slice v3 冻结需求文件的 status 是冻结时快照，不能用来推断当前执行状态。状态流转和验收结果写入已配置主 tracker / 任务包；需求改版后重新编译、审查与绑定批准，见 [Slice 冻结需求协议](../../yss-implementation-contract-compiler/references/slice-implementation-contract.md#第二轮增量规则)。
 
 ## 上下文与外部输入证据
@@ -73,7 +75,7 @@ AND UI 影响切片的前端实现还原计划已通过 schema 校验、`templat
 
 进入代码审查时保存 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest` 及 Spec、Ticket、合同、Checklist、YSS Execution Result 引用，并记录专项检查覆盖与机器检查结果。`worktree` 候选必须一次捕获 committed、staged、unstaged 和 untracked 文件；manifest 的按模式必填字段以及 `yss-worktree-candidate-v1`（raw path、uint64 big-endian 长度、tracked/untracked record、symlink 和不支持条目）以 `orchestration-contract.yaml.review_input` 为唯一执行定义。所有参与审查者（人数按 `orchestration-contract.yaml.gate_consolidation`） 消费同一不可变快照；返回后或完成 checkpoint 摘要变化则返回 `blocked` 并重新审查。Finding 分流不新增生命周期状态：`violation` 仍在当前合同路径由实现者修复后复审；`drift` / `new_impacts` 把合同标 `stale` 并走既有重路由。该清单只作为审查证据。
 
-Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。`git-submodule` 另保存每仓授权、`checkout_state` 和先子后父顺序；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点时不得当成普通目录 commit / 脚手架。
+Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。Agent 按既有 [用户决定协议](user-decisions.md) 从明确动作与范围的真实回复整理字段并保留原始来源，不要求用户重填。只有对应授权值严格为 `true`、范围和引用非空、来源可读、未撤回且动作在范围内时才执行；commit 不隐含 push。任一不满足时不执行对应动作并记录 checkpoint 判断。`git-submodule` 另保存每仓授权、`checkout_state` 和先子后父顺序；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点时不得当成普通目录 commit / 脚手架。
 
 ## 状态块
 

package/template/.agents/skills/yss-product-lifecycle/references/user-decisions.md

@@ -39,7 +39,7 @@ messages:
 
 `scripts/verify-user-decision --requirements <当前事项.json> <决定记录.yaml>` 校验当前消费者要求的 `boundary/subject_ref/scope`；未给 `--requirements` 时校验请求中全部事项。无回复的草案可以保存，但不能通过批准验证。局部批准只允许已明确批准的事项推进。
 
-会签记录新增 `subject_ref`、`approval_scope` 和 `user_decision_ref`；checkpoint 门禁同时声明 `subject_ref/approval_scope` 并与会签记录一致。`verify-approval-record` 默认严格验证当前放行条件，`--require-approved` 是显式等价选项；只有 `--history` 仅检查历史记录结构，不构成批准。恢复和门禁关闭必须使用严格校验。旧数字人记录仍可读取和用于专业审查，不自动升级成用户决定。
+会签记录保留 `subject_ref`、`approval_scope` 和适用的 `user_decision_ref`；checkpoint 门禁同时声明 `subject_ref/approval_scope` 并与会签记录一致。新会签及组合审查使用 schema v2；专业记录绑定当前 `review_task_ref/digest`、`capability_ids` 和 `basis`，能力与技能来源读取角色表，不在本协议复制。恢复和门禁关闭执行 `scripts/verify-approval-record --require-approved --checkpoint <current checkpoint>`，当前期望来自消费者 checkpoint / 任务，禁止复制待验记录作为期望。缺当前上下文不能放行；只有 `--history` 仅检查历史记录结构，不构成批准。历史记录可读，不自动升级为当前专业审查或用户决定；旧消费者拒绝 v2 后升级，不降级绕过。
 
 Workflow Execution Result 使用 `user_decisions` 保存当前要求与证据引用。`user_decision_not_applicable` 仅对未命中的既有技术条件门禁记录 `boundary/reason`，不得跳过已经执行的业务决策。完成结果通过 `validateNextRoute(..., result)` 检查；两参数调用仅检查路由结构，不能证明可以实际流转。
 
@@ -63,11 +63,11 @@ finding 分为 `requirement-violation/missing-evidence/important-risk/suggestion
 
 使用 `scripts/verify-user-decision --continuation <requirement.yaml>` 核验。会签记录可携带同一 `continuation_ref`；工作单元和任务包沿用 `user_decisions`，Plan 入口使用 `plan_continuation_ref`。实施仍校验当前 scope 清单、切片合同、仓库、允许写路径和工程基线，不因延续省略合同校验。旧记录维持严格读取；未登记该 capability 的接收端必须拒绝延续并升级，不能静默当普通批准。
 
-相邻专业检查可共用一个 `schema_version: 1, kind: review-bundle, reviews: [...]` 文件。每行都是已有会签记录形状，有唯一 gate/check ID、当前 subject/digest/scope、独立身份和明确结论；失败项不能被总体通过掩盖。`verify-approval-record` 检查所有行，聚合门禁按检查 ID 读取各自行。组合审查不增加用户确认次数，也不省略检查覆盖。
+相邻专业检查可共用一个 `schema_version: 2, kind: review-bundle, reviews: [...]` 文件；同一任务、会话、角色、运行时和独立主体完成适用能力检查，每行保留唯一 gate/check ID、当前 subject/digest/scope/basis、任务 / 能力绑定与明确结论。失败项不能被总体通过掩盖。`verify-approval-record` 用消费者当前上下文检查所有行，聚合门禁按检查 ID 读取各自行。组合审查不增加用户确认次数，也不省略检查覆盖。首轮完整覆盖适用项，修复后依据差异、受影响结论 / 行为及依赖定向复审并重新绑定当前候选；摘要变化、UI 或 `new_impacts` 不默认触发全部审查轴，未知先调查。未受影响结论复用必须有比较依据，历史原记录保持只读。
 
 ## 实施范围与架构选择
 
-首次实施批准的主体为功能级 `implementation-scope` 清单，`slices` 每行包含：`ticket_ref`、`contract`（ref/version/digest）、`repositories`、`allowed_write_paths`、`baselines`（ref/version/digest）。仓库与写路径必须对应当前合同的实施范围（v2 `common.project_roots/allowed_write_paths`，v3 `scope.project_roots/allowed_write_paths`，通过统一读取器核验）；基线包含合同引用的工程基线。`scope` 使用批准的切片引用集合。合同、范围或基线变化时回到确认；已覆盖的后续切片复用原记录。
+首次实施批准的主体为功能级 `implementation-scope` 清单，`slices` 每行包含：`ticket_ref`、`contract`（ref/version/digest）、`repositories`、`allowed_write_paths`、`baselines`（ref/version/digest）。仓库与写路径必须对应当前合同的实施范围（v2 `common.project_roots/allowed_write_paths`，v3 `scope.project_roots/allowed_write_paths`，通过统一读取器核验）；基线包含合同引用的工程基线。`scope` 使用批准的切片引用集合。合同、范围或基线变化时先调查差异，复核当前合同、定向审查和授权延续；实质决定变化或超出原批准边界时展示差异后确认，未查明时不沿用。已覆盖的后续切片复用原记录。
 
 实施就绪和派发必须同时提供 `user_decisions`、`slice_contract_ref` 与 `vertical_slice_ticket_ref`。Worker 任务包通过 `user_decisions` 传递记录，不能只声明 `ready_for_agent=true`。
 

package/template/.agents/skills/yss-prototype-stage/SKILL.md

@@ -9,11 +9,7 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 把产品设计影响收敛为跨 Agent 一致的原型交付物、证据和生命周期回流合同。它不替代 `yss-product-lifecycle` 的门禁裁决，也不把原型当作生产前端代码。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
-
-## 文档写作
-
-起草或修订交互说明、状态说明和设计结论前，读取 `.template-spec/process/document-writing.md` 的共用写法及产品设计指引；原型视觉和行为仍消费当前设计合同。
+起草或修订交互说明、状态说明和设计结论时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及产品设计指引。作用域仅限当前产物；派发时传递条件及引用，原型视觉和行为仍消费当前设计合同。
 
 ## 进入条件与主入口
 

package/template/.agents/skills/yss-prototype-stage/scripts/verify-prototype-design.mjs

@@ -26,6 +26,7 @@ export async function verifyPrototypeDesign({scope='all',toolchain=process.env.Y
  if((await readdir(output)).length)throw Error('验证输出非空，拒绝覆盖历史证据');
  const report={schema_version:1,scope,status:'running',started_at:new Date().toISOString(),output,source:null,tools:{node:process.version},checks:[],counts:{passed:0,failed:0,'not-executed':0,'not-applicable':0},limitations:['自动化结果不构成人工视觉批准、读屏结论或真实用户效果。']};
  const env={...process.env,TMPDIR:output,YSS_PROTOTYPE_EVIDENCE_DIR:output};
+ delete env.NODE_TEST_CONTEXT; // 子进程独立输出 TAP，不继承父级 node --test 的内部传输协议。
  const add=(id,status,reason,extra={})=>report.checks.push({id,status,...(reason?{reason}:{}),...extra});
  async function run(id,args){
   const log=path.join(output,id+'.log'),command=[process.execPath,...args];

package/template/.agents/skills/yss-repository/SKILL.md

@@ -7,6 +7,8 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 
 本 Skill 消费批准合同，将持久化责任落到选定架构 Profile。它不是完整脚手架，也不从 DDL、表名或示例反向创造领域/API 合同。
 
+只读审计可先盘点实际结构并记录缺失合同，不受实施前置阻止；整改仍需批准且当前的 Slice。既有工程使用有效登记与独立观测，不要求补造生成 Manifest。
+
 ## 架构分流
 
 1. 读取当前 Slice Implementation Contract 的 `architecture_identity`、`persistence_profile`、实现仓登记、数据合同、`allowed_write_paths` 和预期证据。
@@ -57,5 +59,3 @@ description: 用于按批准的 YSS 架构与持久化合同实现或重构 PO
 ## 新脚手架平台约束
 
 消费批准切片架构身份中的 `platform_configuration`，并与工程 Manifest、effective POM 和依赖树核对。命中 MyBatis 时，`framework.mybatis` 必须从该配置指向的 compatibility 条目解析出对当前架构有效的 `component_binding`；构件、摘要、源码 tree、证据或绑定状态不一致时回合同编译器阻断。Validation namespace、Jackson、starter 和处理器版本只消费解析后的精确平台事实，不在本 Skill 中按 Boot 大版本推导。不得在业务实现中升级、降级或替换 YSS 组件；平台迁移使用独立迁移工作单元。详见仓库共享合同 `.template-spec/engineering/backend-platforms.md`。
-
-只读审计可先盘点、记录缺失合同；不得用实施前置要求阻止发现既有违规。整改仍需批准合同，不因缺少生成 Manifest 阻断已有效登记的既有工程。

package/template/.agents/skills/yss-research/SKILL.md

@@ -1,83 +1,74 @@
 ---
 name: yss-research
-description: "研究 YSS 技术或产品策略事实并提供可追溯证据；用于标准、第三方行为、业务约束和 research 兼容入口。"
+description: "研究 YSS 技术与产品策略事实，统一发起竞品调研并组织证据、功能矩阵和深度报告；用于标准、第三方行为、业务约束和 research 兼容入口。"
 ---
 
 # YSS Research
 
-Investigate facts that a YSS decision depends on. Produce evidence and bounded conclusions; do not make or approve the downstream product, domain, architecture, or release decision.
+调查 YSS 决定所依赖的事实，输出可追溯证据和有边界的结论；不作出或批准下游产品、领域、架构或发布决定。
 
-`research` is a deprecated compatibility alias. Use `yss-research` in new assets and routing.
+`research` 是已弃用的兼容别名，新资产和路由使用 `yss-research`。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
-
-## 文档写作
-
-撰写研究简报或结论前，读取 `.template-spec/process/document-writing.md` 的共用写法和研究指引；既有证据结构、来源限定和校验器要求保持完整。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，先读 `.template-spec/process/document-writing.md` 的共用写法和研究指引；作用域仅限当前产物，派发时传递条件及引用。保持原证据结构、来源限定和校验要求。
 
 ## Profiles
 
-- `technical-evidence`: standards, official documentation, source code, third-party APIs, framework behavior, protocols, or implementation constraints. Decision-bearing claims must trace to primary sources.
-- `strategy-evidence`: user problems, business constraints, MVP/non-goal evidence, success criteria, domain-boundary signals, core business-rule evidence, and stage-decision inputs. This profile may consume direct-experience and near-primary evidence with explicit limitations.
+- `technical-evidence`：标准、官方文档、源码、第三方 API、框架行为、协议和实现约束。决定性 Claim 必须追溯到一手来源。
+- `strategy-evidence`：用户问题、业务约束、MVP / 非目标、成功标准、领域边界、核心业务规则和方案决策输入。允许直接经验与近一手证据，须写明限制。
 
-Route competitor, pricing, category, and market-position research to `competitive-intelligence`; consume its cited result rather than duplicating it. Route product UI and workflow-friction scans to `product-design:research` when that platform skill is available. `yss-research` may synthesize their outputs but does not replace their specialist contracts.
+竞品、定价、品类和市场定位研究由本技能统一接收，路由 `competitive-intelligence` 执行，本技能持有模式、研究证据包和结果汇总。竞品策略使用 `strategy-evidence`；其中技术能力和协议事实仍须按 `technical-evidence` 的一手来源要求审计。产品 UI 与流程摩擦扫描在平台技能可用时路由 `product-design:research`。本技能可以综合专项结果，不替代专项合同。
 
-## Modes
+## Modes 与输出选择
 
-- `quick` is the default for exploratory fact finding. Return an in-chat brief unless the user asks to persist it.
-- `evidence-audited` is required when research directly informs a persisted Spec, domain strategy, stage decision, OpenAPI, architecture decision, or another lifecycle approval input. It is also used when the user explicitly asks for deep, strict, reproducible, or auditable research.
+- `quick`：普通探索的默认模式，返回聊天简报；竞品探索同时提供精简功能矩阵，除非用户明确只要报告或矩阵。用户未要求落盘时不创建文件。
+- `evidence-audited`：深度、严格、可复现、可审计研究，以及直接用于持久化 Spec、领域策略、方案决策、OpenAPI、架构或其它生命周期批准输入的研究。竞品深度研究默认输出完整矩阵、深度报告和现有研究双文件。
 
-Do not silently promote an exploratory request solely because more rigor would be nice. State the active profile and mode before searching; explain when a downstream lifecycle use requires promotion.
+开始检索前说明 profile、模式和输出选择。不要仅为提高严谨性把普通探索升级。用户明确只要矩阵或报告时遵从输出选择；选择阅读材料不免除审计模式的证据包。探索材料标明未审计，作为批准输入前须升级并完成审计。
 
-## Source policy
+竞品调研读取 [竞品分析合同](references/competitive-analysis.md)，复用 `.template-spec/plan/templates/competitive-matrix-template.md` 和 `.template-spec/plan/templates/competitive-analysis-template.md`。不新增 profile、模式、生命周期阶段或批准门禁。
 
-1. Start from the decision, audience, time horizon, scope, and questions the research must answer.
-2. Search user-provided or registered material first, using the same inclusion and exclusion criteria as external material. Record exclusions and access failures.
-3. For `technical-evidence`, follow each decision-bearing claim to the official specification, official docs, source code, or first-party API that owns it.
-4. For `strategy-evidence`, classify sources as primary, direct experience, near-primary, secondary, or lead-only. Interviews, tickets, support records, dated reviews, surveys, and credible industry reports are allowed with their sampling and access limits.
-5. Treat untraceable reposts, aggregator snippets, and AI-generated summaries as leads only. They cannot support a published claim.
-6. Seek counter-signals and conflicting evidence. Source count alone is not frequency or confidence.
+## 来源政策
 
-## Delegation
+1. 从要支持的决定、读者、时间范围、边界和研究问题开始。
+2. 先检索用户提供或已登记的材料，对内部与外部材料采用相同纳入 / 排除标准，记录排除和访问失败。
+3. 技术 Claim 追溯到拥有该事实的官方规范、官方文档、源码或第一方 API。
+4. 策略来源分类为 `primary`、`direct-experience`、`near-primary`、`secondary`、`lead-only`；访谈、Ticket、支持记录、带日期的评论、调查和可信行业报告须说明抽样与访问限制。
+5. 无法追溯的转载、聚合摘要和 AI 生成总结只作线索，不支持发布结论。
+6. 主动寻找反向信号和冲突证据，来源数量不代表频率或置信度。
 
-Use a background Agent when the runtime supports it and the reading can proceed independently while other useful work continues. Otherwise research in the current Agent. Delegation is an execution optimization, not a trust signal.
+## 委派
 
-Read-only intake uses task-package schema v2 with `contract.kind: read-only-intake`, `Explorer`, a registered intake work unit and an empty write set. Use `scripts/prepare-read-only-intake` and `scripts/run-read-only-intake`; the dispatcher keeps task and execution evidence outside the repository. No maintenance checkpoint is needed for research intake. No executed commands means `verification_status: not-executed`, not verified. Formal asset writes require owner impact analysis and a new formal task package. See `.template-spec/process/subagent-collaboration.md`.
+运行时支持后台 Agent 且资料可独立阅读时可以委派；否则在当前 Agent 研究。委派用于优化执行，不构成可信度证明。
 
-Lifecycle dispatches must use the repository's structured task package, write isolation, role binding, and handoff contract. The owner receiving the result remains responsible for verifying material claims before consuming them.
+只读分诊使用 task-package schema v2、`contract.kind: read-only-intake`、`Explorer`、已登记分诊工作单元和空写范围；使用 `scripts/prepare-read-only-intake`、`scripts/run-read-only-intake`，执行证据留在仓库外。无已执行命令时写 `verification_status: not-executed`。正式落盘前由所有者分析影响并派发正式任务包，详见 `.template-spec/process/subagent-collaboration.md`。
 
-## Evidence-audited workflow
+只读分诊的独立运行包继续作为证据来源，并由运行存储保护。使用 `scripts/runtime-store inspect` 定位运行，`export` 导出可独立核验的文件包；留存与恢复按 `.template-spec/process/runtime-storage.md` 执行。
 
-Follow [evidence-contract.md](references/evidence-contract.md):
+生命周期派发遵守结构化任务包、写隔离、角色绑定与交接合同；接收所有者仍负责核验实质 Claim。
 
-1. Predeclare the research scope, source classes, inclusion/exclusion criteria, and known access limits.
-2. Maintain a reproducible Search Log and independently locatable Evidence Ledger.
-3. Separate observations, inference, hypotheses, and decisions.
-4. Audit each decision-bearing claim against the evidence it cites, including counter-signals.
-5. Narrow partially supported claims; mark unsupported claims `needs-deeper-research`.
-6. Persist `<slug>-research-brief.md` with adjacent `<slug>-evidence.yaml` and run the bundled validator.
+## 审计工作流
 
-For `strategy-evidence`, every claim that determines a user problem, MVP/non-goal, domain boundary, core business rule, success criterion, important business constraint, or stage-decision basis is decision-bearing and must be audited. Background context may be sampled only when explicitly marked non-decision-bearing.
+按 [证据合同](references/evidence-contract.md) 执行：
 
-## Ownership boundary
+1. 预声明范围、来源类别、纳入 / 排除标准及已知访问限制。
+2. 保存可复现 Search Log 和可独立定位的 Evidence Ledger。
+3. 区分观察、推断、假设和决定。
+4. 对每项决定性 Claim 审计来源与反向信号。
+5. 缩窄部分支持的措辞；无支持的 Claim 标记 `needs-deeper-research`。
+6. 保存相邻的 `<slug>-research-brief.md` 与 `<slug>-evidence.yaml` 并执行校验。
 
-- Research output is evidence, not approval.
-- `domain-modeling` owns glossary changes; `yss-stage-decision` owns domain strategy and the stage-decision package.
-- The lifecycle orchestrator and designated reviewers own gate state.
-- Do not modify `CONTEXT.md`, Spec, domain-strategy, OpenAPI, architecture, Ticket status, or approval records unless a separately authorized owning work unit performs that change.
+策略研究中决定用户问题、MVP / 非目标、领域边界、核心规则、成功标准、重要业务约束或方案决策基础的 Claim 全部审计；只可对明确标记为非决定性的背景抽样。
 
-## Output
+## 所有权与交付
 
-A quick brief includes scope, findings, sources, inference, confidence, counter-signals, gaps, and the next decision it informs.
+研究结果是证据。候选术语交给 `domain-modeling`，产品机会、MVP 和方案建议交给 Plan / `yss-stage-decision` 所有者；生命周期编排器和指定 Reviewer 持有门禁状态。未经另一项已授权所有者工作单元，不修改 `CONTEXT.md`、Spec、领域策略、OpenAPI、架构、Ticket 状态或批准记录。
 
-For persisted `evidence-audited` work, start from [research-brief-template.md](assets/research-brief-template.md) and [evidence-template.yaml](assets/evidence-template.yaml). Run from this skill directory:
+聊天简报包括范围、发现、来源、推断、置信度、反向信号、缺口及下一项决定。审计包从 [研究简报模板](assets/research-brief-template.md) 和 [证据模板](assets/evidence-template.yaml) 起草。竞品附属报告不能替代研究双文件。从仓库根运行：
 
 ```bash
-node scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
+node .agents/skills/yss-research/scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
 ```
 
-In `template-source`, save reusable maintenance research under the existing `.template-source/evidence/maintenance/` convention. In `project-instance`, use the project research/evidence convention and bind any decision-bearing output from the lifecycle asset that consumes it.
-
-模板中正式落盘的研究使用 `work-unit.maintenance-research`，按 `.template-spec/process/research-completion.md` 记录当前验证并收尾；结束研究不授予维护或产品批准。仅回传结论的只读分诊继续使用既有 read-only-intake v2，不伪装成正式研究闭包。
+`template-source` 的可复用维护研究存于 当前工作区仓外的 `maintenance:research/<run-id>/`（用 `scripts/maintenance-path` 解析；证据引用绑定原字节摘要）；`project-instance` 沿项目研究 / 证据约定，并由消费生命周期资产绑定决定性输出。模板正式研究使用 `work-unit.maintenance-research`，按 `.template-spec/process/research-completion.md` 记录当前验证并收尾；只回传结论的分诊继续用 read-only-intake v2。
 
-If sources are unavailable or conflict, state the limitation. Ordinary gaps lower confidence; a missing or mismatched source for a decision-bearing claim prevents that claim from being treated as established.
+来源不可用或冲突时说明限制。普通缺口降低置信度；决定性 Claim 的来源缺失或不匹配时不能视为已确立。研究完成不授予维护或产品批准。

package/template/.agents/skills/yss-research/assets/competitive-evidence-template.yaml

@@ -0,0 +1,146 @@
+{
+  "schema_version": 1,
+  "profile": "strategy-evidence",
+  "mode": "evidence-audited",
+  "scope": {
+    "topic": "<竞品调研主题>",
+    "audience": "<audience>",
+    "time_horizon": "<time horizon>",
+    "research_questions": [
+      "<指定产品、套餐与地区范围内的能力支持情况>"
+    ],
+    "inclusion_criteria": [
+      "<criterion>"
+    ],
+    "exclusion_criteria": [
+      "<criterion>"
+    ]
+  },
+  "ownership": {
+    "research_owner": "yss-research",
+    "downstream_owner": "<lifecycle skill or role>",
+    "decision_ref": null
+  },
+  "search_log": [
+    {
+      "id": "search-001",
+      "channel": "<channel or corpus>",
+      "query_or_corpus": "<query or inspected material>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "results-found"
+    },
+    {
+      "id": "search-002",
+      "channel": "<counter-signal channel>",
+      "query_or_corpus": "<counter-signal query>",
+      "searched_at": "YYYY-MM-DD",
+      "result": "none-found"
+    }
+  ],
+  "evidence_items": [
+    {
+      "id": "evidence-001",
+      "source_level": "direct-experience",
+      "visibility": "internal",
+      "source_class": "<interview, support, ticket, docs, specification, source-code, dataset, report>",
+      "source_ref": "<URL or repository reference>",
+      "locator": "<line, section, record, timestamp, or comment>",
+      "stance": "support",
+      "observed_at": "YYYY-MM-DD",
+      "evidence_date": "YYYY-MM-DD",
+      "observation": "<what the source directly shows>",
+      "limitations": [
+        "<sampling, recency, access, or independence limit>"
+      ]
+    }
+  ],
+  "claims": [
+    {
+      "id": "claim-001",
+      "claim_kind": "business-constraint",
+      "statement": "<在已确认的产品版本、套餐与地区内，竞品A支持能力1；据来源实际内容填写>",
+      "decision_bearing": true,
+      "evidence_refs": [
+        "evidence-001"
+      ],
+      "counter_signal_refs": [
+        "search-002"
+      ],
+      "audit_status": "supported",
+      "confidence": "medium",
+      "disposition": "publish"
+    }
+  ],
+  "source_gaps": [],
+  "audit_summary": {
+    "status": "complete",
+    "audited_claim_ids": [
+      "claim-001"
+    ],
+    "notes": []
+  },
+  "competitive_analysis": {
+    "schema_version": 1,
+    "output_selection": "both",
+    "as_of": "YYYY-MM-DD",
+    "comparison_scope": "<用户、竞品、能力与资料边界；未知字段使用 unknown>",
+    "competitors": [
+      {
+        "id": "competitor-a",
+        "name": "<竞品A>",
+        "type": "direct",
+        "product": "<产品>",
+        "version": "<已确认版本或 unknown>",
+        "edition": "<已确认套餐或 unknown>",
+        "region": "<已确认地区或 unknown>"
+      },
+      {
+        "id": "competitor-b",
+        "name": "<竞品B>",
+        "type": "adjacent",
+        "product": "<产品>",
+        "version": "unknown",
+        "edition": "unknown",
+        "region": "unknown"
+      }
+    ],
+    "capabilities": [
+      {
+        "id": "capability-001",
+        "module": "<功能模块>",
+        "name": "<功能点>",
+        "definition": "<可观察的能力定义>",
+        "user_value": "<用户价值>"
+      }
+    ],
+    "assessments": [
+      {
+        "competitor_id": "competitor-a",
+        "capability_id": "capability-001",
+        "status": "supported",
+        "claim_refs": [
+          "claim-001"
+        ],
+        "limitations": [
+          "<来源实际支持的版本、套餐、地区及其他限制；不能仅按示例填写>"
+        ],
+        "gap": null
+      },
+      {
+        "competitor_id": "competitor-b",
+        "capability_id": "capability-001",
+        "status": "unknown",
+        "claim_refs": [],
+        "limitations": [],
+        "gap": {
+          "reason": "<公开资料尚未确认支持情况；未搜索到不代表不支持>",
+          "next_step": "<明确补充官方资料、试用或访谈的执行计划>"
+        }
+      }
+    ],
+    "artifacts": {
+      "matrix": "<slug>-competitive-matrix.md",
+      "report": "<slug>-competitive-analysis.md"
+    }
+  }
+}

package/template/.agents/skills/yss-research/references/competitive-analysis.md

@@ -0,0 +1,76 @@
+# 竞品分析合同
+
+本合同在现有 research evidence v1 上增加可选 `competitive_analysis` 扩展。`yss-research` 持有研究模式、证据包和汇总，`competitive-intelligence` 执行专项分析。父级 `search_log`、`evidence_items`、`claims` 是唯一检索、来源与 Claim 台账；竞品扩展引用这些 ID，不另建台账。
+
+## 1. 模式与输出
+
+普通探索采用 `quick`，在聊天中给出简报和精简功能矩阵，标明未审计；用户未要求落盘时不写文件。深度、严格、可复现、可审计请求以及正式生命周期批准输入采用 `evidence-audited`。深度默认 `output_selection: both`；用户明确只要矩阵或报告时使用 `matrix` 或 `report`，证据审计要求不变。
+
+竞品策略研究用 `strategy-evidence`；其中技术能力和协议 Claim 必须满足 `technical-evidence` 的一手来源要求。竞品确定状态引用 `technical-fact` Claim 时，校验器要求至少一项 `primary` 支持证据，独立于父 profile 和 `decision_bearing`；`unknown` 不作确定判断，仍须记录来源缺口与补证计划。不得把已知技术事实改标为 `background` 绕过此要求；是否属于技术能力或协议事实仍须来源语义审核。不要新增 profile 或模式。探索材料作为正式批准输入前须升级为审计包。
+
+审计模式始终保留相邻的 `<slug>-research-brief.md` 与 `<slug>-evidence.yaml`。按选择追加 `<slug>-competitive-matrix.md`、`<slug>-competitive-analysis.md`；深度报告不能替代简报。`template-source` 使用 当前工作区仓外的 `maintenance:research/<run-id>/`（用 `scripts/maintenance-path` 解析；证据引用绑定原字节摘要），`project-instance` 沿项目研究 / 证据目录约定。
+
+## 2. 可选扩展接口
+
+| 字段 | 内容 |
+|---|---|
+| `schema_version` | 固定为 `1` |
+| `output_selection` | `matrix`、`report` 或 `both` |
+| `as_of` | 调研截至日期，`YYYY-MM-DD` |
+| `comparison_scope` | 本次用户、能力、用途、时间范围及非目标 |
+| `competitors` | 对象列表；每项为 `{id, name, type, product, version, edition, region}` |
+| `capabilities` | 能力列表；每项为 `{id, module, name, definition, user_value}` |
+| `assessments` | 全部竞品 × 能力结果；每项为 `{competitor_id, capability_id, status, claim_refs, limitations, gap}` |
+| `artifacts` | 同目录附属文件名：`matrix` / `report`，由输出选择决定必填项 |
+
+竞品和能力 ID 稳定且在各自列表唯一；每个竞品 × 能力组合恰有一个 assessment。竞品 `version`、`edition`、`region` 等未确认信息明确写 `unknown`，不能推定适用于所有版本、套餐或地区。能力定义写可观察的功能范围，`user_value` 说明服务的用户任务；不把不同功能因名称相近合并。
+
+`claim_refs` 引用父级 Claim ID，`limitations` 为限定条件列表。`gap` 是 `null` 或 `{reason, next_step}`；未知必须给出无法判断的原因和补证步骤，不能用空缺口代替。决定性比较结果使用已审计 Claim；引用措辞应包含适用的产品、版本 / 套餐、地区、日期与能力范围，审核者须核对来源实际支持范围。
+
+`artifacts.matrix` 固定命名为 `<slug>-competitive-matrix.md`，`artifacts.report` 固定命名为 `<slug>-competitive-analysis.md`。只允许与证据文件同目录的文件名，不允许绝对路径、子目录、`..` 或符号链接逃逸；渲染和校验均应拒绝不安全路径。
+
+未包含扩展的旧 evidence v1 包继续使用原合同与校验行为；不回写历史证据、报告和收尾记录。
+
+## 3. 支持状态与证据
+
+| `status` | 展示 | 判定要求 |
+|---|---|---|
+| `supported` | ✅ 明确支持 | 已审计 Claim 支持定义范围内的能力，记录适用条件 |
+| `partial` | ⚠️ 部分支持 | 已审计 Claim 支持其中一部分；`limitations` 明确缺少的部分或限制 |
+| `absent` | ❌ 明确不支持 | 已审计 Claim 支持该范围内的不支持判断；搜索无结果不能作为依据 |
+| `unknown` | ❓ 未知 | 可没有支持 Claim；`gap.reason` 和 `gap.next_step` 必填 |
+
+资料不完整、访问失败、版本未确认或来源冲突，不能直接转换成 `partial` 或 `absent`。先缩窄到可审计的范围，仍无法判断时使用 `unknown`。已审计 Claim 的 `partially-supported` 结果只能在按原合同限定措辞后消费，不能把未覆盖部分当作已确立。
+
+反向信号仍记录在父级台账。`none-found` 只说明声明的搜索没有找到反例，不证明竞品缺失能力。支持状态与 Claim 审计状态是不同字段，不能彼此替代。
+
+## 4. 阅读材料和受控渲染
+
+直接使用 `.template-spec/plan/templates/competitive-matrix-template.md` 和 `.template-spec/plan/templates/competitive-analysis-template.md`。每文件恰有一组完整标记：
+
+```markdown
+<!-- YSS-COMPETITIVE:START -->
+[由结构化比较结果生成]
+<!-- YSS-COMPETITIVE:END -->
+```
+
+管理区由工具维护，禁止手填比较事实；区外保留人工定位、流程、机会和建议。矩阵管理区生成截至日期、范围、竞品版本 / 套餐 / 地区、能力定义、功能状态表及 Claim / 缺口摘要。`report` 的报告管理区包含完整对比表；`both` 的报告管理区引用同目录完整矩阵，并保留证据摘要。只选择矩阵时不生成报告。
+
+从仓库根运行：
+
+```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
+```
+
+从技能目录运行时可使用 `node scripts/render-competitive-outputs.mjs` 和 `node scripts/validate-research-package.mjs` 的同一参数。新文件从现有模板创建；刷新已有文件仅替换唯一完整管理区，保留区外字节。旧文件无标记、标记重复或不完整时拒绝覆盖，由所有者另行安排适配；不自动把旧报告认定为当前产物。
+
+渲染后的人工正文应消除模板占位项；每项实质结论引用 Claim / 可定位来源，观察、推断、假设和建议分开。默认不生成数字排名；用户明确要求评分时先确认量表、维度 / 权重和依据，未知写不评分，不能作为低分或零分。
+
+## 5. 校验与收尾
+
+校验先执行完整 JSON Schema，再检查唯一 ID、完整比较覆盖、引用、状态限定、选定文件和受控区一致性。重复或失效 ID、缺失产物、未知缺口未说明、部分支持未限定、确定状态无审计 Claim、表格漂移和不安全路径均返回非零退出码与定位诊断。机械校验不能证明来源语义、采样代表性或推断合理性。
+
+模板正式研究按 `.template-spec/process/research-completion.md` 收尾。含竞品扩展时，研究收尾记录条件追加选定矩阵 / 报告和新增校验依赖的 `{ref, digest}`，并纳入 `evidence_refs`。接收端核验当前字节并重跑校验；附属报告、结构化结果、Schema 或渲染逻辑变化后旧验证失效。旧包和旧收尾记录保持读取兼容，不据此宣布新产物已验证。
+
+功能矩阵与深度报告只提供研究证据。候选术语交给 `domain-modeling`；机会、MVP / 非目标、优先级和待确认问题交给 Plan、Spec 或其它对应所有者。研究不直接写入 `CONTEXT.md`、Spec、OpenAPI、架构、Ticket 状态或批准，也不设置 `ready-for-agent`。