create-yss-spec 3.5.0 → 3.5.3

package/src/template/layout-migration.js

@@ -0,0 +1,160 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+
+const { targetPath, pathKind } = require("../filesystem/path-utils");
+const {
+  createMigrationPlan,
+  addUnsafe,
+  addConflict,
+  addRemove,
+} = require("./migration-planner");
+
+const TRACKER_FROM = "docs/agents/issue-tracker.md";
+const TRACKER_TO = ".template-spec/agents/issue-tracker.md";
+const STATIC_DIRECTORIES = [
+  "docs/agents", "docs/process", "docs/templates", "docs/user-guide",
+  "docs/plan/templates", "docs/api/templates", "docs/architecture/templates",
+  "docs/design/templates", "docs/design/tokens", "docs/design/schemas",
+  "docs/design/diagrams", "docs/discovery/templates",
+];
+const STATIC_FILES = [
+  "docs/adr/README.md", "docs/architecture/README.md",
+  "docs/plan/README.md", "docs/plan/entry-review.md",
+  "docs/discovery/README.md", "docs/discovery/IDEATION.md",
+  "docs/design/README.md", "docs/design/design.md",
+  "docs/design/design-system-sync.yaml", "docs/design/preview.html",
+  "docs/design/preview-dark.html", "docs/design/preview.css",
+  "docs/design/preview.js", "docs/engineering/backend-platforms.json",
+  "docs/engineering/backend-platforms.md",
+];
+const RETIRED_SOURCE_ONLY = new Set([
+  "docs/agents/archify-integration.md", "docs/agents/skills-maintenance.md",
+  "docs/agents/strategic-design-skills-integration.md",
+  "docs/agents/yss-ui-skills-integration.md",
+  "docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md",
+  "docs/process/github-workflows.md", "docs/process/maintenance-intensity.yaml",
+  "docs/process/template-engineering-overview.md",
+  "docs/process/template-verification-profiles.yaml",
+  "docs/process/schemas/maintenance-review-record.schema.json",
+  "docs/process/templates/maintenance-checkpoint-template.yaml",
+  "docs/design/design-system-sync.yaml", "docs/design/preview.html",
+  "docs/design/preview-dark.html", "docs/design/preview.css",
+  "docs/design/preview.js",
+]);
+const SEPARATE_LEGACY_MAPPINGS = new Set([
+  "docs/templates/prd-template.md",
+  "docs/templates/vertical-slice-issue-template.md",
+]);
+
+function digest(bytes) {
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function legacyStaticPath(ref) {
+  return STATIC_FILES.includes(ref) ||
+    STATIC_DIRECTORIES.some((directory) => ref.startsWith(`${directory}/`));
+}
+
+function collectLegacyFiles(targetDir, desiredOperations, managedFiles, plan) {
+  const found = new Set();
+  function inspect(ref) {
+    let kind;
+    try { kind = pathKind(targetPath(targetDir, ref)); }
+    catch (error) { addUnsafe(plan, ref, error.message); return; }
+    if (kind === "missing") return;
+    if (kind === "other") { addUnsafe(plan, ref, "旧治理路径是符号链接或特殊文件"); return; }
+    if (kind === "file") { found.add(ref); return; }
+    for (const entry of fs.readdirSync(targetPath(targetDir, ref))) {
+      if (entry === ".DS_Store") continue;
+      inspect(`${ref}/${entry}`);
+    }
+  }
+  for (const directory of STATIC_DIRECTORIES) inspect(directory);
+  for (const ref of STATIC_FILES) inspect(ref);
+  for (const ref of Object.keys(managedFiles || {})) {
+    if (legacyStaticPath(ref)) inspect(ref);
+  }
+  for (const operation of desiredOperations) {
+    if (operation.relativePath.startsWith(".template-spec/")) {
+      inspect(`docs/${operation.relativePath.slice(".template-spec/".length)}`);
+    }
+  }
+  return [...found].filter((ref) => !SEPARATE_LEGACY_MAPPINGS.has(ref)).sort();
+}
+
+function prepareLayoutMigration({ targetDir, desiredOperations, managedFiles = {}, explicit = false }) {
+  const plan = createMigrationPlan(targetDir);
+  const legacyFiles = collectLegacyFiles(targetDir, desiredOperations, managedFiles, plan);
+  const desiredByPath = new Map(desiredOperations.map((operation) => [operation.relativePath, operation]));
+  const operations = [...desiredOperations];
+
+  for (const from of legacyFiles) {
+    const to = `.template-spec/${from.slice("docs/".length)}`;
+    if (!explicit) {
+      addConflict(plan, from, to, "旧治理目录布局需显式 --migrate-layout；普通 attach/sync 不写入");
+      continue;
+    }
+    const source = targetPath(targetDir, from);
+    const destination = targetPath(targetDir, to);
+    const sourceBytes = fs.readFileSync(source);
+    const destinationKind = pathKind(destination);
+    if (destinationKind !== "missing" && destinationKind !== "file") {
+      addUnsafe(plan, to, "迁移目标不是普通文件");
+      continue;
+    }
+    if (from === TRACKER_FROM) {
+      if (destinationKind === "file" && !sourceBytes.equals(fs.readFileSync(destination))) {
+        addConflict(plan, from, to, "项目 tracker 的新旧配置不一致，需人工处理");
+        continue;
+      }
+      const index = operations.findIndex((operation) => operation.relativePath === TRACKER_TO);
+      if (index < 0) {
+        addConflict(plan, from, to, "当前阶段缺少 tracker 目标资产");
+        continue;
+      }
+      if (destinationKind === "missing") {
+        operations[index] = {
+          ...operations[index], type: "render", desiredContent: sourceBytes,
+          desiredHash: digest(sourceBytes),
+        };
+      }
+      addRemove(plan, from, "保留项目 tracker 原内容并退出旧路径", { action: "preserve-project-config", to });
+      continue;
+    }
+    const recordedHash = managedFiles[from]?.contentHash;
+    if (!recordedHash || digest(sourceBytes) !== recordedHash) {
+      addConflict(plan, from, to, "缺少可信受管摘要或旧治理文件已被项目修改");
+      continue;
+    }
+    const desired = desiredByPath.get(to);
+    if (!desired && !RETIRED_SOURCE_ONLY.has(from)) {
+      addConflict(plan, from, to, "目标阶段未安装对应治理资产，不能静默丢弃");
+      continue;
+    }
+    if (destinationKind === "file" && (!desired || digest(fs.readFileSync(destination)) !== desired.desiredHash)) {
+      addConflict(plan, from, to, "目标路径已存在且与当前模板不一致");
+      continue;
+    }
+    addRemove(plan, from, desired ? "可信旧治理文件由新模板取代" : "可信模板专用文件退出实例", {
+      action: desired ? "replace-with-current-template" : "retire-template-only",
+      to: desired ? to : null,
+    });
+  }
+  return { desiredOperations: operations, plan, legacyFiles };
+}
+
+function combineMigrationPlans(...plans) {
+  const targetDir = plans[0]?.targetDir;
+  const combined = createMigrationPlan(targetDir);
+  for (const plan of plans) {
+    combined.operations.push(...plan.operations);
+    combined.legacy.push(...plan.legacy);
+    combined.conflicts.push(...plan.conflicts);
+    combined.unsafe.push(...plan.unsafe);
+  }
+  return combined;
+}
+
+module.exports = { prepareLayoutMigration, combineMigrationPlans, TRACKER_FROM, TRACKER_TO };

package/src/template/migration-runtime.js

@@ -28,10 +28,10 @@ const LEGACY_SKILL_MAPPINGS = [
 ];
 
 const LEGACY_FILE_MAPPINGS = [
-  ["docs/templates/prd-template.md", "docs/templates/spec-template.md"],
+  ["docs/templates/prd-template.md", ".template-spec/templates/spec-template.md"],
   [
     "docs/templates/vertical-slice-issue-template.md",
-    "docs/templates/vertical-slice-ticket-template.md",
+    ".template-spec/templates/vertical-slice-ticket-template.md",
   ],
 ];
 

package/src/template/sync-planner.js

@@ -48,7 +48,7 @@ function classifySyncOperations({
       continue;
     }
 
-    if (operation.relativePath === "docs/agents/issue-tracker.md") {
+    if (operation.relativePath === ".template-spec/agents/issue-tracker.md") {
       unchanged.push({ ...operation, reason: "project-owned-tracker-configuration" });
       continue;
     }

package/template/.agents/rules/yss-ai-skills.md

@@ -4,6 +4,6 @@ trigger: always_on
 
 # YSS UI 实现入口
 
-仅在生产前端或 YSS UI 实现影响命中时使用本入口。先按当前 Slice Implementation Contract 与 `docs/agents/yss-skill-registry.yaml` 选择最小技能集，再进入 `.agents/skills/yss-ui/SKILL.md`；完整业务页面使用 `.agents/skills/yss-ui-business-page-generation/SKILL.md`，并按任务触发读取其引用的 canonical `SKILL.md`。原型阶段使用 `yss-prototype-stage`，不得调用生产实现技能 `yss-ui`。
+仅在生产前端或 YSS UI 实现影响命中时使用本入口。先按当前 Slice Implementation Contract 与 `.template-spec/agents/yss-skill-registry.yaml` 选择最小技能集，再进入 `.agents/skills/yss-ui/SKILL.md`；完整业务页面使用 `.agents/skills/yss-ui-business-page-generation/SKILL.md`，并按任务触发读取其引用的 canonical `SKILL.md`。原型阶段使用 `yss-prototype-stage`，不得调用生产实现技能 `yss-ui`。
 
 YTable 使用真实 API：不得臆造 `request`、`search-params` 或 `actionConfig.actions`；主操作必须放入 `#toolbar-right`，只有确实需要列设置时才使用 `toolbar-config.custom`。其余组件、表单、主题、API 与导出细则以下沉技能为准。

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,30 +3,29 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "9b579c7b954c153d2347696f53123aebaccde48f",
-  "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
+  "source_revision": "ed8865b79dbe1cb59277fe643c3cb27139674530",
+  "adaptation_ref": ".template-source/agents/strategic-design-skills-integration.md",
   "skills": [
     {
       "upstream": "prototype-review",
       "canonical": "prototype-review",
-      "upstream_hash": "6df02dd4de236a749a80efd5eba46d18be7979849af2a9af28636906ccfcb2a0"
+      "upstream_hash": "68c6e4613354ad919bab3d718739f1cc6930d8df0777d6f7db90435bdae77d52"
     },
     {
       "upstream": "yss-prototype-stage",
       "canonical": "yss-prototype-stage",
-      "upstream_hash": "6e1bcdf107d95c11faee2b988e4e0c36b8e5b76f6b40312a206b83733a96b0fc"
+      "upstream_hash": "7781df6293f381bd40781d2f6b163cf824f959624b1c34aeb9c241d6be709c89"
     },
     {
       "upstream": "yss-design-system",
       "canonical": "yss-design-system",
-      "upstream_hash": "e156229435c35827c48d3699b021e5e171ec565c2bf91cc91cbb033bf7802d7c"
+      "upstream_hash": "ae040c639056ecf2160f1231e30ac67360bd8aa1e030eac778520dd56af8068c"
     },
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "f7f765e20f4dca6aca667be03e2b9a7f2a8acc3510eefba88306961882d86ed4"
+      "upstream_hash": "6cd0ed5aa21d68cea871d0bd202beb3b28cca2981f075ad9c24667ac030118d2"
     }
   ],
-  "source_state": "committed",
-  "source_state_note": "source_revision、upstream_hash 与 gitlink 绑定同一已提交战略设计来源。"
+  "source_state": "committed"
 }

package/template/.agents/skills/.yss-skills-manifest.json

@@ -7,7 +7,7 @@
   "excluded_categories": ["library"],
   "excluded_skills": ["component-selection-imports", "java-backend-commit", "page-form-module", "page-list-module", "page-module-development", "page-skeleton", "prototype-page-acceptance", "use-table-height", "use-tree-height", "vue3-best-practices"],
   "source_revision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f",
-  "adaptation_ref": "docs/agents/yss-ui-skills-integration.md",
+  "adaptation_ref": ".template-source/agents/yss-ui-skills-integration.md",
   "package": {
     "name": "@yss-ui/skills",
     "version": "1.3.9"
@@ -37,6 +37,6 @@
       { "path": ".cursor/mcp.json", "container": "mcpServers" },
       { "path": ".vscode/mcp.json", "container": "servers" }
     ],
-    "global_install_guide": "docs/user-guide/yss-ui-mcp.md"
+    "global_install_guide": ".template-spec/user-guide/yss-ui-mcp.md"
   }
 }

