npm - create-yss-spec - Versions diffs - 2.2.8 → 2.2.10 - Mend

create-yss-spec 2.2.8 → 2.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (642) hide show

package/template/docs/design/preview.html ADDED Viewed

@@ -0,0 +1,20 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>YSS Design System Preview</title>
+  <style>
+    :root { --primary:#3371ff; --primary-active:#245bdb; --text:rgba(0,0,0,.88); --secondary:rgba(0,0,0,.65); --layout:#f0f2f5; --surface:#fff; --subtle:#fafafa; --border:#d9d9d9; --selected:#e6f4ff; --success:#52c41a; --warning:#faad14; --error:#f5222d; font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif; }
+    * { box-sizing:border-box } body { margin:0; color:var(--text); background:var(--layout); font-size:14px; } .shell { max-width:1440px; margin:auto; padding:16px; } .toolbar { display:flex; gap:8px; flex-wrap:wrap; align-items:center; margin-bottom:12px; } h1,h2 { margin:0 0 12px; } h1 { font-size:24px; } h2 { font-size:18px; } .card { background:var(--surface); border:1px solid var(--border); border-radius:8px; padding:16px; margin-bottom:12px; } button,input,select { height:32px; border-radius:6px; border:1px solid var(--border); padding:0 12px; font:inherit; background:var(--surface); } button.primary { border-color:var(--primary); background:var(--primary); color:#000; font-weight:600; } button.primary:hover,button.primary:focus-visible { background:var(--primary-active); color:#fff; } button:disabled { background:#f0f0f0; color:rgba(0,0,0,.45); } input:focus-visible,select:focus-visible,button:focus-visible { outline:2px solid var(--primary); outline-offset:2px; } table { width:100%; border-collapse:collapse; } th,td { padding:8px 12px; border-bottom:1px solid var(--border); text-align:left; } th { background:var(--subtle); font-weight:600; } tr.selected { background:var(--selected); } .grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:12px; } .status { padding:8px 12px; border-radius:4px; margin:8px 0; } .success { background:var(--success); color:#000; } .warning { background:var(--warning); color:#000; } .error { background:var(--error); color:#000; } .muted { color:var(--secondary); } @media (max-width:768px) { .shell { padding:12px; } .grid { grid-template-columns:1fr; } .toolbar > * { flex:1 1 140px; } table { min-width:620px; } .table-wrap { overflow-x:auto; } }
+  </style>
+</head>
+<body>
+  <main class="shell">
+    <div class="toolbar"><h1>YSS 设计系统预览</h1><span class="muted">默认 / 紧凑密度</span><button class="primary" onclick="this.textContent='已保存'; this.disabled=true">保存</button><button disabled>禁用</button></div>
+    <section class="card"><h2>筛选与表单</h2><div class="toolbar"><input aria-label="关键词" placeholder="关键词"><select aria-label="状态"><option>全部状态</option><option>已启用</option></select><button class="primary">查询</button><button>重置</button></div><div class="status warning" role="status">请补充必填筛选条件。</div></section>
+    <section class="card"><h2>数据表格</h2><div class="table-wrap"><table><thead><tr><th>名称</th><th>状态</th><th>更新时间</th><th>操作</th></tr></thead><tbody><tr class="selected"><td>示例任务</td><td><span class="status success">成功</span></td><td>2026-09-02 09:30</td><td><button>查看</button></td></tr><tr><td>加载中的任务</td><td>加载中…</td><td>—</td><td><button disabled>编辑</button></td></tr><tr><td>失败任务</td><td><span class="status error">失败：权限不足</span></td><td>—</td><td><button>重试</button></td></tr></tbody></table></div></section>
+    <div class="grid"><section class="card"><h2>空状态</h2><p class="muted">暂无数据，请调整筛选条件。</p><button class="primary">创建记录</button></section><section class="card"><h2>弹层触发</h2><button onclick="alert('Modal / Drawer 应提供可见反馈和焦点管理')">打开 Modal</button></section><section class="card"><h2>无障碍</h2><p class="muted">使用 Tab 检查焦点顺序；缩放到 200% 检查布局。</p></section></div>
+  </main>
+</body>
+</html>

package/template/docs/design/tokens/.design-md-projection.json ADDED Viewed

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "source": "DESIGN.md",
+  "source_sha256": "976d74b4af85b5062f9c5a365591809ff240159f0f4445ce05e7a4dcb76d0185",
+  "files": {
+    "docs/design/tokens/theme.json": "94010a32320bfe7135f75d87357609162e0358061fe8577d820dcb62f43ac4e4",
+    "docs/design/tokens/tokens.default.json": "bf89486a8730a68673473fa7d5afe40b158e833b10df7da75d505bc53f8f6167",
+    "docs/design/tokens/tokens.dark.json": "79b93203f305d26f2f230a8af1f4b7e77c9bdb7997efa0746eed1508c928f85b",
+    "docs/design/tokens/tokens.compact.json": "afa4ae457a3db81d4b8a4b103ed9d6baa897daa1bbc23c96ee7d9182d2b4b992",
+    "docs/design/tokens/variables.css": "d5bb7bdfe13d71214c44d1a0fdf9648cb5fa35cb6511fb2a35202f8a96fb39dd",
+    "docs/design/tokens/variables.dark.css": "b8ebb18f304831ee5c86cf6e5563702b2cc0ce2f51b055036e437a385226cd99"
+  }
+}

package/template/docs/discovery/reports/agent-governance-options.md ADDED Viewed

@@ -0,0 +1,71 @@
+# Agent Skill 治理升级决策分析
+## 结论摘要
+1. 逐技能结构 / 路由 / 行为 eval 不作为 YSS 模板首个升级方向。结构和路由已有确定性校验；行为 eval 成本高、易重复生命周期门禁，应降为后续按变更和风险触发的试验性能力。
+2. invocation metadata 进入 `yss-skill-registry.yaml`；Router 合同只定义字段 schema、解析和阻断规则，不复制每个 skill 的示例。trigger examples 进入注册表，但保持少量、结构化、只为消歧服务。
+3. freshness audit 作为生命周期完成条件的 core 能力，不新建一个常驻通用 skill；Doubt-Driven 作为高风险条件触发的 core 路由策略；Wayfinder 保持 maintainer-only / 兼容入口的可选模式，不进入默认 core 路由。
+## Q1：eval 是否为首个升级方向
+### 现状事实
+- 技能身份、层级、成熟度、别名、默认可发现性和来源投影已经由 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml)、[`skill-registry.mjs`](../../../scripts/lib/skill-registry.mjs)、`sync-skills` 和 `skills-lock.json` 共同校验。
+- 生命周期路由和 Router 已经对未登记技能、依赖闭包、原型独立评审、代码审查唯一入口等关键路由做确定性检查。
+- 生命周期完成已经要求 fresh verification、证据可读、阻断信号清空和 stale / drift 重路由。
+### 决策
+不把“每个 skill 三层 eval”作为 P0。采用以下顺序：
+| 层次 | 初始策略 | 原因 |
+|---|---|---|
+| 结构 | 继续使用现有静态 / schema 校验 | 成本最低，收益已覆盖大部分缺陷 |
+| 路由 | 只对注册表、Router、生命周期变更做确定性增量校验 | 与现有门禁直接对齐，避免重复运行 |
+| 行为 | P2 试验；只覆盖变更中的 core / 高风险 skill | 避免全量运行导致 token 和维护成本失控 |
+行为 eval 的进入条件应是：skill 内容或路由发生变化、命中高风险影响、或出现真实 finding；退出条件是连续真实任务证明它能发现现有静态校验抓不到的问题，且没有形成第二套生命周期门禁。
+## Q2：invocation metadata 与 trigger examples 的归属
+### 决策
+- **注册表**是技能级调用元数据的唯一事实源：调用模式、触发条件、排除条件、主要输出、依赖和少量 trigger examples 均放在这里。
+- **Router 合同**定义 schema、解析顺序、依赖闭包和阻断规则；不复制每个技能的完整示例，避免注册表与 Router 漂移。
+- **生命周期编排合同**继续保留工作单元级 `workflow_reference.invocation_mode`（例如 `model-invoked` / `reference`）。它描述一次工作单元如何被执行，不与注册表的 `user` / `model` / `both` 技能级模式混用。
+### trigger examples 约束
+- 仅为消歧提供 1–3 个正向示例，必要时提供反向排除示例。
+- 示例优先使用 `impact:<name>`、显式用户入口或工作单元 ID 等稳定标识；长篇自然语言放入 skill reference，不放在注册表核心字段。
+- specialist 技能可继承 `impacts` 触发条件；只有存在歧义时才增加显式 examples。
+- examples 只影响发现和路由提示，不直接批准门禁、Ticket 状态或 `ready-for-agent`。
+当前已落地的低成本基础见 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml) 的 `invocation_contract`，以及 [`router-contract.yaml`](../../.agents/skills/yss-router/references/router-contract.yaml) 的合同字段。
+## Q3：三项能力的路由层级
+| 能力 | 推荐层级 | 具体落点 | 不应做什么 |
+|---|---|---|---|
+| freshness audit | core 能力 | 生命周期完成条件、候选快照、fresh verification、stale / drift 检查 | 不再新增一个对所有任务常驻的通用审计 skill |
+| Doubt-Driven | core 条件路由 | Router / 工程基线 / 架构与契约审查中的高风险分支 | 不升级为所有低风险任务的默认步骤，不新建生命周期阶段 |
+| Wayfinder | maintainer-only / 兼容入口的可选模式 | 超长、多 Agent、多会话或 frontier 不清晰时，完成后回 `handoff → to-spec` | 不改变阶段、门禁、Ticket 角色或 `ready-for-agent` |
+### Doubt-Driven 的高风险触发器
+API schema、数据库 schema / 迁移、跨仓库契约、发布 / 回滚、实际改变的认证授权 / 租户 / 敏感数据行为，以及生命周期或生成语义。反证记录进入既有决策、架构、契约或发布审查记录；缺反证、证据不足或残余风险未处理时阻断。
+### freshness audit 的边界
+freshness 是“完成结论可信度”的 core 约束，而不是新的工作单元。模板维护继续使用 L1/L2/L3 checkpoint；产品切片继续使用 Slice Contract 和候选快照。这样可以复用同一条 finding 闭环，不增加每次调用的上下文负担。
+## 证据来源
+- [YSS skill registry](../../agents/yss-skill-registry.yaml)
+- [Skill registry validator](../../../scripts/lib/skill-registry.mjs)
+- [YSS Router contract](../../.agents/skills/yss-router/references/router-contract.yaml)
+- [Slice Implementation Contract](../../.agents/skills/yss-router/references/slice-implementation-contract.md)
+- [Lifecycle orchestration contract](../../.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml)
+- [Harness process tailoring](../../process/harness-process-tailoring.md)
+- [Addy Osmani agent-skills](https://github.com/addyosmani/agent-skills)
+- [Matt Pocock skills](https://github.com/mattpocock/skills)

package/template/docs/process/harness-process-tailoring.md CHANGED Viewed

@@ -46,6 +46,13 @@
 5. 模板正式发布仍执行一次完整 `scripts/verify-template`，但不因 L3 额外冻结候选或派发正式独立审查。
 6. 模板维护与产品切片使用同一 finding 闭环：`violation` / 机器检查失败 / 适用行空白由实施者修复后重新验证并按本表强度复审；`drift` / `new_impacts` 升级影响面并重新分级，禁止在旧合同或旧 checkpoint 上继续编码。审查者不得写实现。未命中的条件项才 `not-applicable`；命中后不得豁免。
+## 5. 上下文、反证与质量基线裁剪
+- Slice Contract 的 `common.context_plan` 是实现上下文的唯一轻量计划：先读 `CONTEXT.md`、已批准 Spec、当前合同和适用 ADR / 工程基线，再按影响面按需加载 references；达到最小充分证据后停止扩展。缺失权威上下文只能 `blocked` 或 `reroute`。
+- 质量标准在 `engineering-baseline` 中定义一次，以 `baseline_id` / `baseline_version` 被 Slice Contract、YSS Skill Execution Result、`code-review` 和发布检查复用；切片不得重定义同一标准。约束结果统一写入 `constraint_results`。
+- 只有命中高风险影响时才要求 Doubt-Driven 在途反证：API / 数据迁移、跨仓契约、发布回滚、实际改变的安全行为、生命周期或生成语义。反证写入现有决策 / 架构 / 契约 / 发布审查记录，不新增生命周期阶段；缺少反证、证据不足或残余风险未处理即阻断。
+- Wayfinder 是超长工作的可选规划模式，不改变阶段、门禁或 Ticket 状态；地图收敛后按 `wayfinder → handoff → to-spec` 返回主链。
 模板维护默认停在 `implementation-ready`，不自动冻结候选或派发审查。需要独立审查时显式提升到 `review-ready`；完成独立审查和最终完整门禁后才能成为 `release-ready`。三个核验入口由 `docs/process/template-verification-profiles.yaml` 统一定义：
 - `scripts/verify-template-fast`：按 Git 影响面运行快速检查；未映射路径或核心核验资产变化时 fail-safe 升级为完整门禁。

package/template/docs/process/lifecycle-registry-baseline.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "49ca553e83efb9cffae220d9e6fca434b1d27096126a640f8f8e172e048808df",
+  "semantic_sha256": "15375e8d7da599e2117e19399cb5e14b9c53aa4e4ce7c94c4e9c135a499e55e6",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",

package/template/docs/process/lifecycle-registry.yaml CHANGED Viewed

@@ -360,7 +360,7 @@ work_units:
   - id: work-unit.stage-decision
     name: 阶段决策包综合
     scope: project-instance
-    input: Discovery、DDD 战略设计、产品和商务输入。
+    input: Discovery、DDD 战略设计以及产品经理负责的商业约束输入。
     output: 带版本、digest、证据和下游映射的阶段决策包。
     completion: 必填字段、引用、影响面和下游消费验证通过；批准门禁完成。
   - id: work-unit.spec-synthesis

package/template/docs/process/template-verification-profiles.yaml CHANGED Viewed

@@ -32,12 +32,22 @@ core_escalation_patterns:
   - scripts/cache-template-commit
   - scripts/capture-maintenance-candidate
   - scripts/inspect-maintenance-candidate
+  - .template-source/tooling/node/scripts/design-md.mjs
 required_files:
   - yss-project.yaml
   - AGENTS.md
   - CONTEXT.md
   - skills-lock.json
+  - .agents/skills/.yss-skills-manifest.json
+  - .mcp.json
+  - .agents/mcp_config.json
+  - .cursor/mcp.json
+  - .gemini/settings.json
+  - .kiro/settings/mcp.json
+  - .vscode/mcp.json
   - docs/agents/yss-skill-registry.yaml
+  - docs/agents/yss-ui-skills-integration.md
+  - docs/user-guide/yss-ui-mcp.md
   - docs/agents/digital-human-roles.yaml
   - docs/process/lifecycle-registry.yaml
   - docs/process/lifecycle-registry-baseline.json
@@ -129,12 +139,16 @@ syntax_files:
   - scripts/verify-maintenance-review-workflow-scenarios
   - scripts/verify-template-cache-scenarios
 routing:
+  - patterns: [DESIGN.md, "docs/design/**", ".template-source/tooling/node/scripts/design-md.mjs"]
+    groups: [design-system]
   - patterns: [AGENTS.md, CONTEXT.md, yss-project.yaml, package.json, .gitignore, README.md, "docs/**"]
     groups: [hygiene]
   - patterns: [AGENTS.md, yss-project.yaml, "docs/process/template-engineering-overview.md"]
     groups: [governance-release]
   - patterns: [skills-lock.json, ".agents/skills/**", ".claude/skills/**", ".codex/skills/**", ".cursor/skills/**", ".hermes/skills/**", ".pi/skills/**", ".qoder/skills/**", ".trae/skills/**", "docs/agents/yss-skill-registry.yaml", "docs/agents/skills-maintenance.md", "scripts/*skill*"]
     groups: [skills]
+  - patterns: [.mcp.json, .agents/mcp_config.json, .cursor/mcp.json, .gemini/settings.json, .kiro/settings/mcp.json, .vscode/mcp.json, docs/user-guide/yss-ui-mcp.md, docs/agents/yss-ui-skills-integration.md]
+    groups: [skills]
   - patterns: ["docs/process/maintenance-*", "docs/process/harness-process-tailoring.md", "docs/process/schemas/maintenance-*", "scripts/*maintenance*", "scripts/lib/maintenance-*"]
     groups: [maintenance]
   - patterns: ["docs/process/lifecycle-*", "docs/process/templates/lifecycle-*", "scripts/*lifecycle*", "scripts/lib/lifecycle-*"]
@@ -156,6 +170,10 @@ routing:
   - patterns: ["scripts/**"]
     groups: [hygiene]
 groups:
+  design-system:
+    commands:
+      - { run: "node .template-source/tooling/node/scripts/design-md.mjs lint DESIGN.md", when: template-source }
+      - { run: "node .template-source/tooling/node/scripts/design-md.mjs drift", when: template-source }
   hygiene:
     commands: []
   tooling:

package/template/docs/templates/build-architecture-checklist-template.md CHANGED Viewed

@@ -46,6 +46,8 @@ owner: ai
 | 工程项目路径：每个 Harness 内项目必须有具体项目段，禁止直接写入容器根或单数 `app/...` | `docs/process/implementation-repo-integration.md` / implementation path validator |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 路径违规时停止 build，并回到实现路由 |
 | 文档语言：持久化生命周期文档、实施记录、审查报告、发布说明和 Git checkpoint 正文必须使用中文，英文 skill / 模板不得原样落地 | `AGENTS.md` / `yss-product-lifecycle` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 仅保留必要英文技术标识、命令和 metadata |
 | 高风险变更：按已批准的普通影响面结论记录验证证据、责任人和回滚约束 | `AGENTS.md` / Spec / 架构记录 |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺验证证据或责任人时不得发布或合并 |
+| 质量基线：`baseline_id` / `baseline_version` 只从 `engineering-baseline` 引用，Slice、Execution Result、审查和发布不得重复定义 | `engineering-baseline` / `orchestration-contract.yaml` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺少基线引用或出现重复标准时阻断并回到工程基线 |
+| Doubt-Driven：命中 API、数据、跨仓、发布回滚、实际安全行为或生命周期 / 生成语义时具备主张、反证、证据、残余风险和审查引用 | Router Contract / `orchestration-contract.yaml` |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  | 缺反证、证据不足或残余风险未处理时阻断 |
 |  |  |  | `implemented` / `seam-deferred` / `drift` / `violation` / `not-applicable` |  |  |
 状态说明：

package/template/docs/templates/implementation-routing-template.md CHANGED Viewed

@@ -40,7 +40,7 @@ owner: ai
 | Harness 内项目根路径符合 `apps/<backend|frontend>/<project>/` | 是 / 否 / 不适用 | `apps/backend/`、`apps/frontend/` 仅为容器 |
 | 未使用 `app/backend/`、`app/frontend/` 及其子路径 | 是 / 否 / 不适用 | 命中即阻断生成和实现 |
 | 原型确认后先完成后端脚手架，再进入业务代码路由 | 是 / 否 / 不适用 | `backend_scaffold_policy_satisfied` |
-| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据、验证命令 |
+| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | schema v2：`scaffold_request_id`、项目/输出目录、Router draft、生命周期批准、base package、Maven 坐标、target DDD/Profile、initialize-only、允许写路径、预期证据、验证命令 |
 | 后端构建 / 测试 / OpenAPI / CI 命令均使用项目根目录 `./mvnw ...`，或已记录受控例外 | 是 / 否 / 不适用 | 裸 `mvn ...` 默认为规范偏离 |
 | 持久化文档正文和章节标题已转换为中文，仅保留必要英文技术标识 / metadata | 是 / 否 | 英文 skill / 模板不得原样落地为交付文档 |
 | YSS skill 路由已完成 | 是 / 否 |  |
@@ -95,11 +95,34 @@ owner: ai
 | verification_commands |  |
 | human_review_points |  |
 | full_reroute_triggers | 新 API/schema、状态机、数据模型、写目录、仓库、skill、风险、seam、交付顺序或其他未冻结行为等变化 |
+| quality_baseline_ref | 工程基线的 `baseline_id` / `baseline_version`；切片不得重新定义质量标准 |
+| context_plan | 必需上下文、按需上下文、停止规则和缺失动作 |
+| doubt_driven_review | 高风险影响的主张、反证、证据、残余风险和审查引用；未命中时 `not-applicable` |
 | 不适用 skill | 原因 |
 |---|---|
 |  |  |
+### Context Plan（上下文工程）
+| 字段 | 内容 |
+|---|---|
+| required_context_refs | `CONTEXT.md`、已批准 Spec、当前 Slice Contract、适用 ADR / 工程基线 |
+| on_demand_context_refs | 命中影响面后再加载的专项 references、实现仓库文件和历史证据 |
+| context_stop_rule | `minimal-sufficient-evidence` |
+| missing_context_action | `blocked` / `reroute`；不得猜测补齐 |
+### Doubt-Driven 高风险反证
+| 字段 | 内容 |
+|---|---|
+| status | `not-applicable` / `required` / `completed` / `blocked` |
+| trigger_impacts | API、数据迁移、跨仓契约、发布回滚、实际安全行为、生命周期 / 生成语义 |
+| claim / counterclaim |  |  |
+| evidence_refs |  |
+| residual_risks |  |
+| reviewer_ref |  |
 ## 3. YSS skill 最小集合
 | 领域 | skill | 使用原因 | 是否必需 |
@@ -222,10 +245,12 @@ owner: ai
 | 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；Router 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
 | 生成器 | `yss-ddd-scaffold-generator` |
 | 模式 | `controlled-generation` |
+| Java / Maven 身份 | `base_package` 与 Maven `group_id` 分开登记；项目版本、父 POM GAV、`yss-components.version` 进入批准合同并原样传给 CLI |
 | 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper 和非业务机械模板 |
 | 禁止生成 | 业务规则、状态机、权限、事务、复杂查询、错误映射、业务字段和用户可见行为 |
-| 生成选项 | 关闭 `--with-example`；非空目录 `--force` 默认阻断，覆盖范围、备份、回滚点和批准引用齐全后才能单独审查 |
-| 验证 | 受控验证器实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；打印命令不算证据 |
+| 生成选项 | 关闭 `--with-example`；生成器严格 initialize-only，非空目录、`--force`、旧项目迁移和当前模板升级均为 `unsupported` |
+| Profile | `target-domain-model` / `mybatis-plus` / `mysql` / `spring-boot-2.7-jdk8` / `javax` / `web` / `yss-internal`；其他组合须先通过独立 fixture |
+| 验证 | 使用一键生成验证入口，实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`；通过后仅为 `empty-scaffold-verified`，golden first slice 通过后才是 `first-slice-verified` |
 | 后置 | `yss-backend-scaffold-parent`、`yss-router` 业务合同重编译、YSS Skill Execution Result |
 所有后续生成代码必须绑定当前批准且版本一致的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 Execution Result。业务行为必须使用 `behavior-tdd`；缺任一条件即阻断，不得以脚手架成功或时间压力豁免。

package/template/docs/templates/review-report-template.md CHANGED Viewed

@@ -87,8 +87,8 @@ rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .
 | 检查项 | 结论 | 证据 |
 |---|---|---|
-| `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YssFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
-| `yss-page-module-development` 页面骨架已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
+| `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
+| `yss-ui-business-page-generation` 页面生成与 `yss-page-module-development` 生命周期编排已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
 | 切片合同 `required_skills` 中的 Formily / 表格 / 树 / 高度 / 主题 / API 专项 skill 已按影响面引用规则；未命中项有 `not-applicable` 原因 | pass / violation / not-applicable |  |
 | 前端验证使用项目根 `pnpm ...`；实际退出码已记录。只做 type-check 或声称“已对齐”不算通过 | pass / violation / not-applicable |  |
 | 机器检查（`pnpm lint` / `pnpm type-check` 等已存在脚本）已执行，或缺失工具已写 `not-applicable` 及原因 | pass / violation / not-applicable |  |

package/template/docs/user-guide/yss-ui-mcp.md ADDED Viewed

@@ -0,0 +1,43 @@
+# YSS UI MCP 接入
+模板已为支持项目级 MCP 配置的客户端预置 `yss-ui` server：
+- Claude Code：`.mcp.json`
+- Antigravity：`.agents/mcp_config.json`
+- Cursor：`.cursor/mcp.json`
+- Gemini CLI：`.gemini/settings.json`
+- Kiro：`.kiro/settings/mcp.json`
+- VS Code：`.vscode/mcp.json`
+这些配置统一通过 `npx -y @yss-ui/mcp` 启动，不写用户主目录，也不覆盖个人全局配置。首次加载模板后，重启或刷新对应客户端即可发现 MCP。
+## Codex 等全局配置客户端
+需要写入用户级配置的客户端不由模板自动修改。以 Codex 为例，由使用者明确执行：
+```bash
+npx -y @yss-ui/mcp install codex
+```
+其他客户端的安装参数以 `@yss-ui/mcp` 当前 CLI 帮助为准。模板只提供说明，不替用户修改 `~/.codex/config.toml` 等全局文件。
+## 使用门禁
+生成或审查 YSS UI 页面时：
+1. 先调用 `get_codegen_rules` 获取当前代码生成约束。
+2. 不确定组件导出时调用 `list_components`。
+3. 配置组件、Hook 或 Utils 前调用 `get_component_docs`。
+4. 复杂场景调用 `get_demo`；无法确定归属时调用 `search_docs`。
+本次模板验证基线为 `@yss-ui/mcp@0.1.8`、YSS UI components `1.5.18`，MCP 对外提供 7 个工具。运行时返回值与项目 lockfile 仍优先于本文快照；MCP 不可用时，按 `AGENTS.md` 读取 `llms-full.txt`，并明确记录降级原因。
+## 快速自检
+客户端中至少确认以下结果：
+- `list_components` 能返回 YSS UI 组件清单。
+- `get_codegen_rules` 能返回当前生成规则。
+- 查询 `YTable` 时，`get_component_docs` 能返回对应文档。
+MCP 无法启动时，先确认 Node.js、`npx` 和网络/私有源访问，再直接运行 `npx -y @yss-ui/mcp` 查看启动错误；不要把 Registry 认证内容写入日志或提交到仓库。

package/template/docs/user-guide//346/210/230/346/234/257/350/256/276/350/256/241/345/255/220/351/241/271/347/233/256/347/224/250/346/210/267/346/211/213/345/206/214.md ADDED Viewed

@@ -0,0 +1,218 @@
+# 战术设计子项目用户手册
+第一次接触 Tactical Design，不需要先会写代码，也不需要背诵 DDD 术语。
+这本手册把已经确认的 Strategic Design Handoff，继续细化成研发团队可以实现、测试和评审的领域模型。全文使用虚构的“客户合同审批”作为例子；示例只用于学习，不要把示例名称直接写入真实项目。
+## 这本手册适合谁
+- 产品经理、业务专家：想知道业务规则在技术设计中如何被保护。
+- 架构师、开发者：需要把业务边界细化为聚合、状态和一致性规则。
+- 测试人员：需要找到可以独立验证的领域行为。
+- AI Agent 操作者：需要知道何时让 Agent 起草、何时要求人工确认、何时必须停下。
+不懂代码也可以读完“业务读者篇”；“研发接手篇”会出现少量工程术语，但每个术语都会先用白话解释。
+## 看完能做什么
+1. 说清 Strategic Design 和 Tactical Design 的分工。
+2. 判断轻量 `Tactical DDD Check` 是否足够，还是需要独立的 Tactical Design 产物。
+3. 把一个业务场景拆成聚合、Entity、Value Object、领域服务和领域事件。
+4. 说明不变量、一致性边界、Repository / Gateway 和 API 的隔离方式。
+5. 形成可评审、可测试、可交给实现团队的战术设计结果。
+## 先记住：它解决什么问题
+Strategic Design 解决“业务应该怎样分工和划边界”；Tactical Design 解决“在一个边界里面，具体由哪些对象协作，以及规则如何不被破坏”。
+| 工作 | 大白话 | 典型结果 |
+|---|---|---|
+| Strategic Design | 决定业务地图和上下文边界 | 子域、限界上下文、统一语言、Context Map |
+| Tactical Design | 决定一个上下文内部怎样组织规则 | 聚合、状态机、不变量、领域服务、领域事件 |
+| 工程实现 | 把设计变成可运行的软件 | OpenAPI、代码、数据映射、测试和发布 |
+本手册的终点是“战术设计已评审并可交给实现”；OpenAPI Freeze、代码和发布仍由下游研发流程负责。
+## 开始前：确认输入和仓库身份
+### 输入必须来自已确认的交接包
+开始前应能找到批准且版本当前的 `Strategic Design Handoff`，其中至少包括：
+- 已确认的业务术语和上下文边界；
+- 关键场景、业务不变量和领域事件候选；
+- Spec、原型或业务级 Ticket 的版本引用；
+- 交给 Tactical Design 裁决的问题，例如聚合边界、状态、一致性和持久化；
+- 未决问题、责任人和后续验证计划。
+如果交接包缺失、过期或与当前 Spec 不一致，先回到上游处理，不要凭经验补写模型。
+### 确认项目实例
+打开项目根目录的 `yss-project.yaml`：
+| 配置 | 含义 | 处理方式 |
+|---|---|---|
+| `repository_mode: project-instance` | 真实业务项目 | 可以记录真实战术设计 |
+| `repository_mode: template-source` | 模板源 | 只能维护通用模板，不能写具体产品模型 |
+| 文件缺失或值不合法 | 身份不清楚 | 先停止并做迁移检查 |
+在项目实例中，先让 Agent 只读分诊：
+```text
+使用 yss-product-lifecycle，以 route 模式检查“客户合同审批”的 Tactical Design 输入。
+请先读取 yss-project.yaml、CONTEXT.md、Strategic Design Handoff 和当前已有架构资料。
+本轮只读，不要修改文件。请用普通话告诉我：
+1. 上游交接包是否批准且仍然有效；
+2. 当前是轻量 Tactical DDD Check 还是需要独立 Tactical Design；
+3. 已确认、待确认和冲突的业务规则分别是什么；
+4. 下一步只做哪一件事。
+正式 ID 放在普通话解释后面。
+```
+## 业务读者篇：用白话理解核心概念
+### 1. 聚合（Aggregate）
+聚合是一组必须一起守规则的对象。聚合根是这组对象对外唯一的入口；外部不能绕过聚合根直接修改内部对象。
+例子：一次“客户合同审批”可以由 `Contract` 聚合根管理审批状态和审批记录。审批记录如果只能随合同一起新增、退回和查询，就可以放在这个聚合内；不相关的通知不要硬塞进来。
+判断一个对象是否属于同一聚合，可以问：
+- 这些数据是否必须在同一次事务中保持一致？
+- 修改其中一个对象时，是否必须立即检查另一个对象？
+- 聚合变得很大后，是否会造成锁、并发或性能问题？
+不要按数据库表的外键关系画聚合；表关系图和业务一致性边界不是一回事。
+### 2. Entity（实体）
+实体有自己的身份，即使其他属性变化，它仍然是“同一个东西”。例如合同有 `contractId`，合同名称或金额修改后仍是同一份合同。
+### 3. Value Object（值对象）
+值对象由它的值决定身份，没有单独的业务身份。例如合同金额、客户地址、审批意见或时间范围。两个值完全相同的金额可以互相替换；值对象通常应尽量不可变。
+### 4. 不变量（Invariant）
+不变量是无论哪条入口执行，都不能被破坏的规则。例如：
+- 合同资料完整且校验通过后才能提交审批；
+- 已通过审批的合同不能直接改回草稿；
+- 同一份合同不能同时存在两个正在处理的审批流程；
+- 每次审批都必须留下操作人、时间、动作和意见。
+每条不变量都要能对应至少一个测试场景。不要把“页面上有一个发布按钮”当成不变量。
+### 5. 状态机
+状态机把允许的状态变化写清楚。合同示例：`草稿 → 待审批 → 审批中 → 已通过`；审批人退回时回到“草稿”，但“已通过”不能直接回到“草稿”。
+| 当前状态 | 动作 | 下一状态 | 必须满足 |
+|---|---|---|---|
+| 草稿 | 提交审批 | 待审批 | 合同资料完整 |
+| 待审批 | 审批人接单 | 审批中 | 已分配审批人 |
+| 审批中 | 审批通过 | 已通过 | 规则检查通过 |
+| 审批中 | 退回 | 草稿 | 必须填写退回原因 |
+| 已通过 | 修改 | 不允许 | 创建新的合同草稿 |
+### 6. 领域服务（Domain Service）
+当一条业务规则不自然属于某个实体，或需要协调多个聚合时，可以使用领域服务。领域服务只表达业务决策，不负责 HTTP、数据库连接或页面跳转。
+### 7. 领域事件（Domain Event）
+领域事件记录“业务上已经发生了什么”，例如 `ContractApproved`。它适合通知订阅者、触发异步处理或留下审计线索；事件名称应使用业务语言，不要直接暴露数据库表名。
+## 研发接手篇：从场景形成战术设计
+### 第一步：从用户场景开始，不从类名开始
+以“提交客户合同审批”为例，先写出：谁发起、前置条件、动作、结果、失败方式和后续影响。
+```text
+角色：销售人员
+前置条件：合同资料完整，且当前没有正在处理的审批流程
+动作：提交合同审批
+成功：合同进入“待审批”，产生 ContractSubmitted 事件
+失败：保留原状态，返回可理解的失败原因
+```
+### 第二步：列出规则并划一致性边界
+把规则分成“必须立即成立”和“可以稍后完成”：
+| 规则 | 一致性要求 | 设计提示 |
+|---|---|---|
+| 提交前资料必须完整 | 立即成立 | 放在合同聚合的不变量中 |
+| 同一合同不能重复提交 | 立即成立 | 由聚合 + Repository 检查并发冲突 |
+| 审批结果通知销售 | 可稍后完成 | 审批完成后发送领域事件 |
+| 统计报表更新 | 可稍后完成 | 使用异步订阅，不阻塞审批事务 |
+跨聚合流程由 Application 编排；核心规则仍放在 Domain。不要把所有规则塞进 Controller 或 Application Service。
+### 第三步：画出对象职责，而不是字段清单
+至少记录以下内容：
+| 对象 | 类型 | 负责什么 | 不负责什么 |
+|---|---|---|---|
+| `Contract` | Aggregate Root / Entity | 状态变化、提交前检查 | 发送 HTTP、直接操作表 |
+| `ApprovalRecord` | Entity 或 Value Object（需裁决） | 表达审批动作、意见和时间 | 决定整个流程 |
+| `ApproveContract` | Domain Service（必要时） | 协调跨对象的审批规则 | 事务提交和接口适配 |
+| `ContractRepository` | Repository seam | 保存和加载聚合 | 对外暴露数据库结构 |
+| `ContractApproved` | Domain Event | 描述审批已通过 | 代替主事务中的规则检查 |
+“Value Object 还是 Entity”不是凭习惯决定的：如果版本需要独立追踪身份、生命周期或并发操作，可能是 Entity；如果它只是不可变的版本值，可能是 Value Object。把裁决理由写下来。
+### 第四步：隔离 Repository、Gateway 和 API
+- `Repository` 面向领域模型的保存 / 加载，不让领域层依赖 ORM 或表结构。
+- `Gateway` 面向外部系统能力，例如通知、文件存储或规则服务；领域层只依赖抽象接口。
+- API schema 面向调用方，不直接暴露聚合内部对象、Repository 或持久化表。
+- Application 负责用例编排、事务边界和跨聚合协调；Domain 负责核心业务规则。
+### 第五步：写测试 seam
+每条关键规则都要有可执行的验证入口：
+- 聚合行为测试：给定状态和动作，验证状态变化或拒绝原因；
+- Repository / Gateway 契约测试：验证抽象接口的输入输出；
+- Application 用例测试：验证事务边界和跨聚合协调；
+- API 契约测试：验证公开 wire shape，不验证内部类名。
+## 什么时候需要独立 Tactical Design
+大多数简单变更，在系统概要设计中的 `Tactical DDD Check` 写清楚即可。只有当以下内容复杂到无法在一节中审查时，才升级为独立 Tactical Design 产物：
+- 多个聚合之间有复杂的一致性或并发规则；
+- 状态机有分支、补偿、重试或不可逆状态；
+- 持久化映射会隐藏或破坏领域边界；
+- Gateway、领域事件或最终一致性需要明确时序；
+- 评审者无法仅凭概要设计复现关键业务行为。
+升级不是为了增加文档数量，而是为了让复杂决策可读、可测试、可追责。无论采用轻量检查还是独立文档，都必须引用同一份 `tactical-design` contract 和 `evidence.tactical-design-review`，不能产生两套互相矛盾的事实源。
+## 评审前自检
+- [ ] 输入来自批准且版本当前的 `Strategic Design Handoff`。
+- [ ] 统一语言与 `CONTEXT.md` 一致，没有临时创造同义词。
+- [ ] 聚合根、Entity、Value Object 的身份和边界有理由。
+- [ ] 每个聚合的不变量和允许的状态转换都写清楚。
+- [ ] 一致性规则区分了立即成立与最终一致。
+- [ ] Application、Domain、Repository、Gateway 和 API 的职责没有混淆。
+- [ ] 领域事件表达业务事实，不暴露内部表结构。
+- [ ] 关键规则都有测试 seam 和失败场景。
+- [ ] 已判断轻量 `Tactical DDD Check` 是否足够；需要升级时写明原因。
+- [ ] 未决问题有负责人、后续 Ticket、验证计划和目标版本。
+## 与其他文档怎么分工
+- [用户手册索引](./用户手册索引.md)：所有入门手册的入口。
+- [战略设计子项目用户手册](../../submodules/yss-strategic-design-harness/docs/user-guide/战略设计子项目用户手册.md)：上游 Discovery、DDD 战略设计、Spec、原型和 Strategic Design Handoff。
+- [系统概要设计模板](../architecture/templates/system-overview-design-template.md)：轻量 Tactical DDD Check 的记录位置。
+- [架构评审清单](../architecture/templates/architecture-review-checklist.md)：设计评审时的结构化检查项。
+- `yss-router` 与后端 / 前端专项技能：批准后的实现合同、代码和验证规则。
+本手册是模板源中的通用分发资产。真实项目应使用自己的术语、规则、合同版本和批准记录；不要把“客户合同审批”示例当成真实业务结论。

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md CHANGED Viewed

@@ -173,6 +173,60 @@ CLI 初始化、接管或同步成功后，再准备：
 每完成一步，请告诉我改了什么、证据在哪里、下一步是什么。
 ```
+## 可选：使用个人 Codex Plugin
+本节介绍的是个人、本机的可选工具，不属于 YSS 模板交付物。它不会自动安装到其他成员的环境，也不会改变项目的事实源、生命周期阶段或门禁。
+### 适合谁
+当前示例插件 `yss-backend-harness` 只服务后端工程角色。产品、项目、前端和测试角色应使用各自职责对应的工具或 Plugin，不要把后端插件当成全团队通用插件。
+### 安装和触发
+在已经安装 Codex、并且本机存在 `personal` marketplace 的环境中执行：
+```bash
+codex plugin add yss-backend-harness@personal
+```
+安装后刷新或重启 Codex，再在已登记的实现仓库中调用。例如：
+```text
+请读取当前 YSS 任务包和 Slice Contract，按 role.backend-engineer 生成或执行后端任务。
+```
+插件只能在以下条件满足后执行具体实现：
+- 仓库是 `project-instance`，不是 `template-source`；
+- 实现仓库、项目根目录、分支和验证命令已经登记；
+- OpenAPI 已 Freeze，或已记录无 API 影响；
+- Slice Contract 已批准并处于 `ready-for-agent`；
+- 任务包明确了允许写入的路径、行为和测试 seam。
+### 插件不会替代什么
+Plugin 是运行时适配器，不是新的事实源。它不会替代 `yss-product-lifecycle`、`yss-router` 或 `tdd`，不会设置 `ready-for-agent`，不会 Freeze OpenAPI，也不能承担独立审查。
+执行结果应包含 `Workflow Execution Result`（例如 `completed`、`blocked`、`needs-human` 或 `failed`）及对应证据。发现路径越界、合同过期、影响面变化或证据缺失时，应停止并回到路由流程。
+### 不可用时怎么办
+如果插件未安装、版本不兼容或执行失败，回退到通用的 `yss-router + tdd` 流程，并记录阻塞原因和实际验证命令。不要为了绕过插件故障而跳过生命周期门禁。
+### 其他应用的接入建议
+应用接入按项目需要逐步增加，不作为模板默认依赖：
+1. GitHub 或 GitLab：代码、分支、MR/PR 和 CI。
+2. Jira 或 Linear：父 Ticket、Slice Ticket、状态和责任人。
+3. GitHub Actions、GitLab CI 或 Jenkins：自动执行模板、前端和后端验证。
+4. Confluence、Notion 或飞书文档：团队说明和知识库，但不得替代仓库事实源。
+5. Figma：仅在产品设计和 UI 实现阶段接入。
+6. Slack、Teams 或企业微信：仅发送阻塞、审查和发布通知，不承载正式决策。
+7. Sentry、Grafana 或 Datadog：仅在具体产品实例上线后接入运行监控。
+推荐顺序是：本地 Git + Codex/Plugin → Git 平台 → Issue tracker → CI/CD → 知识库 → 设计、通知和监控。
 ## 一张表看懂完整路线
 | 你要解决的问题 | 正式阶段 | 完成后应该看到什么 |
@@ -630,12 +684,11 @@ ADR 是架构决策记录。
 | 角色 | 提前参与什么 | 交付前重点检查 |
 |---|---|---|
 | 需求经理 | 用户、范围、术语、成功标准 | Spec 是否还能被业务复述 |
-| 产品经理 | 优先级、页面流、状态和原型 | 实现是否偏离已确认体验 |
+| 产品经理 | 优先级、页面流、状态、原型及商业约束、交付承诺和发布窗口 | 实现是否偏离已确认体验；对外承诺是否经过生物人批准 |
 | 前端工程师 | 原型可行性、API 是否好用 | 页面状态、截图、console、`pnpm` |
 | 后端工程师 | API、数据、领域规则、工程准备 | 行为测试、契约、`./mvnw` |
 | 测试工程师 | 测试入口、异常和恢复路径 | 独立审查、当次验证 |
 | 项目经理 | Ticket、依赖、仓库和风险 | 候选、发布顺序和回滚点 |
-| 商务 | 商业约束和交付窗口 | 对外承诺是否与实际范围一致 |
 角色可以由不同 Agent 运行时承载。实现者不能审查自己的候选。