create-yss-spec 2.1.7 → 2.1.9

package/template/.claude/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -5,42 +5,48 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 ## 入口与仓库身份裁决
 
 - 所有入口先读取 `yss-project.yaml`。缺失、解析失败、schema 不支持或 `repository_mode` 非法时，停止路由并进入 migration-check。
-- **直接调用 `ask-matt`** 时，它只能提供通用 Matt flow 导航；有效 YSS 仓库必须把最终阶段、影响面、门禁和状态裁决交回 `yss-product-lifecycle`。
-- **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用 `ask-matt`；编排器直接使用兼容映射。Matt skills 作为固定上游使用，不在 YSS 精简中修改。
+- **直接调用 `ask-matt`** 时，它只能提供通用 Matt flow 导航，不得写生命周期资产、改变门禁或 Ticket 状态；有效 YSS 仓库必须在任何写入前把最终阶段、影响面、门禁和状态裁决交回 `yss-product-lifecycle`。
+- **直接调用生命周期管理的 Matt user-invoked skill**（`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`implement`）时，用户仍是正式资产的创建者；生命周期先校验前置条件，再接受结果并重新计算阶段、门禁和状态。它们不适用 `ask-matt` 的 `navigate-only` 限制。其他 user-invoked skill 同样不得由生命周期自动调用；只有在其专属适配合同存在时才进入 YSS 流程。
+- **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用任何 Matt user-invoked skill；编排器直接使用兼容映射，并只调用允许的 model-invoked 原语。Matt user-invoked skill 保持显式入口，生命周期只准备、校验并验收其结果。
 - `template-source` 只允许进入模板维护流程。命中 `to-spec`、`to-tickets`、`implement`、Release 或 Retrospective 时返回 `blocked`，原因是 `template-source-product-artifact-forbidden`；`ask-matt` 和 `setup-matt-pocock-skills` 都不得为具体产品生成 Spec、prototype、OpenAPI 或垂直切片 Ticket。
 - `project-instance` 才允许进入产品 Discovery → Spec → 设计 → 契约 → Ticket → 实现 → Release / Retrospective 链路。
 
 | 情形 | Matt flow | 生命周期验收 |
 |---|---|---|
-| 首次启用或配置缺失 | `setup-matt-pocock-skills` | 幂等核对 tracker、真实标签和领域布局；冲突时迁移而非覆盖 |
+| 首次启用或配置缺失 | `setup-matt-pocock-skills`（用户显式） | `needs-human`，说明缺失项；用户完成 setup 后重新计算 readiness |
 | 通用入口 | `ask-matt` | 检测到 YSS 后由本编排器最终裁决 |
-| 需求澄清 | `grill-with-docs`、`domain-modeling` | 按退出判定检查未决项和回流 |
+| 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder` | map 真正完成后 `handoff → to-spec` |
 | 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
-| Spec 综合 | `to-spec` | 初稿进入 `ready-for-human`，不得直接实现 |
-| 切片 | `to-tickets` | 仅在冻结/无影响记录后拆垂直切片；初始角色为 `ready-for-human` |
-| 实现 | `implement`、`tdd` | `yss-router` 编译 Slice Implementation Contract 草案；本编排器核验并持久化后才执行，专项 Execution Result 返回后再次核验 |
+| Spec 综合 | `to-spec`（用户显式） | 生命周期准备与验收；初稿进入 `ready-for-human`，不得直接实现 |
+| 切片 | `to-tickets`（用户显式） | 生命周期准备与验收；仅在冻结/无影响记录后拆垂直切片，初始角色为 `ready-for-human` |
+| 实现 | `implement`（用户显式） | `yss-router` 编译 Slice Implementation Contract 草案；本编排器核验并持久化后才允许用户启动 implement；其内部按自身流程使用 `tdd`，结果回交后再次核验 |
 | Bug | `diagnosing-bugs`、`tdd` | 先建立红色反馈；高风险影响升级上游门禁 |
 | 审查 | `code-review` | 唯一默认代码审查入口；审查者独立，结合 Spec、仓库治理规则和 YSS 标准 |
 | 跨上下文 | `handoff` | 保存来源、阶段、未决项、命令和下一责任人 |
 | 阶段边界 | `PHASE-BOUNDARIES.md` | 按 `Continue → /clear → /handoff → subagent → /compact` 选择上下文动作；只记录证据，不扩展生命周期状态 |
 | 解释未落地 | `wait-what` | 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` |
-| 人工步骤 | `wizard` | 只处理 Agent 无法替代的点击、审批、凭据和迁移步骤；默认临时使用，秘密值必须隐藏并脱敏 |
-| 编写 Agent 文档 | `writing-for-agents`、`writing-skills` | 共享 skill 只改 `.agents/skills`；流程文档保持简体中文 |
+| 人工步骤 | 人工 checkpoint | 记录 Agent 无法替代的点击、审批、凭据和迁移步骤；秘密值必须隐藏并脱敏 |
+| 编写 Agent 文档 | `writing-for-agents`；维护 skill 时使用 `maintaining-skills` | 共享 skill 只改 `.agents/skills`；流程文档保持简体中文 |
 
 尽量不修改 Matt skill 以复制 YSS 规则。只有它违反模板硬门禁时才做最小兼容修改。
 
 Router 只能返回 `draft`、`blocked` 或 `ready-for-lifecycle-review`，不得自行批准合同、设置 `ready-for-agent` 或宣布完成。`new_impacts`、`drift`、`violation`、越界路径或缺失实际验证会暂停当前工作单元，并由本编排器决定增量重路由、完整重路由或回到更早生命周期阶段。
 
-## Matt Skill Result
+## Workflow Execution Result
 
-Matt skill 的自然语言执行结果必须先归一化为 `Matt Skill Result`，再由生命周期编排器验收。结果至少包含：
+生命周期工作单元必须输出 `Workflow Execution Result`，再由编排器验收。旧 `Matt Skill Result` 仅可通过只读 compatibility adapter 归一化，且不得影响路由或作为行为基线；workflow reference 不表示调用了对应 Matt user-invoked skill。结果至少包含：
 
 ```yaml