package/template/.agents/skills/alibaba-java-code-style/SKILL.md

@@ -20,7 +20,7 @@ This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into
 
 ## Core Priorities
 
-- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `docs/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
+- 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
 - Keep names readable, English, and consistent with Java layer conventions.
 - Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
 - Make logs useful without wasting CPU, disk, or alert budget.

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

@@ -11,13 +11,13 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 
 普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
-If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
 
 ## 文档写作
 
-撰写审查报告时，读取 `docs/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+撰写审查报告时，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
 
 ## Process
 
@@ -30,13 +30,13 @@ If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-
 Look for the originating spec, in this order:
 
 1. A spec/Ticket/contract reference supplied by the user or an upstream lifecycle review input.
-2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `.template-spec/agents/issue-tracker.md`.
 3. A spec file under `docs/`, `specs/`, or `docs/.scratch/` matching the branch name or feature.
 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
 
 ### 3. Identify the standards sources
 
-Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `docs/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
+Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `.template-spec/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
 For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
 
@@ -89,7 +89,7 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor
 
 For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `docs/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
 
 For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 

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

@@ -2,7 +2,7 @@
 
 本文件只服务唯一默认审查技能 `code-review`。Alibaba Java、YSS 前端 / 后端 skill 是 **Standards 轴的专项检查输入**，不是第二个通用审查 skill。
 
-权威接线：`yss-product-lifecycle/references/orchestration-contract.yaml` 的 `work-unit.code-review.review_standards_route` 与 `review_input`。报告形状：`docs/templates/review-report-template.md`。
+权威接线：`yss-product-lifecycle/references/orchestration-contract.yaml` 的 `work-unit.code-review.review_standards_route` 与 `review_input`。报告形状：`.template-spec/templates/review-report-template.md`。
 
 ## 1. 编译标准源
 

package/template/.agents/skills/codebase-design/SKILL.md

@@ -116,3 +116,7 @@ Use `archify` only when the user or the governing YSS contract explicitly asks f
 
 - **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
 - **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.
+
+## 显式架构审计
+
+用户明确要求评估维护成本、模块边界或可测试性时，读取 [架构审计](references/architecture-audit.md)。输出有证据的重构候选；只有用户已授权实现范围后才能修改代码。普通术语咨询不自动扫描仓库或发起重构。

package/template/{.codex/skills/improve-codebase-architecture/SKILL.md → .agents/skills/codebase-design/references/architecture-audit.md}

@@ -1,10 +1,4 @@
----
-name: improve-codebase-architecture
-description: 显式分析代码结构的维护成本、模块边界与可测试性，提出有证据的重构候选。
-disable-model-invocation: true
----
-
-# Improve Codebase Architecture
+# 显式架构审计模式
 
 Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
 
@@ -69,7 +63,7 @@ Once the user picks a candidate, run the `/grilling` skill to walk the decision
 
 Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
 
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. If the root contract is missing, stop and restore it before continuing.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
 - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
-- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.
+- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its alternative interface design guidance within the authorized scope.

package/template/.agents/skills/cross-repo-implementation-routing/SKILL.md

@@ -16,12 +16,12 @@ description: Use when a Harness change or vertical slice may require work across
 
 ## Workflow
 
-1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
+1. 读取 `.template-spec/process/implementation-repo-integration.md` 和当前 change 资产。
 2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
 3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
 4. 核对项目根路径：Harness 内 `harness-apps` 与 `git-submodule` 项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。`git-submodule` 另核 gitlink、`.gitmodules` 和独立 `git_url`。外部 `external-repository` 记录各自的真实项目根。
 5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。`git-submodule` 必须追加 `superproject-gitlink-update`。
-6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
+6. 按 `.template-spec/templates/cross-repo-slice-template.md` 生成切片记录草案。
 7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
 
 ## Routing Matrix

package/template/.agents/skills/frontend-commit/SKILL.md

@@ -20,99 +20,10 @@ description: "为前端改动生成提交信息、审查原子提交或修复 Gi
 - 无代码改动，或改动内容与提交请求不匹配。
 - 合并提交、发布提交和自动依赖机器人提交：遵循仓库专用流程，不套用本技能的常规消息模板。
 
-## 硬约束（禁止/必须）
+## 执行合同
 
-- 必须把仓库规则视为最高优先级：依次遵循 `AGENTS.md`、`CONTRIBUTING.md`、Git hooks、解析后的 commitlint 配置、本地配置和近期历史；通用规则只作回退。
-- 只在用户明确要求提交时执行暂存和 `git commit`；若仅要求提交信息或审查，只输出候选消息与依据。
-- 必须保留用户和他人的既有改动。禁止默认使用 `git add -A`、`git add .`、`git commit -a`、`--no-verify`，也不要自动 amend、rebase、push 或改写已发布历史。
-- 提交必须是单一逻辑变更。不要用提交信息掩盖混杂的功能、修复、格式化或临时文件。
-- 遇到密钥、令牌、私钥、证书、`.env` 实值、账号数据或意外大文件时停止提交并报告具体路径，不要在输出中泄露内容。
-- 已有暂存内容视为用户选择，除非用户授权，不要擅自取消暂存或混入其他文件。
-- `fixup!` 只用于用户明确要求的评审或 autosquash 工作流，不能作为最终历史的默认提交。
-- revert 优先使用 Git 生成的回滚信息并保留被回滚 SHA，再根据仓库规范校验；不要把普通反向修改伪装成 revert。
+先读取 [公共提交合同](../git-commit-core/SKILL.md)，再读取 [专项 scope 与示例](references/scope-and-examples.md)。公共合同负责授权、暂存保护、消息格式、hook 和提交后核验，本入口负责以下专项判断。
 
-## 工作流
+读取 package.json、lockfile 和 workspace，按 pnpm 与仓库脚本执行相关测试、类型检查、lint 或构建。scope 依次为仓库枚举、包/应用、业务模块、共享能力；不用 views/hooks/文件名兜底。
 
-### 1. 建立仓库契约
-
-1. 确认仓库根目录、当前分支和工作树状态。
-2. 搜索并读取仓库级说明、贡献指南、提交模板、commitlint 配置和 `commit-msg`、`pre-commit` hooks。
-3. 检测 `package.json`、lockfile、workspace 配置和前端应用或包边界。
-4. 如果仓库使用 commitlint，优先使用本地依赖按包管理器读取解析后的配置，例如 `pnpm exec commitlint --print-config json`；不要为了校验联网安装依赖。
-5. 查看相关路径近期的非 merge 提交，了解仓库已经形成的 scope 和语言习惯，但不要复制历史中的明显错误。
-
-### 2. 审查真实改动
-
-至少检查：
-
-```bash
-git status --short --branch
-git diff --cached --name-status
-git diff --cached
-git diff --name-status
-git diff
-git ls-files --others --exclude-standard
-```
-
-- 同时理解暂存区、未暂存区和未跟踪文件；不要只依据文件名生成消息。
-- 将改动按用户可理解的行为和因果关系分组。功能实现、配套测试和为该功能必需的最小配置可以属于同一原子提交。
-- lockfile 必须与对应 manifest 一起提交。只提交项目本来就跟踪且由本次意图产生的生成代码；排除构建产物、缓存和临时文件。
-- 若无改动、改动与请求不符、多个逻辑变更无法安全拆分，先说明并停止。需要逐行拆分同一文件时，不要靠猜测改写暂存区。
-
-### 3. 选择 type、scope 与正文
-
-先读取 `./references/scope-and-examples.md`，再按「标准代码骨架」的格式生成。
-
-- type 默认从 `feat/fix/docs/style/refactor/perf/test/chore/revert/build/ci` 中选择，但仓库枚举优先。
-- scope 优先级为：仓库枚举 → monorepo 包或应用 → 业务模块 → 共享能力。使用小写 kebab-case；不要机械地以 `views`、`hooks` 或文件名作为 scope。
-- 标题使用仓库确定的 type/scope、分隔符和语言；无既定规则时默认英文 type/scope、ASCII `:` 和中文摘要；描述行为或价值，不写“修改文件”“更新代码”或单个文件名。
-- 默认将完整 header 控制在 72 个字符内；仓库配置了其他限制时服从该配置。标题末尾不加句号，不用 emoji 或全角冒号。
-- 简单单文件变更可以没有 body；多文件、非显然修复、重要功能或行为变化使用 body 解释做了什么、为什么以及如何验证。
-- 仅对真实不兼容变更使用 `!` 和 `BREAKING CHANGE:`；仅在已知编号或仓库要求时加入工单、DCO、`Signed-off-by` 等 footer，禁止编造。
-
-### 4. 验证并提交
-
-1. 根据变更范围运行仓库已有的最小充分检查，例如相关单元测试、类型检查、lint 和构建检查；优先使用仓库脚本与当前包管理器。
-2. 通过 stdin 校验完整候选消息，而不只校验 header。仅在仓库实际采用 commitlint 时使用其本地命令并要求退出码 0；否则按现有 hook/贡献指南验证，不安装新工具。
-3. 仅暂存属于当前原子提交的明确路径或安全 hunks，再重新检查 `git diff --cached --check`、`--name-status` 和完整 staged diff。
-4. 执行正常 `git commit`，允许 hooks 运行。
-5. hook 若格式化或修改文件，重新检查 staged 与 working tree，确认实际提交内容没有漂移。
-6. 提交成功后检查 `git show --stat --oneline --decorate HEAD` 和 `git status --short`，向用户报告 commit hash、消息、已运行检查以及剩余未提交改动。
-
-## 标准代码骨架
-
-```text
-type(scope)!: 中文行为摘要
-
-- 说明关键行为或原因
-- 说明兼容性、测试或必要约束
-
-BREAKING CHANGE: 说明不兼容影响和迁移方式
-Refs: 已知工单号
-```
-
-示例：
-
-```text
-feat(data-push): 优化推送任务数据源与调度规则展示
-
-- 将英文星期转换为中文调度描述
-- 按数据源目录映射业务名称并补充单元测试
-```
-
-## 交付检查清单
-
-- [ ] 完整消息通过仓库实际采用的提交校验；采用 commitlint 时记录 stdin 校验退出码 0。
-- [ ] scope 来自仓库枚举、包名或业务模块，未使用 `views`、`hooks`、`utils` 或文件名兜底。
-- [ ] 标题语言、type/scope 和长度符合仓库配置；无配置时才使用本技能回退格式。
-- [ ] 暂存区只包含当前原子提交的文件；lockfile 与对应 manifest 同提交。
-- [ ] 已运行与变更范围匹配的最小充分检查（相关测试、类型检查、lint）。
-- [ ] 提交后已核对 `git show --stat` 与 `git status --short`，并向用户报告 hash 与剩余改动。
-
-## 失败兜底策略
-
-- 无法区分 `feat`、`fix`、`refactor` 时继续检查需求和行为；仍有高影响歧义则询问用户，不自动降级为 `chore`。
-- hook 拒绝时按输出中的规则修正并重新校验，绝不使用 `--no-verify`。
-- 仓库 parser 或 hook 不支持标准破坏性标记时，不要绕过校验或静默删掉标记；报告规则冲突，并采用仓库明确批准的兼容方案。
-- 多个逻辑变更无法安全拆分时，先给出拆分方案并停止，不强行生成“大杂烩”提交。
-- 发现密钥或意外大文件时停止提交，报告具体路径并等待用户处理。
+无代码改动或请求与改动不匹配时停止。多个逻辑变更无法安全拆分时先给出拆分方案；发现凭据或意外大文件只报告路径。不以更换 type、删除破坏性标记或绕过 hooks 掩盖规则冲突。

package/template/.agents/skills/git-commit-core/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: git-commit-core
+description: Internal shared commit safety and message contract consumed by frontend-commit and java-backend-commit.
+disable-model-invocation: true
+---
+
+# 提交公共合同
+
+仅供专项提交入口读取，不作为默认发现或自动提交入口。
+
+1. 仓库 AGENTS、贡献指南、hooks、解析后的 commitlint 配置优先于通用规则；读取近期相关历史确认语言与 scope。
+2. 同时检查 `git status --short --branch`、暂存与未暂存的完整 diff、未跟踪文件。只为实际且属于用户意图的单一逻辑变更生成消息；不明确的拆分先说明，不猜测修改暂存区。
+3. 只有用户明确要求提交才暂存明确路径或安全 hunks 并执行 commit。禁止默认 `git add -A`、`git add .`、`git commit -a`、`--no-verify`，不自动 amend、rebase、push。保留既有暂存和无关工作。
+4. 遇到密钥、私钥、令牌、真实环境凭据或意外大文件停止提交并只报告路径。manifest 与 lockfile 一起处理；排除缓存与未授权生成物。
+5. 消息采用仓库 type/scope/语言；无配置时使用英文 type/scope、ASCII 冒号和中文行为摘要，header 默认不超过 72 字符。正文解释原因、兼容性和验证。只标记真实 BREAKING CHANGE，不编造工单或签署。fixup 仅限显式授权流程；revert 保留原 SHA。
+6. 运行专项入口要求的最小充分检查。仓库实际采用 commitlint 时通过 stdin 校验完整消息且退出 0，否则执行已有 hook/贡献规范，不临时安装工具。
+7. 提交前重新检查 `git diff --cached --check`、name-status 和完整暂存差异；正常执行 hooks，拒绝时修复，不绕过。hook 改文件后核对实际差异。
+8. 提交后检查 `git show --stat --oneline --decorate HEAD` 和 `git status --short`，报告 hash、消息、验证和剩余工作。生成消息或审查任务不执行提交。

package/template/.agents/skills/i-have-adhd/SKILL.md

@@ -6,7 +6,7 @@ license: MIT
 
 # i-have-adhd · YSS 适配
 
-为当前产物应用 `docs/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `docs/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
+为当前产物应用 `.template-spec/process/document-writing.md`；该文是中文写法的唯一权威来源。需要例子时读取 `.template-spec/templates/examples/lifecycle-writing-examples.md`。本技能是原资产所有者的配套技能，不持有业务决定、批准或生命周期状态。
 
 ## 触发与作用域
 

package/template/.agents/skills/i-have-adhd/references/yss-adaptation.md

@@ -14,7 +14,7 @@
 | 原因与修复直接陈述 | 区分已知现象、待验证原因和实际验证结果 |
 | 平台专属 agent 配置 | 不安装上游 Gemini 持久提示；项目 OpenAI 配置只描述当前文档配套用途 |
 
-生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `docs/process/document-writing.md` 维护；本文件只解释来源差异。
+生命周期仍拥有门禁、状态、批准和资产；本技能没有独立授权、审批或分支流程。正文规则只在 `.template-spec/process/document-writing.md` 维护；本文件只解释来源差异。
 
 注册表将本技能声明为模型可调用、实例默认可发现的通用工作流 core 技能（仍只作为文档配套）；调用者以条件依赖加载。上游 `disable-model-invocation: true` 在适配版移除；作用域由本技能触发条件限定，不延续上游会话开关。
 

package/template/.agents/skills/i-have-adhd/tests/verify-integration.mjs

@@ -7,7 +7,7 @@ import {pathToFileURL} from 'node:url';
 const root=path.resolve(process.argv[2] || '.');
 const read=ref=>fs.readFileSync(path.join(root,ref),'utf8');
 const {parse}=await import(pathToFileURL(path.join(root,'scripts/vendor/yaml.mjs')));
-const registry=parse(read('docs/agents/yss-skill-registry.yaml'));
+const registry=parse(read('.template-spec/agents/yss-skill-registry.yaml'));
 const skill=registry.skills.find(x=>x.id==='i-have-adhd');
 assert.equal(skill.instance_default_discoverable,true);
 assert.equal(registry.invocation_contract.overrides['i-have-adhd'].invocation_mode,'model');
@@ -27,7 +27,7 @@ for (const target of locked.targets) {
   const skillPath=target.endsWith('/i-have-adhd')?target:path.join(target,'i-have-adhd');
   assert.equal(treeHash(path.join(root,skillPath)),locked.effectiveHash,`projection ${target}`);
 }
-for(const ref of ['docs/process/document-writing.md','docs/templates/examples/lifecycle-writing-examples.md']) {
+for(const ref of ['.template-spec/process/document-writing.md','.template-spec/templates/examples/lifecycle-writing-examples.md']) {
   assert.ok(read(ref).length);
   assert.ok(!read(ref).includes('.template-source/'));
 }

package/template/.agents/skills/implementation-repo-onboarding/SKILL.md

@@ -16,12 +16,12 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 ## Workflow
 
-1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `docs/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `docs/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
+1. 按根 `yss-project.yaml` 确认 `project-instance` 身份并消费根 `CONTEXT.md`，读取 `.template-spec/process/implementation-repo-integration.md`。命中既有 Java/Maven 跨仓交付接入时，先按 `.template-spec/process/delivery-preflight.md` 以已知原始引用准备清单并运行 `scripts/preflight-delivery --input <file> --stage prepare --json`；缺失来源保持缺失，不伪造 scope、批准、生成器或模块事实。预检可在拟初始化目标上列出当前缺项，但不会创建工程或执行输入命令。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
 3. 如果输入是远端 URL，优先使用只读 Git 查询。需要完整工作树时：`external-repository` 只能 clone 到临时目录；`git-submodule` 只能通过 `git submodule add` / `git submodule update --init` 在已批准的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` gitlink 挂载点检出，禁止普通 clone 或复制源码进 Harness。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
 5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
-6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
+6. 按 `.template-spec/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
 7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。命中交付预检时，登记和工程基线补齐后重跑 `prepare`；将结构化诊断的责任来源和恢复入口纳入缺口清单，在初始化或构建前关闭当前阶段阻断。后续阶段证据尚未形成不能被当作本阶段失败；其他技术栈/不涉及该交付协议的接入记录不适用原因，不能冒充后端 v2 正例。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。需要转入已授权写入时，先按 [写范围核验](references/write-scope.md) 检查工具对象结果；只有 `.writable === true` 可写，其他形态或状态一律阻断。
 
 ## Baseline Checks