create-yss-spec 2.1.15 → 2.2.1

package/template/.trae/skills/ytree-usage/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ytree-usage
+description: 指导 YSS UI 左树右表、组织树、分类树、目录树和节点管理页使用 @yss-ui/components 的 YTree，覆盖 fieldNames 字段映射、搜索过滤、受控选中、节点动作、删除确认、虚拟滚动和自适应高度；当生成或修改树形筛选、左树右表、树搜索或树节点操作时使用。
+---
+
+# YTree 使用
+
+## 触发条件
+
+- 生成或修改左树右表、组织树、分类树、目录树、树搜索或树节点操作。
+- 需要配置 `fieldNames`、受控选中、`YTreeActionItem` 或树区域自适应高度。
+
+## 不适用场景
+
+- 树数据只用于表单 TreeSelect 字段：使用 `YFormily` 或对应表单规范。
+- 页面只有普通列表而没有层级筛选：使用 `../ytable-usage/SKILL.md`。
+
+## 实施流程
+
+1. 当前会话可用 yss-ui MCP 时，先用 `get_component_docs` 查询 `YTree` 的 Props、Slots、Events 和 `YTreeActionItem`；需要搜索、节点动作、受控选中或左树右表时，再用 `get_demo` 获取对应官方 Demo。
+2. MCP 工具不可用、调用失败或用 `search_docs/list_components` 校正后仍无结果时，才读取最新 `llms-full.txt`；若文档与当前项目依赖版本不一致，用当前源码和导出核验。
+3. 确定树数据的 title/key/children 字段、受控状态和选中后的业务联动。
+4. 按容器布局配置 `useTreeHeight`，再添加搜索和节点动作。
+5. 若包含删除，单独完成气泡确认链路；不把 `danger` 颜色当成二次确认。
+
+## 硬约束（禁止/必须）
+
+- 从 `@yss-ui/components` 导入 `YTree`、`YTreeActionItem` 等真实导出；高度使用 `@yss-ui/hooks` 的 `useTreeHeight`。
+- 数据字段不一致时配置 `fieldNames`，不为了改名重复递归复制树数据。
+- 搜索使用 `filterable + v-model:searchValue`；受控选中使用 `v-model:selectedKeys`。
+- 普通节点菜单使用 `showActions + getNodeActions`，并监听 `@action`。`YTreeActionItem` 只支持 `key/label/icon/disabled/danger`，禁止臆造 `isConfirm/click` 等字段。
+- `danger: true` 只改变危险项视觉，不会弹出确认框。删除必须放在节点附近的 `#node-suffix` 或当前选中节点操作区，用 Ant Design Vue `Popconfirm` 的 `@confirm` 调用接口；不使用居中 `Modal.confirm`。
+- 树区域需要滚动时绑定 `:height="treeHeight"`，不默认添加 `:virtual="true"`。只有展开后可见扁平节点数 `* itemHeight > height` 时才会实际裁剪 DOM。
+- 使用 YTree 内置搜索时，高度 Hook 通过 `extraOffset: YTREE_SEARCH_HEIGHT` 扣除 48px；不再叠加无依据的魔法数。
+- 左树右表优先组合 `YSplitPane + YCard + YTree + YTable`；切换节点时同步查询条件并把右表分页重置为第 1 页。
+- 节点删除 API 的错误由 `mutator.ts` 统一提示并 reject；不在 `else/catch` 重复 `message.error`。
+
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YTree, type YTreeActionItem } from '@yss-ui/components';
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
+
+/** 树节点数据。 */
+interface TreeNode {
+  id: string;
+  name: string;
+  children?: TreeNode[];
+}
+
+const emit = defineEmits<{
+  create: [node: TreeNode];
+  edit: [node: TreeNode];
+}>();
+const treeAreaRef = ref<HTMLDivElement>();
+const treeData = ref<TreeNode[]>([]);
+const searchValue = ref('');
+const selectedKeys = ref<Array<string | number>>([]);
+const { treeHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT,
+});
+
+/** 生成当前节点的非危险操作。 */
+const getNodeActions = (): YTreeActionItem[] => [
+  { key: 'add', label: '新增子节点' },
+  { key: 'edit', label: '编辑' },
+];
+
+/** 处理 YTree 动作事件。 */
+const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
+  if (key === 'add') emit('create', node);
+  if (key === 'edit') emit('edit', node);
+};
+</script>
+
+<template>
+  <div ref="treeAreaRef" class="tree-area">
+    <YTree
+      :height="treeHeight"
+      :tree-data="treeData"
+      :field-names="{ title: 'name', key: 'id', children: 'children' }"
+      filterable
+      show-actions
+      v-model:searchValue="searchValue"
+      v-model:selectedKeys="selectedKeys"
+      :get-node-actions="getNodeActions"
+      @action="handleTreeAction"
+    />
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.tree-area {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+```
+
+## 删除确认边界
+
+```vue
+<template #node-suffix="{ node }">
+  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
+    <YButton type="link" @click.stop>删除</YButton>
+  </Popconfirm>
+</template>
+```
+
+`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。
+
+## 交付检查清单
+
+- [ ] `fieldNames`、`searchValue`、`selectedKeys`、`action` 与真实 API 一致。
+- [ ] 节点动作项未出现虚构字段，删除不会点菜单后立即执行。
+- [ ] 高度偏移与内置搜索实际开关一致，没有多扣魔法数。
+- [ ] 左树选中后，右表查询条件和分页重置闭环清晰。
+
+## 失败兜底策略
+
+- 节点字段不统一时先修正 `fieldNames`，不复制整棵树换键。
+- 点击删除立即调用 API 时，移出节点动作菜单，改为节点附近或页面操作区 `Popconfirm`。
+- 传入 `height` 但节点未裁剪时，先核对展开后可见节点数、`itemHeight` 和阈值，不盲目强制 `virtual=true`。
+- 节点 API 失败后让 mutator reject 中断右表刷新等后续流程，不重复错误提示。

package/template/AGENTS.md

@@ -83,15 +83,15 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 | merge / rebase 冲突 | `resolving-merge-conflicts` |
 | 架构治理、难测模块或深模块设计 | `improve-codebase-architecture` / `codebase-design` |
 | 跨线程、跨仓库、上下文过长或原型结论回流 | `handoff` 或等价交接记录 |
-| 本地知识库 init / refresh / rebuild，或要把研究结果落成持久 wiki | `llm-wiki`（落成持久 wiki 用 `ingest`；已映射 live 源变了用 `refresh`） |
+| 本地知识库 init / refresh / rebuild，或要把研究结果落成持久 wiki | `llm-wiki`（落成持久 wiki 用 `ingest`；已映射 live 源变了用 `refresh`）。`template-source` 的 wiki-root 为 `.template-source/wiki`；`project-instance` 不附带源仓库编译树，需要时在仓库根 `wiki/` 执行 `init` |
 
 业务行为默认按 `tdd` 使用已确认的公开 seam 逐切片实现。一次性生成、纯配置或流程文档不适用代码 TDD 时，必须记录例外理由和可执行验证方式。
 
 ## 9. 工作区与实现仓库边界
 
-当前仓库默认是研发管理仓库，运行时代码优先位于已登记的独立实现仓库。只有用户明确选择当前仓库承载实现代码时，才使用唯一的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 项目根。
+当前仓库默认是研发管理仓库，运行时代码优先位于已登记的独立实现仓库（`repository_scope: external-repository`）。只有用户明确选择当前仓库承载实现代码时，才使用同源的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`（`harness-apps`），或以 Git submodule 把独立实现仓挂到同一 `apps/` 布局（`git-submodule`）。三种 scope 必须用登记字段、Git 身份和工作树 gitlink 区分；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得当成普通目录。
 
-`apps/backend/` 和 `apps/frontend/` 只是项目容器；`app/backend/`、`app/frontend/` 及其子路径禁止作为工程输出。完整登记字段和跨仓约束见 `docs/process/implementation-repo-integration.md`。
+`apps/backend/` 和 `apps/frontend/` 只是项目容器；`app/backend/`、`app/frontend/` 及其子路径禁止作为工程输出。`git-submodule` 不得登记为 `harness-apps`，也不得把实现源码复制进 Harness。完整登记字段、嵌套 Git 授权和跨仓约束见 `docs/process/implementation-repo-integration.md`。
 
 ## 10. 独立审查、验证和追踪
 
@@ -113,8 +113,8 @@ README、用户指南、根目录 `CLAUDE.md` 和其他说明文档只引用或
 
 本仓库是 `template-source` Harness / 研发管理仓库，没有前端 / 后端运行时应用；可运行、可测试的表面只有 Node 工具链与治理校验脚本。
 
-- 依赖与工具链：Node `>=22 <27`（`.nvmrc` 固定 22）；`pnpm` 通过 `packageManager` 字段由 corepack 自动切换到 `10.15.0`，无需手工切换。Node 依赖只装在 `.template-source/tooling/node`，仓库根没有 `package.json`。
-- 测试：`pnpm --dir .template-source/tooling/node test`（`node --test`，共 15 个用例）。
+- 依赖与工具链：Node `>=22 <27`（`.nvmrc` 固定 22）；`pnpm` 通过 `packageManager` 字段由 corepack 自动切换到 `10.15.0`，无需手工切换。Node 依赖只装在 `.template-source/tooling/node`，仓库根没有 `package.json`。本仓 wiki-root 为 `.template-source/wiki`。
+- 测试：`pnpm --dir .template-source/tooling/node test`（`node --test`，共 16 个用例）。
 - 构建 / lint：`pnpm --dir .template-source/tooling/node build:vendor` 与 `check:vendor` 维护 `scripts/vendor/*.mjs`；顶层 lint 是 `verify-template` 内对所有脚本执行的 `node --check`。
 - 完整发布门禁（相当于"运行应用"）：`scripts/verify-template`，成功输出 `模板发布校验通过`。它串联证据索引、`pnpm test`、`check:vendor` 和全部 `scripts/verify-*` 场景校验。
 - 非显然的坑：`scripts/verify-lifecycle-registry`（及其对应测试 `Node lifecycle registry verifier ...`）会 shell out 到 `python3` 并 `import jsonschema` 做 JSON Schema 校验。缺少该 Python 模块时测试会以 `ModuleNotFoundError: No module named 'jsonschema'` 失败，而不是代码问题；update script 已负责 `pip3 install jsonschema`。

package/template/CONTEXT.md

@@ -68,11 +68,12 @@
 | 生态发布清单 | 关联模板 schema 与 commit、CLI 版本与快照、公开技能来源与导出 hash 的跨仓发布证据。 | — | 不要求尚未生成的仓库 commit 互相循环引用。 |
 | 研发管理仓库 | 承载 Spec、OpenAPI、架构、Ticket、验证、发布和复盘等研发管理资产的仓库。 | — | 不等同于前端 / 后端代码 monorepo。 |
 | 实现仓库 | 承载前端、后端或其他运行时代码及其 Git、CI、MR / PR、测试命令和发布流水线的仓库。 | — | 不要把实现仓库的源码所有权混入研发管理仓库。 |
+| Git 子模块分层接入 | 将前端 / 后端实现仓以 Git submodule（gitlink，mode `160000`）挂到 `project-instance` 的 `apps/` 布局下，并登记 `repository_scope: git-submodule`。 | — | 不得与 `harness-apps` 同源 monorepo 或无 gitlink 的 `external-repository` 混用；禁止把实现源码复制进 Harness 冒充 submodule。 |
 | 跨仓库契约变更 | 需要两个或多个独立仓库协同实现、验证和按顺序发布的共享契约变化。 | — | 任一参与仓库未完成契约对齐和集成验证时，不得单独声称整体可发布。 |
 | 模板源仓库（`template-source`） | 承载 `yss-spec-project-template` 权威模板资产及其演进规则的仓库身份。 | — | 只管理可复用模板，不承载某个具体产品的研发生命周期资产。 |
 | 模板实例仓库（`project-instance`） | 由模板初始化后生成、承载某个具体产品研发生命周期资产的仓库身份。 | — | 不作为通用流程模板的权威来源。 |
-| 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | — | 不包含模板源审查、研究、发布路线或源仓库专属 ADR。 |
-| 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线和源仓库治理决策的归档区域。 | — | 不随 CLI 分发；不等于产品实例的研发管理资产。 |
+| 模板实例分发面 | 模板源中应随 CLI 快照进入 `project-instance` 的共享生命周期、模板、用户指南和验证资产集合。 | — | 不包含模板源审查、研究、发布路线、源仓库专属 ADR 或源仓库 LLM Wiki 编译树。 |
+| 模板源治理区 | 仅供 `template-source` 使用、保存审查证据、研究记录、跨仓契约、发布路线、源仓库治理决策和源仓库 LLM Wiki 编译树的归档区域。 | — | 不随 CLI 分发；不等于产品实例的研发管理资产。`wiki-root` 为 `.template-source/wiki`。 |
 | 仓库身份清单 | 显式声明仓库身份和清单结构版本的机器可读资产。 | — | 不承载项目名称、团队规模、Tracker 或其他易变业务配置。 |
 
 ## 业务术语

package/template/docs/agents/skill-migrations.md

@@ -0,0 +1,16 @@
+# 技能迁移说明
+
+本文记录已退役技能入口的迁移路径。退役技能不保留物理目录、投影或 lock 条目；本文件是历史名称的唯一持久兼容说明。
+
+## high-fidelity-html-prototype
+
+`high-fidelity-html-prototype` 已退役，不再作为 Router alias、默认发现入口或独立物理技能存在。
+
+迁移到：
+
+- 阶段合同：`yss-prototype-stage`
+- Codex 产品设计主入口：`product-design:index`
+- Ant Design v6 事实与 CLI 证据：`yss-antd-design`
+- 独立低保真评审：`prototype-review`
+
+迁移时保留原型评审记录、AntD CLI 验证、浏览器验证和用户确认，并由 `yss-product-lifecycle` 裁决 `gate.prototype-reviewed`、`gate.prototype-verified` 和 `gate.user-confirmation`。不得创建同名兼容目录。

package/template/docs/agents/skills-maintenance.md

@@ -7,7 +7,7 @@
 - `.agents/skills` 是跨 Agent 共享技能的唯一权威内容。
 - `.claude/skills`、`.codex/skills`、`.cursor/skills`、`.hermes/skills`、`.pi/skills`、`.qoder/skills`、`.trae/skills` 中的同名共享技能是生成投影，不得分别手工修改。
 - Cursor 的契约运行时入口是 `.cursor/skills`。若客户端同时枚举 `.claude/skills`，仍以 `.cursor/skills` 为 Cursor 投影契约，不得把两套同名 skill 解释为两个来源。
-- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；该文件当前为 shadow，不改变 Agent 实际发现列表，也不允许 Router 按其裁剪闭包。
+- 分层、别名和默认可发现性以 `docs/agents/yss-skill-registry.yaml` 为准；当前 registry 为 `active`，Router、生命周期编排器和实例发现面必须消费通过校验的 canonical 技能及其 alias 解析结果。
 - 只属于某个平台的 skill 继续保留在对应 root，并由 `skills-lock.json` 的 `platform` 分组记录。
 - 共享技能投影可以是指向权威目录的符号链接，也可以是完整同步副本；`scripts/sync-skills --check` 会检查链接目标或完整目录哈希。
 

package/template/docs/agents/yss-skill-registry.yaml

@@ -1,14 +1,14 @@
 schema_version: 1
 registry_id: yss.skill-routing
-status: shadow
+status: active
 description: >-
-  技能分层、别名、默认可发现性和 Agent 运行时入口的 shadow 路由注册表。
-  本文件不替代 skills-lock.json 的来源、hash 与投影完整性职责；Router 与生命周期编排器在 status=shadow 时不得消费本表做运行时裁剪。
+  技能分层、别名、默认可发现性和 Agent 运行时入口的可执行路由注册表。
+  本文件不替代 skills-lock.json 的来源、hash 与投影完整性职责；Router 与生命周期编排器只消费通过本表校验的 canonical 技能。
 canonical_content_root: .agents/skills
 runtime_policy:
-  consumed_by_router: false
-  consumed_by_lifecycle: false
-  discovery_enforced: false
+  consumed_by_router: true
+  consumed_by_lifecycle: true
+  discovery_enforced: true
 agent_runtime_roots:
   claude: .claude/skills
   codex: .codex/skills
@@ -27,7 +27,7 @@ skills:
   - id: ask-matt
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [lifecycle]
   - id: code-review
@@ -75,13 +75,13 @@ skills:
   - id: grill-me
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [discovery]
   - id: grill-with-docs
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [discovery]
   - id: grilling
@@ -96,17 +96,10 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [lifecycle]
-  - id: high-fidelity-html-prototype
-    layer: compatibility
-    maturity: deprecated
-    instance_default_discoverable: false
-    aliases: []
-    impacts: [prototype]
-    replaced_by: yss-prototype-stage
   - id: implement
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [lifecycle]
   - id: implementation-repo-onboarding
@@ -118,7 +111,7 @@ skills:
   - id: improve-codebase-architecture
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [quality]
   - id: llm-wiki
@@ -190,7 +183,7 @@ skills:
   - id: setup-matt-pocock-skills
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [setup]
   - id: setup-pre-commit
@@ -226,19 +219,19 @@ skills:
   - id: to-spec
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [lifecycle]
   - id: to-tickets
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [lifecycle]
   - id: triage
     layer: compatibility
     maturity: supported
-    instance_default_discoverable: true
+    instance_default_discoverable: false
     aliases: []
     impacts: [lifecycle]
   - id: using-git-worktrees
@@ -413,7 +406,7 @@ skills:
     layer: specialist
     maturity: supported
     instance_default_discoverable: false
-    aliases: []
+    aliases: [page-module-development, yss-ui-business-page-generation]
     impacts: [frontend]
   - id: yss-product-lifecycle
     layer: core
@@ -473,13 +466,13 @@ skills:
     layer: specialist
     maturity: supported
     instance_default_discoverable: false
-    aliases: []
+    aliases: [use-table-height]
     impacts: [frontend]
   - id: yss-use-tree-height
     layer: specialist
     maturity: supported
     instance_default_discoverable: false
-    aliases: []
+    aliases: [use-tree-height]
     impacts: [frontend]
   - id: yss-userinfo
     layer: specialist
@@ -499,12 +492,119 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [backend, api]
+  - id: component-selection-imports
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: file-export-download
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend, api]
+  - id: formily-foundation
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: formily-linkage-effects
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: formily-mode-slot-detail
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: formily-step-flow
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: frontend-commit
+    layer: maintainer-only
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [template-maintenance]
+  - id: java-backend-commit
+    layer: maintainer-only
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [template-maintenance]
+  - id: page-form-module
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: page-list-module
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: page-skeleton
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: prototype-page-acceptance
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [prototype, frontend]
+  - id: theme-token-usage
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend, prototype]
+  - id: vue3-best-practices
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: yedit-table-usage
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: ytable-usage
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
+  - id: ytree-usage
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [frontend]
 platform_skills:
   - id: data-analytics
     root: .codex/skills
     layer: maintainer-only
     instance_default_discoverable: false
+    aliases: []
   - id: product-design
     root: .codex/skills
     layer: specialist
     instance_default_discoverable: false
+    aliases: [product-design:index]
+external_skills:
+  - id: yss-backend-scaffold-parent
+    source: .agents/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

package/template/docs/process/implementation-repo-integration.md

@@ -21,7 +21,7 @@ apps/
 - `allowed_write_paths`、`expected_evidence_files` 和生成器输出位置必须能回指具体项目目录；直接放开 `apps/backend/` 或 `apps/frontend/` 属于路径策略违规。
 - 外部实现仓库不要求采用 Harness 的 `apps/` 布局，但仍必须登记该仓库内的实际项目根路径；跨仓库切片的写路径不得用本 Harness 的占位路径冒充真实路径。
 
-每个 Harness 内项目至少登记 `project_type`、`project_name`、`project_root` 和 `repository_scope`。同一 Git monorepo 下的多个项目可以共用一条仓库登记，但必须逐项目列出根路径和独立验证命令；不同 Git 仓库必须分别登记。
+每个 Harness 内项目至少登记 `project_type`、`project_name`、`project_root` 和 `repository_scope`。`repository_scope` 只允许 `external-repository`、`harness-apps` 或 `git-submodule`。同一 Git monorepo 下的多个项目可以共用一条仓库登记，但必须逐项目列出根路径和独立验证命令；不同 Git 仓库必须分别登记，`git-submodule` 的每个子仓各一条。
 
 ## 1.2 前端 / 后端验证命令
 
@@ -32,6 +32,28 @@ apps/
 - Ticket、Slice Implementation Contract、CI 和 Review 证据必须写下实际执行的上述命令。既有仓库缺少 `pnpm` 或 Maven Wrapper 时，先记录受控例外、替代命令和责任人，再执行。
 - 本模板源仓库没有产品 frontend / backend 运行时；其 Node 校验仍按 `AGENTS.md` 的 Cursor Cloud 说明使用 `pnpm --dir .template-source/tooling/node`。
 
+## 1.3 `repository_scope: git-submodule`
+
+当用户明确选择分层接入、且前端 / 后端保持独立 Git 历史、同时挂到 `project-instance` 工作树时，使用 Git submodule，而不是把实现源码复制进 Harness，也不是把 gitlink 登记成 `harness-apps`。
+
+```text
+<project-instance>/                      # superproject = 研发管理仓库
+├── .gitmodules
+├── apps/backend/<backend-project>/     # gitlink mode 160000
+└── apps/frontend/<frontend-project>/   # gitlink mode 160000
+```
+
+强制规则：
+
+- `layout_policy` / `implementation_path_policy` 必须是 `git-submodule-harness-apps`。挂载路径仍须是具体的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；容器根和 `app/` 单数路径一律阻断。
+- 三个 `repository_scope` 必须在登记字段、Git 身份和写路径上可区分：`git-submodule` 强制 `git_url`、`gitmodules_name`、`gitlink_path`（等于 `project_root`）、`git_entry_mode: 160000`、`superproject_git_url`、`checkout_state`，并分别登记默认分支、CI、验证命令、回滚点（子仓 SHA + 父仓 gitlink SHA）；`harness-apps` 与 `external-repository` 禁止填写这些 gitlink 身份字段（可填 `不适用`）。缺 `git_entry_mode` 不得默认为普通目录。
+- 子仓 `git_url` 必须与 `superproject_git_url` 不同。登记后必须用工作树对照（`git ls-files --stage`、`.gitmodules`、`inspectWorkingTreeScope`）：声明 `harness-apps` 但路径是 gitlink，或声明 `git-submodule` 但工作树只是普通目录 / 复制源码，均视为误路由并阻断。
+- 只允许 `git submodule add` / `git submodule update --init` 形成 gitlink；禁止把实现仓库源码 copy、subtree 或普通 clone 进 Harness 后冒充 submodule。
+- clone / CI / Cloud Agent 必须递归检出：`git clone --recurse-submodules`，或事后 `git submodule update --init`。GitHub Actions 须显式 `submodules: true|recursive` 且私有子仓另给 PAT / SSH；GitLab 须设 `GIT_SUBMODULE_STRATEGY` 并配置 job token 访问。默认不递归时目录为空，不得当作「工程不存在」去脚手架。
+- 空 gitlink、未初始化、detached HEAD 或 `--force` 覆盖挂载点一律不得当成普通目录：`scaffold_status=required` 阻断，脚手架生成器即使收到 `--force` 也不得覆盖 gitlink，且不得进入「请显式传入 `--force`」普通目录覆盖 / rename 路径；禁止在 detached HEAD 上 commit，也不得把 `--output-dir` 指向 detached HEAD 子仓后 mkdir、staging 或生成工程。先在子仓检出跟踪分支，再写代码。写入前必须读取 `inspectWorkingTreeScope` 的对象结果：只有 `.writable === true` 才可写。已登记为 `git-submodule` 的空 gitlink / uninitialized / detached HEAD 必须 `.writable === false`，即使工作树探测失败也不得把返回值当成可写。
+- Git 授权按仓分别计算，顺序强制为 **先子仓 commit/push，再父仓更新 gitlink**。父仓 push 使用 `git push --recurse-submodules=check`。跨仓库切片的 `delivery_order` 必须包含 `superproject-gitlink-update`。
+- `.gitmodules`、gitlink 和子仓工作树不是 `create-yss-spec` 受管资产；CLI `sync` 不得创建、覆盖或删除它们。
+
 ## 2. 影响面路由
 
 | 影响面 | 必须绑定的记录 | 本变更结论 |
@@ -46,7 +68,7 @@ apps/
 
 - 模板仓库负责 `yss-project.yaml`、流程事实源、迁移指南、技能投影、模板校验脚本和快照可发布状态。
 - CLI 仓库负责 `attach`、`sync`、受管 manifest、快照 commit、metadata、迁移计划、备份 / 回滚、端到端测试和用户说明。
-- CLI 只写研发管理资产；不得创建或覆盖前后端运行时代码，不删除目标 `.git`。
+- CLI 只写研发管理资产；不得创建或覆盖前后端运行时代码，不删除目标 `.git`，也不创建、覆盖或删除 `.gitmodules` 与 gitlink。
 - 模板 commit 必须是 40 位不可变提交；开发测试可通过 `YSS_SPEC_TEMPLATE_REF` 覆盖，正式发布不得跟随浮动 `main`。
 
 ## 4. Fresh verification 与 checkpoint

package/template/docs/templates/cross-repo-slice-template.md

@@ -65,6 +65,21 @@ owner: ai
 | Frontend |  | pass / fail / not-applicable |
 | E2E / 关键路径 |  | pass / fail / not-applicable |
 
+## 5.1 Git submodule（条件）
+
+`repository_scope: git-submodule` 时必填；其他范围标记 `not-applicable`。
+
+| 字段 | 值 |
+|---|---|
+| superproject-gitlink-update | pending / ready / blocked / not-applicable |
+| submodule_commit_sha | 子仓已推送的 40 位 SHA |
+| superproject_gitlink_sha | 父仓记录的 gitlink SHA，必须等于 `submodule_commit_sha` |
+| checkout_state | attached-branch / detached-head / uninitialized / empty-gitlink |
+| push_recurse_submodules | `check` |
+| clone_or_ci_recurse | `git clone --recurse-submodules` / `GIT_SUBMODULE_STRATEGY` / Actions `submodules` |
+
+`delivery_order` 必须包含子仓 MR / PR，然后是 `superproject-gitlink-update`。空 gitlink、detached HEAD 或未推送的子仓 SHA 一律 `blocked`。
+
 ## 6. Release And Rollback
 
 | 字段 | 值 |

package/template/docs/templates/implementation-repo-registry-template.md

@@ -17,11 +17,16 @@ owner: ai
 | git_url |  |
 | default_branch |  |
 | local_worktree |  |
-| repository_scope | external-repository / harness-apps |
+| repository_scope | external-repository / harness-apps / git-submodule |
 | project_type | backend / frontend / fullstack / other |
 | project_name |  |
 | project_root | 外部仓库相对路径，或 `apps/backend/<project>/` / `apps/frontend/<project>/` |
-| layout_policy | `harness-apps-multi-project` / `external-repository-native` |
+| layout_policy | `harness-apps-multi-project` / `external-repository-native` / `git-submodule-harness-apps` |
+| gitmodules_name | `git-submodule` 必填；其他范围填 `不适用` |
+| gitlink_path | 等于 `project_root`；仅 `git-submodule` |
+| git_entry_mode | `160000`；仅 `git-submodule` |
+| superproject_git_url | 父仓远端；必须与 `git_url` 不同 |
+| checkout_state | attached-branch / detached-head / uninitialized / empty-gitlink / 不适用 |
 | scaffold_status | existing / required / initialized |
 | scaffold_skill | `yss-ddd-scaffold-generator` / `yss-frontend-scaffold-generator` / none |
 | scaffold_target_confirmed | 是 / 否 / 不适用 |
@@ -41,7 +46,7 @@ owner: ai
 | typecheck_command |  |  |
 | ci_pipeline |  |  |
 
-Harness 内项目路径约束：`apps/backend/`、`apps/frontend/` 只能作为项目容器；工程必须位于具体的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`app/backend/`、`app/frontend/` 及其子路径禁止登记或生成。外部实现仓库填写真实项目根路径，不使用本表的 Harness 占位路径。
+Harness 内项目路径约束：`apps/backend/`、`apps/frontend/` 只能作为项目容器；工程必须位于具体的 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`app/backend/`、`app/frontend/` 及其子路径禁止登记或生成。外部实现仓库填写真实项目根路径，不使用本表的 Harness 占位路径。`git-submodule` 必须同时满足 Harness `apps/` 挂载路径和独立 Git 身份，不得登记为 `harness-apps` 或无 gitlink 的 `external-repository`。空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。登记后必须对照工作树 gitlink，禁止把复制进 Harness 的源码冒充 submodule。
 
 ## 2.1 项目清单（同一 monorepo 可登记多个项目）
 

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

@@ -84,8 +84,8 @@ owner: ai
 | 字段 | 内容 |
 |---|---|
 | impacted_areas |  |
-| implementation_path_policy | `harness-apps-multi-project` / `external-repository-native` |
-| project_roots | Harness 内填写 `apps/backend/<project>/` / `apps/frontend/<project>/`；外部仓库填写真实项目根 |
+| implementation_path_policy | `harness-apps-multi-project` / `external-repository-native` / `git-submodule-harness-apps` |
+| project_roots | Harness 内与 `git-submodule` 填写 `apps/backend/<project>/` / `apps/frontend/<project>/`；外部仓库填写真实项目根 |
 | required_skills |  |
 | optional_skills |  |
 | unavailable_skills | 写明 provider、fallback 和阻断结论；不得静默跳过 |
@@ -187,7 +187,7 @@ owner: ai
 
 ## 4. 外部实现仓库
 
-> 当前仓库默认不承载运行时代码。若用户明确选择 Harness 内实现，项目根必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 不能作为项目根，`app/backend/`、`app/frontend/` 及其子路径禁止使用。
+> 当前仓库默认不承载运行时代码。若用户明确选择 Harness 内实现，同源代码用 `harness-apps`；独立仓挂载用 `git-submodule`。两种项目根都必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 不能作为项目根，`app/backend/`、`app/frontend/` 及其子路径禁止使用。
 
 | repo_role | project_root | git_url | default_branch | working_branch | MR / PR | CI | test_command | build_command | 状态 |
 |---|---|---|---|---|---|---|---|---|---|

package/template/docs/user-guide//344/272/247/345/223/201/347/224/237/345/221/275/345/221/250/346/234/237/345/267/245/344/275/234/346/265/201.md

@@ -24,7 +24,7 @@
 | 架构资产   | `docs/.scratch/<feature>/architecture/`、`docs/adr/`               | 保存业务架构、功能架构、系统总体架构、数据架构和关键 ADR                              |
 | 交付过程   | `docs/.scratch/<feature>/parent-ticket.md`、`issues/`、`gates/`、`verification/` | 跟踪垂直切片、实现路由、验证记录和审查结论                                       |
 
-推荐把真实工程代码放在独立实现仓库。本仓库默认作为 Harness / 研发管理仓库，保存产品、契约和过程资产。如果用户明确选择把代码放入本仓库，才按需新增：
+推荐把真实工程代码放在独立实现仓库（`external-repository`）。本仓库默认作为 Harness / 研发管理仓库，保存产品、契约和过程资产。如果用户明确选择把代码放入本仓库，使用同源 `harness-apps`；如果要把独立前后端仓挂进本仓工作树且保留各自 Git 历史，使用 `git-submodule`：
 
 ```text
 apps/
@@ -34,7 +34,7 @@ docs/releases/
 docs/implementation/
 ```
 
-`apps/backend/` 和 `apps/frontend/` 只能作为项目容器，不能直接生成工程；`app/backend/`、`app/frontend/` 及其子路径禁止使用。不得由 Agent 自行新建任意顶层业务代码目录。实现仓库接入和跨仓库切片绑定见 `docs/process/implementation-repo-integration.md`。
+`apps/backend/` 和 `apps/frontend/` 只能作为项目容器，不能直接生成工程；`app/backend/`、`app/frontend/` 及其子路径禁止使用。`git-submodule` 挂载点仍是上述具体项目目录，但是 gitlink，不能登记成 `harness-apps`。不得由 Agent 自行新建任意顶层业务代码目录。实现仓库接入和跨仓库切片绑定见 `docs/process/implementation-repo-integration.md`。
 
 ## 2. 工具分工
 

package/template/docs/user-guide//344/272/247/345/223/201/347/240/224/345/217/221/345/205/250/347/224/237/345/221/275/345/221/250/346/234/237/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -165,7 +165,7 @@ skills 是让 AI 按规程工作的“操作手册”，不是关键词装饰。
 使用 yss-router，基于 `docs/.scratch/data-modeling/issues/04-validate-model.md`、
 冻结 OpenAPI `docs/.scratch/data-modeling/api/data-modeling.yaml` 和架构设计，
 选择最小 YSS 技能集。
-请说明为什么需要或不需要 yss-domain、yss-repository、yss-mybatis、yss-web-controller、yss-ui、api-integration。
+请说明为什么需要或不需要 yss-domain、yss-repository、yss-mybatis、yss-web-controller、yss-ui、yss-api-integration。
 不要实现代码，只输出技能路由、实现顺序和验证建议。
 ```
 
@@ -804,8 +804,8 @@ TDD 顺序示例：
 | 后端用例编排 | `yss-application` |
 | 持久化 | `yss-repository`、需要分页/批量/数据源时加 `yss-mybatis` |
 | Web 接口 | `yss-web-controller`、`yss-dto` |
-| 前端页面 | `yss-ui`、`yss-page-module-development`、`api-integration` |
-| OpenAPI client 刷新 | `yss-openapi-governance` 从冻结 YAML 派生 JSON，随后 `api-integration` 运行 Orval；只在 Freeze 后或按实现契约刷新时使用 |
+| 前端页面 | `yss-ui`、`yss-page-module-development`、`yss-api-integration` |
+| OpenAPI client 刷新 | `yss-openapi-governance` 从冻结 YAML 派生 JSON，随后 `yss-api-integration` 运行 Orval；只在 Freeze 后或按实现契约刷新时使用 |
 
 阶段门禁：
 
@@ -1072,7 +1072,7 @@ docs/user-guide/
 使用 yss-router。
 输入资产：<Spec 路径>、<交互设计路径>、<OpenAPI Freeze 路径或无 API 影响记录>、<架构设计路径>、<垂直切片路径>。
 目标：选择最小 YSS 技能集。
-请说明每个候选技能需要或不需要的理由，尤其是 yss-domain、yss-repository、yss-mybatis、yss-web-controller、yss-ui、yss-openapi-governance、api-integration。
+请说明每个候选技能需要或不需要的理由，尤其是 yss-domain、yss-repository、yss-mybatis、yss-web-controller、yss-ui、yss-openapi-governance、yss-api-integration。
 边界：不要实现代码，只输出技能路由、实施顺序、测试 seam 和验证建议。
 ```
 

package/template/docs/user-guide//347/224/237/345/221/275/345/221/250/346/234/237/346/234/200/344/275/263/345/256/236/350/267/265.md

@@ -258,7 +258,7 @@ Competitive Matrix
 
 | 场景 | 主技能 | 常见补充 |
 |---|---|---|
-| 新建完整 Vue 业务页面 | `yss-ui` | `yss-page-module-development`、`yss-openapi-governance`、`api-integration` |
+| 新建完整 Vue 业务页面 | `yss-ui` | `yss-page-module-development`、`yss-openapi-governance`、`yss-api-integration` |
 | YTable / YTree / YssFormily 页面 | `yss-ui` | `yss-use-table-height`、`yss-use-tree-height`、`yss-formily` |
 | 从零创建后端服务 | `yss-ddd-scaffold-generator` | 后续接 `yss-domain`、`yss-repository`、`yss-web-controller` |
 | 领域建模和状态规则 | `yss-domain` | — |