+result_schema: workflow-execution-result-v1
+work_unit: work-unit.spec-synthesis
+workflow_reference:
+  source: mattpocock/skills
+  skill: to-spec
+  invocation_mode: reference
 result: completed # completed / blocked / needs-human / failed
-skill: <skill-name>
 evidence_refs:
   - docs/process/yss-product-lifecycle-orchestrator-validation.md
 changed_artifacts: []
@@ -54,15 +60,17 @@ blocking_signals: []
 
 Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-for-lifecycle-review → needs-human`。这里的 `completed` 只表示 Matt 工作单元已产出可验收结果，不表示生命周期完成或可发布。
 
-`completed` 的 `evidence_refs` 至少包含一条可读取或可解析的证据引用；只有字段存在但为空，不能证明工作单元完成。
+`completed` 的 `evidence_refs` 至少包含一条可读取或可解析的证据引用；只有字段存在但为空，不能证明工作单元完成。正式 Spec、Ticket 或实现资产仍只能由对应显式用户入口创建。
 
 ## Matt flow 前置条件
 
 | Matt flow | 进入条件 | 生命周期结果 |
 |---|---|---|
-| `to-spec` | `grill-with-docs` 已满足退出条件，且不存在未回流的 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | Spec 初稿为 `ready-for-human`，不等于批准 |
-| `to-tickets` | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 只能生成垂直切片 Ticket；YSS active 的 `to-tickets` 初始统一为 `ready-for-human` |
-| `implement` | `ready-for-agent` 公式、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 单会话实现同样适用，不得绕过门禁 |
+| `to-spec`（用户显式） | Discovery work unit 或 `grill-with-docs` 已满足退出条件，且不存在未回流 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | 生命周期只准备/验收；Spec 初稿为 `ready-for-human`，不等于批准 |
+| `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human` |
+| `implement`（用户显式） | `ready-for-agent` 公式、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁 |
+
+`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
 
 ## Review 候选与 Git 授权
 
@@ -70,9 +78,11 @@ YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mod
 
 Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
 
+“然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
+
 ## Setup readiness
 
-编排器先做幂等 readiness 检查，再决定是否调用 `setup-matt-pocock-skills`。检查结果只能是：
+编排器先做幂等 readiness 检查。`missing` 时不得调用 `setup-matt-pocock-skills`，而是结构化暂停并请用户显式运行它。检查结果只能是：
 
 `ready`、`missing`、`conflict`、`degraded`、`not-applicable`。
 
@@ -82,6 +92,8 @@ Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明
 
 当 YSS 生命周期处于 active 状态时，Matt `to-spec` 中独立运行时的 `ready-for-agent` 发布提示由本适配层覆盖为 `ready-for-human`：Spec 必须先经过产品总体设计 / 功能架构、必要的设计与契约门禁，之后才由生命周期编排器决定垂直切片 Ticket 的 `ready-for-agent`。这只约束 YSS 编排下的状态写入，不修改 Matt skill 单独运行时的核心行为。
 
+`setup-matt-pocock-skills` 仅由用户显式启动。readiness=`missing` 时返回 `needs-human`、`requested_skill=setup-matt-pocock-skills` 和 `resume_route=setup-readiness`；仅发现旧路径资产仍进入 migration-check 并暂停写入。`ready` 直接继续，`conflict` 进入迁移裁决，`degraded` 保留待发布草案，`not-applicable` 仅验证模板契约。通用 setup 文案与 YSS tracker 合同冲突时，以 `docs/agents/issue-tracker.md` 和本编排契约为准。
+
 ### Local Markdown 兼容映射
 
 当 `docs/agents/issue-tracker.md` 的 `platform` 为 `local-markdown` 时，Matt flow 的本地输出归一化为以下 YSS 载体：

package/template/.claude/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -35,8 +35,18 @@ entry_routing:
   invalid_manifest:
     action: migration-check
   direct_matt_entry:
+    skill: ask-matt
     delegate_to: yss-product-lifecycle
     requires_valid_manifest: true
