create-yss-spec 2.1.14 → 2.2.0

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -5,6 +5,12 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+import {
+  findGitRoot,
+  gitSubmoduleScaffoldViolation,
+  overlayMountViolation
+} from "../../../../scripts/lib/repository-scope-policy.mjs";
+
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
 const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
@@ -87,11 +93,28 @@ class ScaffoldGenerator {
     this.scaffoldContract = undefined;
   }
 
+  gitRootForOutput() {
+    return findGitRoot(this.finalProjectRoot) || findGitRoot(this.outputDir) || REPOSITORY_ROOT;
+  }
+
+  refuseGitlinkAsRegularDirectory(gitRoot, target) {
+    const overlay = overlayMountViolation(gitRoot, target, { force: true });
+    if (overlay) fail(overlay);
+  }
+
   async generate() {
     await this.validateHarnessOutputLayout();
-    if (await exists(this.finalProjectRoot) && !this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    const gitRoot = this.gitRootForOutput();
+    const gitlinkViolation = gitSubmoduleScaffoldViolation(gitRoot, this.outputDir, this.projectName, { force: this.options.force });
+    if (gitlinkViolation) fail(gitlinkViolation);
+    this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+    const targetExists = await exists(this.finalProjectRoot);
+    if (targetExists) {
+      this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+      if (!this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    }
     await this.validateContractMetadata();
-    if (await exists(this.finalProjectRoot) && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
+    if (targetExists && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
     await mkdir(this.outputDir, { recursive: true });
     const stagingRoot = await mkdtemp(path.join(this.outputDir, `.${this.projectName}.staging-`));
     this.projectRoot = path.join(stagingRoot, this.projectName);
@@ -101,7 +124,11 @@ class ScaffoldGenerator {
       this.generateDatabaseScripts(); await this.generateDocumentation(); await this.writeGenerationManifest();
       await this.copyWrapperFiles(); await this.validateGeneratedArtifacts();
       let backupPath;
-      if (await exists(this.finalProjectRoot)) { backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`); await rename(this.finalProjectRoot, backupPath); }
+      if (await exists(this.finalProjectRoot)) {
+        this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+        backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`);
+        await rename(this.finalProjectRoot, backupPath);
+      }
       await rename(this.projectRoot, this.finalProjectRoot); this.projectRoot = this.finalProjectRoot;
       console.log(`\n✅ 项目生成完成!\n📂 项目位置: ${this.projectRoot}`);
       if (backupPath) console.log(`♻️ 原项目备份: ${backupPath}`);

package/template/.pi/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -1,11 +1,14 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { run } from "./run_scaffold_verification.mjs";
+import { makeGitlinkFixture } from "../../../../scripts/lib/git-submodule-fixtures.mjs";
+import { GITLINK_MODE, gitLsFilesStage } from "../../../../scripts/lib/repository-scope-policy.mjs";
 
 const scripts = path.dirname(fileURLToPath(import.meta.url));
 const generator = path.join(scripts, "generate_scaffold.mjs");
@@ -21,6 +24,55 @@ test("拒绝不一致合同和未经明确批准的非空目录覆盖", async (t
 
 test("已批准的 --force 先备份非空目标，再提交 staging 工程", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const oldProject = path.join(data.output, "demo-service"); await mkdir(oldProject); await writeFile(path.join(oldProject, "old.txt"), "recoverable"); const result = await command([...data.args, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]); assert.equal(result.code, 0, result.stderr); const entries = await readdir(data.output); const backup = entries.find((entry) => entry.startsWith(".demo-service.backup-")); assert.ok(backup); assert.equal(await readFile(path.join(data.output, backup, "old.txt"), "utf8"), "recoverable"); assert.ok((await readdir(path.join(data.output, "demo-service"))).includes("pom.xml")); });
 
+test("拒绝覆盖 .gitmodules 登记的 git-submodule 挂载点", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const superproject = path.join(data.root, "harness");
+  const output = path.join(superproject, "apps/backend");
+  await mkdir(path.join(output, "demo-service"), { recursive: true });
+  await writeFile(path.join(superproject, ".gitmodules"), "[submodule \"demo-service\"]\n\tpath = apps/backend/demo-service\n\turl = https://example.invalid/demo-service.git\n");
+  const contractFile = path.join(data.root, "gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  assert.equal(result.code, 1, result.stderr);
+  assert.match(`${result.stdout}\n${result.stderr}`, /gitlink 不得由脚手架覆盖/);
+});
+
+test("拒绝在 detached HEAD 子仓工作树内当成普通目录生成", async (t) => {
+  const data = await fixture();
+  const detached = makeGitlinkFixture({ checkout: "detached-head" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => detached.cleanup());
+  const output = path.join(detached.superproject, detached.mount);
+  const contractFile = path.join(data.root, "detached-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "nested-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /detached HEAD 不得当成普通目录写入/);
+  assert.equal(existsSync(path.join(output, "nested-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("staging") || name === "nested-service"), false);
+});
+
+test("--force 覆盖真实 gitlink 不得走普通目录覆盖路径", async (t) => {
+  const data = await fixture();
+  const empty = makeGitlinkFixture({ checkout: "empty-gitlink" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => empty.cleanup());
+  const output = path.join(empty.superproject, "apps/backend");
+  const contractFile = path.join(data.root, "empty-gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "billing-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /--force 不得把 git-submodule 挂载点当成普通目录覆盖|gitlink 不得/);
+  assert.equal(existsSync(path.join(output, "billing-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("backup")), false);
+  assert.equal(gitLsFilesStage(empty.superproject, empty.mount)?.mode, GITLINK_MODE);
+});
+
 test("验证器记录三条 wrapper 命令的成功和失败证据", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\n[ \"$1\" = test ] && exit 2\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const evidence = path.join(root, "evidence"); const report = await run(project, evidence); assert.equal(report.status, "failed"); assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 2, 0]); assert.match(await readFile(path.join(evidence, "mvnw-test.stderr.log"), "utf8"), /^$/); });
 
 test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence")); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });

package/template/.pi/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -31,7 +31,7 @@ branch: template
 ## Workflow
 
 1. 确认当前任务已经通过 Harness 入口分诊，且实现位置已记录在 proposal、design、build entry review、实施计划或实现路由记录中。
-2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。
+2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。

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

@@ -78,7 +78,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 
 YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空或摘要变化时返回 `blocked`，不能缩小审查范围或合并不同候选的结论。
 
-Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
+Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 
 “然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
 

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

@@ -9,6 +9,10 @@ implementation_path_policy:
   forbidden_roots: [app/backend/, app/frontend/]
   container_roots_are_projects: false
   external_repository_uses_native_root: true
+  policies: [harness-apps-multi-project, external-repository-native, git-submodule-harness-apps]
+  git_submodule:
+    repository_scope: git-submodule
+    layout_policy: git-submodule-harness-apps
 
 review_verification:
   low_medium_combined_independent_executor: true
@@ -260,6 +264,26 @@ git_authorization:
     authorized_value: true
     non_empty: [push_scope, push_authorization_ref]
     unauthorized_action: checkpoint-only
+  git_submodule:
+    applies_when: repository_scope=git-submodule
+    forbid_commit_on_detached_head: true
+    commit_order: [submodule-repositories, superproject-gitlink]
+    push_order: [submodule-repositories, superproject-gitlink]
+    push_recurse_submodules: check
+    empty_gitlink_scaffold: blocked
+    treat_empty_gitlink_as_regular_dir: blocked
+    treat_detached_head_as_regular_dir: blocked
+    force_overlay_mount: blocked
+    write_inside_detached_head: blocked
+    require_git_entry_mode: "160000"
+    working_tree_declared_scope_must_match: true
+    copy_source_into_harness: forbidden
+    clone_requires_recurse_submodules: true
+    delivery_order_must_include: superproject-gitlink-update
+    nested_authorization: per-repository
+    inspect_working_tree_writable: explicit-boolean
+    empty_gitlink_writable: false
+    force_overlay_regular_dir_path: blocked
 
 seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan, target_version_or_release_date]
 

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

@@ -69,6 +69,8 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 实现授权、`orchestrate`/`resume` 的有界写入、当前分支和 Git checkpoint 都不蕴含 commit 或 push 授权。执行 commit 前必须同时取得 `commit_authorized=true`、非空 `commit_scope` 和 `commit_authorization_ref`；执行 push 前必须同时取得 `push_authorized=true`、非空 `push_scope` 和 `push_authorization_ref`。任一缺失时只记录 checkpoint 判断并保持 Git 状态不变；负责人要求、时间压力、测试通过或“本地 commit 可逆”都不能补足用户授权。
 
+`repository_scope: git-submodule` 时授权按仓分别计算：禁止在 detached HEAD 提交；commit / push 顺序必须先子仓、再父仓 gitlink（`superproject-gitlink-update`）；父仓 push 使用 `git push --recurse-submodules=check`。空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录脚手架，也不得把实现源码复制进 Harness。登记字段必须能与 `harness-apps` / `external-repository` 区分，并对照工作树 gitlink。
+
 ## 必须暂停
 
 - Spec baseline、需求冻结、原型确认、OpenAPI Freeze 或 Architecture Review 等普通门禁等待人工裁决。

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

@@ -59,7 +59,7 @@ AND UI 影响切片的前端实现还原计划已通过 schema 校验、`templat
 
 进入代码审查时保存 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest` 及 Spec、Ticket、合同、Checklist、YSS Execution Result 引用。`worktree` 候选必须一次捕获 committed、staged、unstaged 和 untracked 文件；manifest 的按模式必填字段以及 `yss-worktree-candidate-v1`（raw path、uint64 big-endian 长度、tracked/untracked record、symlink 和不支持条目）以 `orchestration-contract.yaml.review_input` 为唯一执行定义。两个 Reviewer 消费同一不可变快照；返回后或完成 checkpoint 摘要变化则返回 `blocked` 并重新审查。不新增生命周期状态，只把该清单作为审查证据。
 
-Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。
+Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。`git-submodule` 另保存每仓授权、`checkout_state` 和先子后父顺序；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点时不得当成普通目录 commit / 脚手架。
 
 ## 状态块
 

package/template/.pi/skills/yss-router/SKILL.md

@@ -29,7 +29,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - Repository/数据模型影响缺少数据架构时，不得路由持久化实现。
 - API 变化必须回到生命周期 Draft/Review/Freeze；半成品 backend 不得冒充稳定 source of truth。
 - 后端端到端切片必须包含 Application；对象/POJO 影响按契约自动补 `mapstruct`、`lombok`、`alibaba-java-code-style`。
-- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。
+- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
 - 原型确认后若 backend `scaffold_status=required`，先由本 Router 按 `scaffold_contract_schema` 编译 `yss-ddd-scaffold-generator` 的 `controlled-generation` 工作单元合同 draft；合同必须带 `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据和验证命令。经生命周期编排器批准并持久化后才能运行生成器，再由受控工作单元实际执行固定的 `./mvnw validate`、`./mvnw test`、`./mvnw package` 并记录逐条结果，随后加载 `yss-backend-scaffold-parent` 并重新编译业务合同；脚手架不承载业务行为。

package/template/.pi/skills/yss-router/references/router-contract.yaml

@@ -15,10 +15,30 @@ implementation_path_policy:
   forbidden_roots:
     - app/backend/
     - app/frontend/
+  policies:
+    - harness-apps-multi-project
+    - external-repository-native
+    - git-submodule-harness-apps
+  git_submodule:
+    repository_scope: git-submodule
+    layout_policy: git-submodule-harness-apps
+    git_entry_mode: "160000"
+    empty_gitlink_scaffold: blocked
+    treat_empty_gitlink_as_regular_dir: blocked
+    treat_detached_head_as_regular_dir: blocked
+    force_overlay_mount: blocked
+    write_inside_detached_head: blocked
+    copy_source_into_harness: forbidden
+    inspect_working_tree_writable: explicit-boolean
+    empty_gitlink_writable: false
+    force_overlay_regular_dir_path: blocked
   rules:
     - "Harness 内每个运行时工程必须位于具体 project 目录，不能直接写入 apps/backend/ 或 apps/frontend/。"
     - "app/backend/、app/frontend/ 及其子路径不是兼容别名，必须阻断。"
     - "外部实现仓库使用登记的真实项目根路径，不用 Harness 容器路径冒充。"
+    - "git-submodule 挂载路径使用 git-submodule-harness-apps，必须是 gitlink 且分别登记；不得登记为 harness-apps。"
+    - "空 gitlink、detached HEAD、--force 覆盖挂载点不得当成普通目录；也不得在 detached HEAD 工作树内当普通目录写入。"
+    - "inspectWorkingTreeScope 必须返回 { writable }；空 gitlink / detached HEAD 的 writable 必为 false；--force 覆盖 gitlink 不得走普通目录覆盖路径。"
 subcontract_statuses: [required, not-applicable]
 
 readiness:

package/template/.pi/skills/yss-router/references/slice-implementation-contract.md

@@ -37,7 +37,7 @@ slice_contract:
         reason:
   common:
     impacted_areas: []
-    implementation_path_policy: harness-apps-multi-project # or external-repository-native
+    implementation_path_policy: harness-apps-multi-project # or external-repository-native | git-submodule-harness-apps
     project_roots: []
     required_skills: []
     optional_skills: []

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

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

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

@@ -18,11 +18,11 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 1. 确认当前仓库是 Harness 仓库，读取 `docs/process/implementation-repo-integration.md`。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
-3. 如果输入是远端 URL，优先使用只读 Git 查询；需要 clone 时只能 clone 到临时目录，不能 clone 到 Harness 仓库内。
+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. 判定实现位置：Harness 内只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。外部实现仓库记录真实项目根路径，不套用 Harness 占位路径。
-6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
-7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
+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` 这些字段填 `不适用`。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。
 
 ## Baseline Checks
 
@@ -36,7 +36,7 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 ## Boundaries
 
 - 不直接提交、推送、创建 MR / PR 或修改实现仓库。
-- 不把实现仓库源码复制进 Harness 仓库。
+- 不把实现仓库源码复制进 Harness 仓库；`git-submodule` 只能形成 gitlink，不能 copy / subtree 冒充。
 - 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
 - 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
 - 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。

package/template/.qoder/skills/llm-wiki/SKILL.md

@@ -51,7 +51,7 @@ node <skill-root>/scripts/extract.mjs skill-names --in <live-lock.json> --out <w
 
 ## Steps
 
-1. Detect: `wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists.
+1. Detect: `<wiki-root>/wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists. Default wiki-root is repo-root `wiki/`. If `yss-project.yaml` is `repository_mode: template-source`, wiki-root is `.template-source/wiki`.
 2. If the user is asking a repository question, load [query.md](references/query.md) and stop. Do not lint, ingest, or append `log.md`.
 3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
 4. **Fact order:** called code > table comments / config defaults > stale raw copies. After writing, re-read live sources for a sample of claims (`N = min(5, changed pages)`).

package/template/.qoder/skills/llm-wiki/references/discover.md

@@ -27,6 +27,7 @@ Unless the user replaces this list with the host's single source-of-truth table:
 ## Default exclude
 
 - `docs/reviews/`
+- `.template-source/evidence/`
 - `docs/.scratch/`
 - Agent projection directories (copies or symlinks of shared skills)
 - `node_modules`

package/template/.qoder/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -64,7 +64,7 @@ node scripts/generate_scaffold.mjs \
 - 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若仓库已经存在相同工程，先核对覆盖范围。
 - 输出目录必须显式指定；非空目录默认拒绝写入，确认覆盖时才使用 `--force`。
-- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。

package/template/.qoder/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -5,6 +5,12 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+import {
+  findGitRoot,
+  gitSubmoduleScaffoldViolation,
+  overlayMountViolation
+} from "../../../../scripts/lib/repository-scope-policy.mjs";
+
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
 const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
@@ -87,11 +93,28 @@ class ScaffoldGenerator {
     this.scaffoldContract = undefined;
   }
 
+  gitRootForOutput() {
+    return findGitRoot(this.finalProjectRoot) || findGitRoot(this.outputDir) || REPOSITORY_ROOT;
+  }
+
+  refuseGitlinkAsRegularDirectory(gitRoot, target) {
+    const overlay = overlayMountViolation(gitRoot, target, { force: true });
+    if (overlay) fail(overlay);
+  }
+
   async generate() {
     await this.validateHarnessOutputLayout();
-    if (await exists(this.finalProjectRoot) && !this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    const gitRoot = this.gitRootForOutput();
+    const gitlinkViolation = gitSubmoduleScaffoldViolation(gitRoot, this.outputDir, this.projectName, { force: this.options.force });
+    if (gitlinkViolation) fail(gitlinkViolation);
+    this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+    const targetExists = await exists(this.finalProjectRoot);
+    if (targetExists) {
+      this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+      if (!this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    }
     await this.validateContractMetadata();
-    if (await exists(this.finalProjectRoot) && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
+    if (targetExists && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
     await mkdir(this.outputDir, { recursive: true });
     const stagingRoot = await mkdtemp(path.join(this.outputDir, `.${this.projectName}.staging-`));
     this.projectRoot = path.join(stagingRoot, this.projectName);
@@ -101,7 +124,11 @@ class ScaffoldGenerator {
       this.generateDatabaseScripts(); await this.generateDocumentation(); await this.writeGenerationManifest();
       await this.copyWrapperFiles(); await this.validateGeneratedArtifacts();
       let backupPath;
-      if (await exists(this.finalProjectRoot)) { backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`); await rename(this.finalProjectRoot, backupPath); }
+      if (await exists(this.finalProjectRoot)) {
+        this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+        backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`);
+        await rename(this.finalProjectRoot, backupPath);
+      }
       await rename(this.projectRoot, this.finalProjectRoot); this.projectRoot = this.finalProjectRoot;
       console.log(`\n✅ 项目生成完成!\n📂 项目位置: ${this.projectRoot}`);
       if (backupPath) console.log(`♻️ 原项目备份: ${backupPath}`);

package/template/.qoder/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -1,11 +1,14 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { run } from "./run_scaffold_verification.mjs";
+import { makeGitlinkFixture } from "../../../../scripts/lib/git-submodule-fixtures.mjs";
+import { GITLINK_MODE, gitLsFilesStage } from "../../../../scripts/lib/repository-scope-policy.mjs";
 
 const scripts = path.dirname(fileURLToPath(import.meta.url));
 const generator = path.join(scripts, "generate_scaffold.mjs");
@@ -21,6 +24,55 @@ test("拒绝不一致合同和未经明确批准的非空目录覆盖", async (t
 
 test("已批准的 --force 先备份非空目标，再提交 staging 工程", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const oldProject = path.join(data.output, "demo-service"); await mkdir(oldProject); await writeFile(path.join(oldProject, "old.txt"), "recoverable"); const result = await command([...data.args, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]); assert.equal(result.code, 0, result.stderr); const entries = await readdir(data.output); const backup = entries.find((entry) => entry.startsWith(".demo-service.backup-")); assert.ok(backup); assert.equal(await readFile(path.join(data.output, backup, "old.txt"), "utf8"), "recoverable"); assert.ok((await readdir(path.join(data.output, "demo-service"))).includes("pom.xml")); });
 
+test("拒绝覆盖 .gitmodules 登记的 git-submodule 挂载点", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const superproject = path.join(data.root, "harness");
+  const output = path.join(superproject, "apps/backend");
+  await mkdir(path.join(output, "demo-service"), { recursive: true });
+  await writeFile(path.join(superproject, ".gitmodules"), "[submodule \"demo-service\"]\n\tpath = apps/backend/demo-service\n\turl = https://example.invalid/demo-service.git\n");
+  const contractFile = path.join(data.root, "gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  assert.equal(result.code, 1, result.stderr);
+  assert.match(`${result.stdout}\n${result.stderr}`, /gitlink 不得由脚手架覆盖/);
+});
+
+test("拒绝在 detached HEAD 子仓工作树内当成普通目录生成", async (t) => {
+  const data = await fixture();
+  const detached = makeGitlinkFixture({ checkout: "detached-head" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => detached.cleanup());
+  const output = path.join(detached.superproject, detached.mount);
+  const contractFile = path.join(data.root, "detached-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "nested-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /detached HEAD 不得当成普通目录写入/);
+  assert.equal(existsSync(path.join(output, "nested-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("staging") || name === "nested-service"), false);
+});
+
+test("--force 覆盖真实 gitlink 不得走普通目录覆盖路径", async (t) => {
+  const data = await fixture();
+  const empty = makeGitlinkFixture({ checkout: "empty-gitlink" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => empty.cleanup());
+  const output = path.join(empty.superproject, "apps/backend");
+  const contractFile = path.join(data.root, "empty-gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "billing-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /--force 不得把 git-submodule 挂载点当成普通目录覆盖|gitlink 不得/);
+  assert.equal(existsSync(path.join(output, "billing-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("backup")), false);
+  assert.equal(gitLsFilesStage(empty.superproject, empty.mount)?.mode, GITLINK_MODE);
+});
+
 test("验证器记录三条 wrapper 命令的成功和失败证据", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\n[ \"$1\" = test ] && exit 2\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const evidence = path.join(root, "evidence"); const report = await run(project, evidence); assert.equal(report.status, "failed"); assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 2, 0]); assert.match(await readFile(path.join(evidence, "mvnw-test.stderr.log"), "utf8"), /^$/); });
 
 test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence")); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });

package/template/.qoder/skills/yss-frontend-scaffold-generator/SKILL.md

@@ -31,7 +31,7 @@ branch: template
 ## Workflow
 
 1. 确认当前任务已经通过 Harness 入口分诊，且实现位置已记录在 proposal、design、build entry review、实施计划或实现路由记录中。
-2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。
+2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。

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

@@ -78,7 +78,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 
 YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空或摘要变化时返回 `blocked`，不能缩小审查范围或合并不同候选的结论。
 
-Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
+Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 
 “然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
 

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

@@ -9,6 +9,10 @@ implementation_path_policy:
   forbidden_roots: [app/backend/, app/frontend/]
   container_roots_are_projects: false
   external_repository_uses_native_root: true
+  policies: [harness-apps-multi-project, external-repository-native, git-submodule-harness-apps]
+  git_submodule:
+    repository_scope: git-submodule
+    layout_policy: git-submodule-harness-apps
 
 review_verification:
   low_medium_combined_independent_executor: true
@@ -260,6 +264,26 @@ git_authorization:
     authorized_value: true
     non_empty: [push_scope, push_authorization_ref]
     unauthorized_action: checkpoint-only
+  git_submodule:
+    applies_when: repository_scope=git-submodule
+    forbid_commit_on_detached_head: true
+    commit_order: [submodule-repositories, superproject-gitlink]
+    push_order: [submodule-repositories, superproject-gitlink]
+    push_recurse_submodules: check
+    empty_gitlink_scaffold: blocked
+    treat_empty_gitlink_as_regular_dir: blocked
+    treat_detached_head_as_regular_dir: blocked
+    force_overlay_mount: blocked
+    write_inside_detached_head: blocked
+    require_git_entry_mode: "160000"
+    working_tree_declared_scope_must_match: true
+    copy_source_into_harness: forbidden
+    clone_requires_recurse_submodules: true
+    delivery_order_must_include: superproject-gitlink-update
+    nested_authorization: per-repository
+    inspect_working_tree_writable: explicit-boolean
+    empty_gitlink_writable: false
+    force_overlay_regular_dir_path: blocked
 
 seam_deferred_required: [risk, owner, follow_up_ticket, verification_plan, target_version_or_release_date]
 

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

@@ -69,6 +69,8 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 
 实现授权、`orchestrate`/`resume` 的有界写入、当前分支和 Git checkpoint 都不蕴含 commit 或 push 授权。执行 commit 前必须同时取得 `commit_authorized=true`、非空 `commit_scope` 和 `commit_authorization_ref`；执行 push 前必须同时取得 `push_authorized=true`、非空 `push_scope` 和 `push_authorization_ref`。任一缺失时只记录 checkpoint 判断并保持 Git 状态不变；负责人要求、时间压力、测试通过或“本地 commit 可逆”都不能补足用户授权。
 
+`repository_scope: git-submodule` 时授权按仓分别计算：禁止在 detached HEAD 提交；commit / push 顺序必须先子仓、再父仓 gitlink（`superproject-gitlink-update`）；父仓 push 使用 `git push --recurse-submodules=check`。空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录脚手架，也不得把实现源码复制进 Harness。登记字段必须能与 `harness-apps` / `external-repository` 区分，并对照工作树 gitlink。
+
 ## 必须暂停
 
 - Spec baseline、需求冻结、原型确认、OpenAPI Freeze 或 Architecture Review 等普通门禁等待人工裁决。

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

@@ -59,7 +59,7 @@ AND UI 影响切片的前端实现还原计划已通过 schema 校验、`templat
 
 进入代码审查时保存 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest` 及 Spec、Ticket、合同、Checklist、YSS Execution Result 引用。`worktree` 候选必须一次捕获 committed、staged、unstaged 和 untracked 文件；manifest 的按模式必填字段以及 `yss-worktree-candidate-v1`（raw path、uint64 big-endian 长度、tracked/untracked record、symlink 和不支持条目）以 `orchestration-contract.yaml.review_input` 为唯一执行定义。两个 Reviewer 消费同一不可变快照；返回后或完成 checkpoint 摘要变化则返回 `blocked` 并重新审查。不新增生命周期状态，只把该清单作为审查证据。
 
-Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。
+Git 动作分别保存 `commit_authorized`、`commit_scope`、`commit_authorization_ref`、`push_authorized`、`push_scope`、`push_authorization_ref`。只有授权值严格为 `true`、范围和用户授权引用均非空时才执行相应动作；缺失授权时保持工作区不变并记录 checkpoint 判断。`git-submodule` 另保存每仓授权、`checkout_state` 和先子后父顺序；空 gitlink、detached HEAD 或 `--force` 覆盖挂载点时不得当成普通目录 commit / 脚手架。
 
 ## 状态块
 

package/template/.qoder/skills/yss-router/SKILL.md

@@ -29,7 +29,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - Repository/数据模型影响缺少数据架构时，不得路由持久化实现。
 - API 变化必须回到生命周期 Draft/Review/Freeze；半成品 backend 不得冒充稳定 source of truth。
 - 后端端到端切片必须包含 Application；对象/POJO 影响按契约自动补 `mapstruct`、`lombok`、`alibaba-java-code-style`。
-- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。
+- Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
 - 原型确认后若 backend `scaffold_status=required`，先由本 Router 按 `scaffold_contract_schema` 编译 `yss-ddd-scaffold-generator` 的 `controlled-generation` 工作单元合同 draft；合同必须带 `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据和验证命令。经生命周期编排器批准并持久化后才能运行生成器，再由受控工作单元实际执行固定的 `./mvnw validate`、`./mvnw test`、`./mvnw package` 并记录逐条结果，随后加载 `yss-backend-scaffold-parent` 并重新编译业务合同；脚手架不承载业务行为。