+    action: navigate-only
+    lifecycle_state_mutation: forbidden
+    lifecycle_artifact_write: forbidden
+    return_to_orchestrator: required
+  formal_user_entry:
+    skills: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+    action: lifecycle-validate-and-accept
+    lifecycle_artifact_write: conditional-explicit-user-entry
+    return_to_orchestrator: required
   template_source:
     route: template-maintenance
     forbidden_artifacts: [product-spec, prototype, openapi, vertical-slice-tickets]
@@ -44,8 +54,11 @@ entry_routing:
     on_forbidden_flow: blocked
     block_reason: template-source-product-artifact-forbidden
 
-# Matt skill 的自然语言输出必须先归一化，再由生命周期编排器决定是否推进。
+# 旧 Matt Skill Result 只用于兼容读取；所有生命周期新输出使用 Workflow Execution Result。
 matt_skill_result:
+  status: compatibility-read-only
+  may_influence_routing: false
+  normalize_to: workflow-execution-result-v1
   schema_version: 1
   result_values: [completed, blocked, needs-human, failed]
   required: [result, skill, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
@@ -60,6 +73,59 @@ matt_skill_result:
     blocked: blocked
     ready-for-lifecycle-review: needs-human
 
+workflow_execution_result:
+  canonical_output_schema: workflow-execution-result-v1
+  accepted_input_schemas: [workflow-execution-result-v1]
+  legacy:
+    matt-skill-result-v1:
+      status: compatibility-read-only
+      may_influence_routing: false
+      normalize_to: workflow-execution-result-v1
+      removal_target: schema_version_2
+  result_values: [completed, blocked, needs-human, failed]
+  required: [result_schema, work_unit, workflow_reference, result, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
+  completed_requires_empty: [new_impacts, stale_candidates]
+  completed_requires_non_empty: [evidence_refs]
+  completed_requires_readable_evidence_refs: true
+  evidence_ref_validation: readable-or-resolvable
+  completed_requires_no_blocking_signals: true
+  workflow_reference:
+    required: [source, skill, invocation_mode]
+    source: mattpocock/skills
+
+# Matt user-invoked skills remain explicit user entry points. Lifecycle work units
+# may prepare, validate and accept their results, but cannot invoke them or create
+# their formal artifacts on their behalf.
+matt_invocation_boundary:
+  user_invoked_skills: [ask-matt, batch-grill-me, grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, loop-me, setup-matt-pocock-skills, setup-ts-deep-modules, teach, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder, writing-beats, writing-fragments, writing-shape]
+  lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+  model_invoked_skills: [grilling, domain-modeling, code-review]
+  lifecycle_may_invoke_user_invoked: false
+  formal_artifact_owner: explicit-user-entry
+  continuous_orchestration: prepare-and-validate-only
+  direct_user_entry: lifecycle-validate-and-accept
+
+lifecycle_workflow_references:
+  work-unit.discovery-interview:
+    invocation_mode: model-invoked
+    skills: [grilling, domain-modeling]
+  work-unit.spec-synthesis:
+    workflow_reference: to-spec
+    invocation_mode: reference
+    formal_artifact_owner: explicit-user-entry
+  work-unit.ticket-decomposition:
+    workflow_reference: to-tickets
+    invocation_mode: reference
+    formal_artifact_owner: explicit-user-entry
+  work-unit.slice-implementation:
+    workflow_reference: implement
+    invocation_mode: reference
+    formal_artifact_owner: explicit-user-entry
+  work-unit.code-review:
+    invocation_mode: model-invoked
+    skill: code-review
+
 flow_preconditions:
   to-spec:
     required: [grill_exit, no_unresolved_runnable_blocker]
@@ -73,6 +139,15 @@ flow_preconditions:
     required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied]
     applies_to_single_session: true
 
+grill_exit:
+  required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
+  facts_resolved_or_routed:
+    technical_fact: research
+    runnable_question: handoff-prototype-handoff
+    external_decision: external-input-required
+  user_confirmation_required: true
+  output: discovery-evidence
+
 ticket_role_transition:
   yss_active:
     to_tickets_initial_role: ready-for-human
@@ -131,6 +206,7 @@ review_input:
     completion_requires_current_digest: true
 
 git_authorization:
+  natural_language_intent_is_authorization: false
   commit:
     requires_explicit_user_authorization: true
     required: [commit_authorized, commit_scope, commit_authorization_ref]
@@ -230,6 +306,15 @@ tracker:
 setup_readiness:
   evaluation: once_per_task
   recheck_when: [tracker_changed, remote_changed, labels_changed, configuration_changed]
+  missing_action: needs-human
+  requested_skill: setup-matt-pocock-skills
+  resume_route: setup-readiness
+  preserves: [lifecycle.status, gate.status, ticket.role]
+  lifecycle_may_invoke_setup: false
+  legacy_artifacts_detected:
+    action: migration-check
+    setup: forbidden
+    write: paused
   states: [ready, missing, conflict, degraded, not-applicable]
   evidence: [platform, label_check, domain_layout, artifact_root, migration_ref]
   semantics:
@@ -366,5 +451,5 @@ prototype_modes:
 
 behavioral_invariants:
   wait_what_preserves_state: true
-  wizard_human_only: true
+  human_checkpoint_required_for_manual_steps: true
   diagnostics_redact_secrets: true

package/template/.claude/skills/yss-product-lifecycle/references/orchestration.md

@@ -6,7 +6,7 @@
 2. `setup readiness`：每个任务只执行一次，核对 tracker、五态标签和领域文档布局，并在本轮缓存结果；仅在 tracker、主远端、真实标签或配置变化时重查。
 3. 加载父 Ticket/checkpoint 与真实资产，计算最近可信阶段。
 4. 评估资产、门禁和 `stale`，选择第一个未阻塞工作单元。
-5. 调用一个最小 Matt/YSS 专项 skill，将结果归一化为 `Matt Skill Result`，验收输出并回写状态与证据。
+5. 执行最小生命周期工作单元：只实际调用允许的 model-invoked skill；Matt user-invoked skill 仅作为 workflow reference。将结果归一化为 `Workflow Execution Result`，验收输出并回写状态与证据。
 6. 若仍在授权和自动推进边界内，回到第 3 步；否则暂停。
 
 不要仅输出下一个提示词后结束 `orchestrate`/`resume`。不要因进入业务代码阶段而退出主控；应把实现交给专项 skill，并在返回后继续核验。
@@ -40,7 +40,7 @@ Readiness 结果在同一任务内复用。只有 tracker、主远端、真实
 | 状态 | 判定 | 动作 |
 |---|---|---|
 | `ready` | tracker、Local `Status:` 或远程标签和领域布局兼容 | 继续 |
-| `missing` | 必要配置缺失 | 路由 `setup-matt-pocock-skills` |
+| `missing` | 必要配置缺失 | `needs-human`；说明缺失项并请用户显式运行 `setup-matt-pocock-skills`，随后回到 readiness |
 | `conflict` | 多个持久配置或真实标签/Local 状态互相矛盾 | 暂停并提出迁移方案，不覆盖 |
 | `degraded` | 已选择的 GitHub/GitLab 不可用 | 建 `docs/.scratch/<feature>/` 待发布草案，不改投平台 |
 | `not-applicable` | `template-source` | 只验证模板契约 |
@@ -51,11 +51,11 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 ## Matt flow 进入条件
 
-- `to-spec` 只能在 `grill-with-docs` 退出条件满足且没有未回流 runnable blocker 时进入；产物默认为 `ready-for-human`。
-- `to-tickets` 只能在 OpenAPI Freeze 或无 API 影响记录完成后进入，并且只能生成垂直切片 Ticket；YSS active 下初始角色统一为 `ready-for-human`，不得沿用 Matt 的通用 `ready-for-agent` 默认值。
-- `implement` 无论是多会话还是单会话，都必须满足 `ready-for-agent` 公式、批准并持久化的 Slice Implementation Contract 和 Build Architecture Checklist。
+- `work-unit.discovery-interview` 实际调用 `grilling` 和 `domain-modeling`。`to-spec` 只能由用户显式启动；生命周期仅在其前准备并验收，正式 Spec 默认为 `ready-for-human`。
+- `to-tickets` 只能由用户显式启动；生命周期仅在 OpenAPI Freeze 或无 API 影响记录后准备和验收垂直切片，初始角色统一为 `ready-for-human`。
+- `implement` 只能由用户显式启动；无论多会话还是单会话，生命周期都在其前后核验 `ready-for-agent` 公式、批准并持久化的 Slice Implementation Contract 和 Build Architecture Checklist。
 - `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 合同重编译均已回写；否则停在工程基线，不得写业务代码。
-- Matt Result 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元。
+- `Workflow Execution Result` 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元；旧结果只能先经只读兼容 adapter 归一化。
 
 ## 审查与验证
 

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

@@ -50,7 +50,7 @@ AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路
 
 父 Ticket、Spec、设计、原型、OpenAPI Draft、wayfinder map 和 decision ticket 不得使用 `ready-for-agent`。
 
-YSS active 调用 `to-tickets` 时，垂直切片初始角色固定为 `ready-for-human`。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；Matt `to-tickets` 的独立默认值不参与该裁决。
+用户显式运行 `to-tickets` 后，垂直切片初始角色固定为 `ready-for-human`。只有 `yss-product-lifecycle` 复算上述公式全部为真后，才能把它提升为 `ready-for-agent`；生命周期不会自动调用 `to-tickets`，其默认标签也不参与该裁决。
 
 ## Review 与 Git 授权状态
 

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

@@ -11,7 +11,7 @@ description: Use when a YSS feature has product-design impact on a primary flow,
 
 - 先由 `yss-product-lifecycle` 判断产品设计影响；无行为变化的孤立视觉修复记录 `not-applicable`，不创建空资产。
 - Codex 的产出主入口是 `product-design:index`；其他 Agent 使用等价的产品设计能力，但必须产出本技能规定的相同资产和证据。能力或证据不能等价时，暂停并回到人工确认。
-- 旧 `product-design-prototype`、`wireframe-prototype`、`high-fidelity-html-prototype` 仅为兼容入口；从它们进入时立即回到本合同。
+- `product-design-prototype`、`high-fidelity-html-prototype` 仅为兼容入口；从它们进入时立即回到本合同。已退休的原型技能不得继续路由。
 
 ## 资产与门禁顺序
 

package/template/.codex/skills/ask-matt/SKILL.md

@@ -80,7 +80,6 @@ Off the main flow entirely.
 - **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
 - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
 - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
-- **`/wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
 - **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
 - **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.

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

@@ -10,7 +10,7 @@ Two-axis review of a pinned candidate against a fixed point:
 
 Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
 
-The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## Process
 

package/template/.codex/skills/grill-me/SKILL.md

@@ -4,4 +4,4 @@ description: A relentless interview to sharpen a plan or design.
 disable-model-invocation: true
 ---
 
-Run a `/grilling` session.
+Call the Skill tool with `grilling`.

package/template/.codex/skills/grill-with-docs/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: grill-with-docs
 description: Use when the user explicitly requests a relentless design interview that must preserve resolved glossary terms, ADR-worthy decisions, and factual research evidence.
+disable-model-invocation: true
 ---
 
-Run a `grilling` session with `domain-modeling` active.
+Call the Skill tool with `grilling`, then call it separately with `domain-modeling`.
 
 ## Output Contract
 

package/template/.codex/skills/maintaining-skills/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: maintaining-skills
+description: Use when creating, modifying, validating, or retiring reusable Agent skills.
+---
+
+# Maintaining Skills
+
+Create skills that add useful, non-obvious guidance without constraining unrelated work.
+
+## Working Contract
+
+1. Inspect the skill's callers, ownership, projections, and validation policy before editing. Preserve user intent, authorization boundaries, supported runtimes, and existing metadata unless the requested change requires otherwise.
+2. Assume the Agent already has general reasoning and tool competence. Record only domain knowledge, decision criteria, fragile invariants, or repeatable operations that materially improve outcomes. Do not turn one example or past failure into a universal rule.
+3. Keep discovery precise: use a lowercase hyphenated name and a concise description that states the capability and when it applies. Avoid catchalls that attract unrelated requests.
+4. Keep `SKILL.md` as short as the task permits. Put conditional detail in `references/`, deterministic repeated operations in `scripts/`, and files intended for generated output in `assets/`. Create only resources with a concrete use.
+5. Match specificity and validation to risk. Prefer outcome and decision criteria when several approaches are valid; use fixed steps or absolute rules only for correctness, safety, permissions, or genuinely fragile workflows.
+6. Follow the repository's declared maintenance and review policy. If none exists, run structural validation plus focused checks of the behavior or invariant changed. Use independent forward testing only when complexity or risk makes it meaningful; do not require a failing baseline for every ordinary edit.
+7. After changes, validate frontmatter, naming, references, scripts, projections, locks, and affected callers. Retire obsolete names and resources unless the repository explicitly requires compatibility.
+
+## Boundaries
+
+- Project rules belong in the project's authoritative instructions, not duplicated inside a generic skill.
+- Platform-private skills or absolute local paths are not portable shared dependencies.
+- A validation command proves only what it checks; structural validation alone does not prove good Agent decisions.
+- Do not create README files, changelogs, examples, routers, or placeholder directories without a concrete requirement.

package/template/.codex/skills/product-design-prototype/SKILL.md

@@ -36,7 +36,7 @@ If no Spec baseline exists, route back to `yss-product-lifecycle` / `grill-with-
 
 | Need | Add skill/tool |
 |---|---|
-| Low-fidelity page or flow sketch | `wireframe-prototype` |
+| Low-fidelity page or flow sketch | `product-design:index` |
 | Figma work or existing Figma file | `figma` / `figma-use` |
 | YSS implementation constraints | `yss-router`, then `yss-ui`, `yss-formily`, `yss-page-module-development` as needed |
 

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+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
 

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

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
 
-The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+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
 

package/template/.codex/skills/yss-components/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "yss-components"
-description: Use when YSS UI 组件开发规范与最佳实践。涉及页面布局、YTable、YssFormily、YTree、Header 区块、空态与弹窗等页面搭建场景时必须使用。
+description: Use when YSS Vue 页面涉及布局、YTable、YEditTable、YFormily、YTree、ConditionBuilder、空态、弹窗或业务组件选型。
 ---
 
 # YSS 页面组件开发标准
@@ -9,11 +9,32 @@ description: Use when YSS UI 组件开发规范与最佳实践。涉及页面布
 
 ## 0. 权威资料与边界
 
-- YSS UI 组件文档：`http://192.168.164.27:3200/components`
+- YSS UI 组件文档：`http://192.168.164.27:3200/components`（组件契约以该手册为准；本技能依据 2026-08-18 可见内容整理）
 - 本地引用索引：`references/frontend-docs.md`
 
 本技能只负责页面组件、布局和交互呈现规范。请求、分页参数、接口映射交给 `yss-hook` 或 `api-integration`；完整页面生成流程交给 `yss-page-module-development`；表格/树高度细节交给 `yss-use-table-height` 或 `yss-use-tree-height`。
 
+组件文档与当前项目的已验证用法冲突时，先检查当前项目代码和依赖版本，再决定是否迁移；不得把上游 Ant Design Vue、vxe-table、Univer 或 Monaco 的未验证 API 当作 YSS 顶层契约。
+
+## 0.1 组件选型速查
+
+| 场景 | 首选组件 | 关键边界 |
+| --- | --- | --- |
+| 常规动作、权限控制、操作下拉 | `YButton`、`AuthorityDropdown` | 用 `permissionCode` + `fallback` 控制隐藏/禁用；按需导入下拉必须使用 `AuthorityDropdown`，不使用仅全量注册的 `YDropdown` 别名。 |
+| 信息分组、统计卡片 | `YCard` | 组件不处理卡片布局；使用 CSS Grid/Flex 排版，`padding` 与 `bodyStyle.padding` 同时提供时以后者为准。 |
+| 左树右表、上下内容区 | `YSplitPane` | 轻内容使用默认实时拖拽；树、宽表、编辑器、图表等重内容使用 `resize-mode="deferred"` + `collapse-animation="transform"`。 |
+| 树、目录、资源导航 | `YTree` | 受控选择使用 `v-model:selected-keys`；大量节点必须给 `height`，再按需设置 `virtual`，不能只靠 CSS 高度。 |
+| 查询、编辑、详情表单 | `YFormily` | 新代码使用公开导出 `YFormily`；`YssFormily` 仅为历史兼容名。查询动作、展开状态和跨字段联动都以 schema / `scope` / `x-reactions` 表达。 |
+| 常规展示、选择、分页、筛选、操作列 | `YTable` | 远程分页和远程筛选由 Hook 管理；多选必须声明业务 `row-config.keyField`，不能依赖内部 `_X_ROW_KEY`。 |
+| 行内编辑、单元格校验、拖拽排序 | `YEditTable` | 只在确有编辑闭环时使用；保存前调用 `validate()`，以 `v-model:data` 与公开 `updateRow` 事件接回受控数据。 |
+| 嵌套 AND/OR、字段-操作符-值联动 | `YConditionBuilder` | 保存和请求映射在 Hook；组件只维护 `ConditionGroup`。复杂筛选不是把字段硬编码回普通 `YFormily` 模板。 |
+| 月视图、排班、日程状态 | `YMonthCalendar` | 是单日期选择与展示月份的独立状态，不是日期范围输入器；范围查询继续在 `YFormily` 的日期字段完成。 |
+| SQL / JSON / 配置编辑、日志阅读 | `YMonaco` / `YMonacoDiff` | 容器变更后必要时调用 `layout()`；日志追加使用 `appendContent()`，不反复 `setValue()`。 |
+| Cron 配置 | `YCron` | 输出为七段 `秒 分 时 天 月 周 年`；只使用其 `v-model`、`disabled`、`show-second`、`show-year` 公开契约。 |
+| 类 Excel 协作编辑 | `YSheet` | 必须给明确高度；只通过 Facade API 更新工作簿，卸载后释放实例；评估 Univer/React/RxJS 的包体影响。 |
+| 两步文件导入与失败结果下载 | `YFileImport` | 默认阻止 Upload 自动上传；在 `nextStep` / `finalImport` 事件中由业务实现校验、上传和结果回显。 |
+| 图表 | `YssEcharts` | 先阅读当前版本组件页面与项目现有图表实践，再确定 option、数据更新和容器尺寸方案。 |
+
 ## 1. 触发场景
 
 当需求涉及以下任一内容时，优先按本技能执行：
@@ -21,7 +42,7 @@ description: Use when YSS UI 组件开发规范与最佳实践。涉及页面布
 - 新建页面或重构页面结构
 - 左树右表、左右分栏、主从布局
 - YTable 列渲染、分页、空态
-- YssFormily 查询区与 schema 配置
+- YFormily（或历史代码中的 YssFormily）查询区与 schema 配置
 - 页面级弹窗、详情抽屉、Header 信息区
 
 ## 2. 页面目录规范
@@ -49,9 +70,9 @@ views/PageName/
 - `index.vue` 仅编排页面，不承载复杂数据转换
 - `components/` 放展示型或区块型组件
 - `hooks/` 放页面业务逻辑 Hook
-- `schemas/` 放 YssFormily 元数据定义
+- `schemas/` 放 YFormily 元数据定义
 
-## 3. 页面骨架规范
+## 3. 页面骨架规范（YSplitPane + YTree）
 
 页面容器使用 `YSplitPane`，并提供宽度边界与 `storage-key`。
 
@@ -81,13 +102,17 @@ views/PageName/
 - 左侧区域承载目录、筛选树、统计导航
 - 右侧区域按顺序组织 Header、查询区、数据区
 - 右侧无选中对象时必须提供明确空态
+- 尺寸需要受控时使用 `v-model:left-width`（纵向使用 `v-model:top-height`）；`storage-key` 仅保存用户尺寸，不替代页面状态。
+- 左树使用业务主键配置 `field-names`，选中状态使用 `v-model:selected-keys`。树数据量大时传入明确 `height`，必要时启用虚拟滚动；搜索区通过 `#search`、`#header-left`、`#header-right` 扩展，不复制内置搜索逻辑。
+- 节点“更多”操作使用 `get-node-actions` 和 `@action`；默认点击更多会选中该节点，若不应改变主内容选择，显式设置 `:select-on-action-click="false"`。
+- 折叠树时默认保留内容状态（`destroy-on-collapse=false`）。只有确需释放重 DOM、且允许丢失树展开/勾选/滚动状态时才设为 `true`。
 
-## 4. 查询区规范（YssFormily）
+## 4. 查询区规范（YFormily）
 
 查询表单必须采用 schema 驱动，页面中只负责绑定 `schema`、`scope`、初始值与插槽。
 
 ```vue
-<YssFormily
+<YFormily
   ref="formRef"
   :schema="searchSchema"
   :model-value="initialValues"
@@ -99,7 +124,7 @@ views/PageName/
       <a-input v-model:value="searchVal" />
     </a-input-group>
   </template>
-</YssFormily>
+</YFormily>
 ```
 
 schema 约束：
@@ -107,6 +132,10 @@ schema 约束：
 - 使用 `FormLayout + FormGrid + FormItem` 组织字段
 - 按钮区使用 `AutoButtonGroup + Submit`
 - 行为通过 `onSubmit: '{{ handleQuery }}'` 等 scope 方法绑定
+- 新页面统一使用 `YFormily`；`YssFormily` 不作为新代码的组件名或类型来源。
+- 查询表单需要折叠时启用 `collapsible`，并用 `v-model:expanded` 管理外部状态。使用 `#actions` 自定义操作区后，组件会把折叠入口置于其左侧；不要再手写第二套展开逻辑。
+- 字段显隐、禁用、数据源联动使用 `x-reactions`；单字段输入优先监听底层组件的 `onUpdate:value`，选择/失焦事件以 Ant Design Vue 对应事件为准。复杂异步、副作用和跨页面可复用逻辑下沉到 Hook。
+- 详情页使用 `mode="2"`，字段插槽固定为 `#detail-<path>`（路径中的 `.` 替换为 `-`）；不要为只读页另建一套模板。
 
 ## 5. 数据区规范（YTable）
 
@@ -133,6 +162,22 @@ schema 约束：
 - 先固定序号列，再拼接动态列
 - 列字段名与接口字段保持一致
 - 长文本列优先 `showOverflow` 或省略显示
+- 按业务主键设置 `:row-config="{ keyField: 'id', useKey: true }"`；涉及刷新、树表、勾选或批量操作时这是必需项。
+- 分页数据来自服务端时在 `pagination` 中明确 `remote: true`，由 Hook 响应 `page-change` / `size-change` 后刷新数据和 `total`；不得让组件在远程数据上再次切片。
+- 远程列筛选监听 `filter-change`，列上提供稳定的 `filters`，并设置 `filterMethod: () => true` 禁用 vxe-table 本地过滤；本地筛选才编写真实 `filterMethod`。
+- 多选首列为 `type: 'checkbox'`，用 `v-model:selected-row-keys` 或 `v-model:selected-rows` 受控。批量动作放在 `#toolbar-right`，成功后重置选中键或调用 `clearSelection()`。
+- 插槽统一使用 kebab-case：`#<field>-header`、`#<field>-filter`、`#expand-row`、`#group-header`、`#toolbar-left`、`#toolbar-right`。不要把 camelCase 旧兼容写法用于新模板。
+- 最后一列宽度必须精确控制时设置 `:auto-flex-column="false"`；默认自动填满余宽。数据量达到组件阈值时让默认 `virtualXConfig` / `virtualYConfig` 生效，避免手动拼接分页假象。
+
+### 5.1 可编辑表格的升级条件
+
+只有同时满足“用户需要在行内编辑”和“编辑前校验、保存或取消回退”时，从 `YTable` 升级到 `YEditTable`：
+
+- 列通过 `component`（可为纯函数）声明编辑器；按行差异由 `cellProps(ctx)` 决定，函数不得有副作用。
+- 必填和自定义校验通过 `editRules` / `customRule` 声明，提交前调用 `tableRef.value.validate()`；校验失败不得发起保存请求。
+- 以 `v-model:data` 接收完整数据，或在 Vue 模板监听公开 `updateRow` 事件的 kebab-case 写法 `@update-row` 接收单元格变更；保存失败由业务层回退受控数据或保持编辑态，不能假定组件自动持久化。
+- 行级候选项优先级为“行对象 `rowOptionsFieldName`（默认 `options`）→ 列 `options` → `optionsMap[field]`”。字段联动、异步候选和清空关联值必须落在 Hook 的单一数据流中。
+- 编辑表的表头筛选仍是 `filterable + filters + filterMethod`；编辑态 `filterOptions` 只过滤该行下拉候选，二者不可混用。
 
 ## 6. 交互状态规范
 
@@ -143,6 +188,36 @@ schema 约束：
 - `selected`：依赖选中节点时，未选中显示引导空态
 - `error`：请求失败提示 `message.error`
 
+### 6.1 复杂条件、日历和导入的状态契约
+
+#### `YConditionBuilder`
+
+- 用于可嵌套的 AND/OR 条件树，根值必须是 `ConditionGroup`：`{ id, type: 'GROUP', logicalOp: 'AND' | 'OR', children }`；叶子是 `{ id, type: 'LEAF', field, operator, value, betweenValue1?, betweenValue2? }`。
+- 静态操作符使用 `operator-options`；字段切换需改变操作符或值候选时使用 `get-operators(field)` 与 `load-values({ q, field, operator })`。远程字段搜索使用 `load-fields(q)`。
+- 默认严格校验；提交前调用 `ref.validate()`。只有明确允许未完成草稿时才能关闭 `strict-mode`。
+- 嵌套深度由 `max-depth` 限制（默认 3）。条件树到接口筛选 DSL 的序列化、恢复与错误兜底必须放在 `hooks/useXxx.ts`，保留组件内的标准模型。
+- `readonly` 已废弃且不生效；展示态统一传 `disabled`。
+
+#### `YMonthCalendar`
+
+- `v-model` 管理一个选中 `Dayjs`，`v-model:month` 管理展示月份；两者不要混为一个日期范围字段。
+- `valid-range` 限制可选范围，`disabled-date` 处理业务禁用日期。`validRange` 起止传反时组件会自动交换，但业务仍应在 Hook 中规范化输入。
+- 需要连续假期/日程视觉时使用 `cell-layout="grid"` 和 `#date-cell` / `#date-cell-extra`；自定义单元格必须根据 `isToday`、`isSelected`、`isDisabled` 等上下文自行保留状态语义。
+- 父容器高度确定且需要填满时才使用 `fill-height`；它要求父容器有明确高度。键盘、右键或双击动作接入 `select`、`cell-contextmenu`、`cell-dblclick`，不覆盖组件默认焦点行为。
+
+#### `YFileImport`
+
+- 以 `v-model` 管理弹窗显示；选择文件、`nextStep` 校验/预检、结果回显、`finalImport` 确认构成两步流程。事件会提供 `fileList`、`loadingName` 和 `close`。
+- 默认 `beforeUpload` 始终返回 `false`，因此不能期待 `action` 自动上传。需要直传时只在 `upload-props.customRequest` 实现，文件类型规则由 `accept` 或 `file-type-list` 统一配置。
+- `importResult` 用于展示成功、失败和总数；失败文件下载用 `exportErrorData` 事件。遮罩、居中等弹窗配置只放 `modal-props`，上传器配置只放 `upload-props`。
+
+### 6.2 编辑器、Cron、Sheet 与图表
+
+- `YMonaco` 默认 `auto-layout`；在分栏折叠、抽屉打开等容器尺寸变化后确认编辑器已布局。只读日志使用 `language="log"` 或 `"yss-log"`，并用 `appendContent()` 追加；超大内容避免频繁重设完整字符串。
+- `YCron` 的业务值就是七段表达式。页面仅负责双向绑定和禁用态；Cron 到后端调度模型的转换、时区和生效校验属于接口/Hook 层。
+- `YSheet` 的 `modelValue` 是工作簿数据；初始化后经 `getUniverAPI()` / `getWorkbook()` 的 Facade 修改并用 `save()` 取值，禁止直接改 `IWorkbookData`。必须设置容器高度；使用前确认 optionalDependencies 已被私服安装成功。
+- `YssEcharts` 的 option、数据更新策略和容器尺寸以当前版本手册与项目既有实践为准；不得把原生 ECharts 初始化、实例销毁和 ResizeObserver 再复制进页面层。
+
 ## 7. 组件编码规范
 
 - 使用 `<script setup lang="ts">`
@@ -220,7 +295,7 @@ schema 约束：
 满足任一条件即可触发本技能：
 
 - 用户提到“页面搭建、页面重构、页面区块拆分”
-- 用户提到“YTable、YssFormily、YTree、YSplitPane”
+- 用户提到“YTable、YEditTable、YFormily、YTree、YSplitPane、ConditionBuilder”
 - 用户提到“左树右表、查询区、表格区、空态、详情弹窗”
 - 用户要求“参考 QualityReportData 做一个新页面”
 
@@ -234,7 +309,7 @@ schema 约束：
 应触发示例：
 
 - “帮我按 QualityReportData 的结构搭一个新页面，左侧树右侧表格。”
-- “把这个页面查询区改成 YssFormily schema 驱动。”
+- “把这个页面查询区改成 YFormily schema 驱动。”
 - “YTable 需要加分页和空态，顺便补一个详情弹窗。”
 
 不应优先触发示例：

package/template/.codex/skills/yss-design-system/SKILL.md

@@ -80,7 +80,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
 | 低保真评审通过后的高保真 HTML 原型 | `yss-prototype-stage`；`high-fidelity-html-prototype` 仅兼容入口 |
-| 低保真线框或流程图 | `product-design:index` 或 `wireframe-prototype` 兼容入口 |
+| 低保真线框或流程图 | `product-design:index` |
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |