create-yss-spec 2.1.0 → 2.1.1

package/template/.qoder/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""在生成项目根目录实际执行 YSS 脚手架的固定验证命令并留证。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List
+
+
+COMMANDS = ("validate", "test", "package")
+
+
+def iso_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def write_text(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8", errors="replace")
+
+
+def run(project_root: Path, evidence_dir: Path) -> Dict[str, object]:
+    wrapper = project_root / "mvnw"
+    if not wrapper.is_file():
+        raise FileNotFoundError(f"项目根目录缺少 Maven wrapper: {wrapper}")
+    manifest_path = project_root / ".yss" / "scaffold-generation.json"
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"项目根目录缺少脚手架生成元数据清单: {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    required_manifest_fields = [
+        "schema_version",
+        "contract_id",
+        "contract_version",
+        "slice_id",
+        "approval_ref",
+        "approver",
+        "lifecycle_approval_ref",
+        "router_draft_ref",
+        "persisted_ref",
+        "contract_file_ref",
+        "current_version",
+        "allowed_write_paths",
+        "expected_evidence_files",
+        "verification_commands",
+        "generation_mode",
+    ]
+    missing_manifest_fields = [
+        field for field in required_manifest_fields if manifest.get(field) in (None, "")
+    ]
+    if manifest.get("generation_mode") != "controlled-generation" or missing_manifest_fields:
+        raise ValueError(
+            "脚手架生成元数据清单不完整或不是 controlled-generation: "
+            + ", ".join(missing_manifest_fields)
+        )
+    if manifest["current_version"] != manifest["contract_version"]:
+        raise ValueError("脚手架生成元数据清单不是当前合同版本")
+    if manifest["verification_commands"] != [
+        "./mvnw validate",
+        "./mvnw test",
+        "./mvnw package",
+    ]:
+        raise ValueError("脚手架生成元数据清单验证命令不符合固定合同")
+
+    evidence_dir.mkdir(parents=True, exist_ok=True)
+    command_results: List[Dict[str, object]] = []
+    for phase in COMMANDS:
+        command = f"./mvnw {phase}"
+        stdout_path = evidence_dir / f"mvnw-{phase}.stdout.log"
+        stderr_path = evidence_dir / f"mvnw-{phase}.stderr.log"
+        started_at = iso_now()
+        started = time.monotonic()
+        try:
+            completed = subprocess.run(
+                [str(wrapper), phase],
+                cwd=project_root,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+            exit_code = completed.returncode
+            stdout = completed.stdout
+            stderr = completed.stderr
+        except OSError as exception:
+            exit_code = 127
+            stdout = ""
+            stderr = str(exception)
+        duration_ms = round((time.monotonic() - started) * 1000, 3)
+        write_text(stdout_path, stdout)
+        write_text(stderr_path, stderr)
+        command_results.append(
+            {
+                "command": command,
+                "phase": phase,
+                "exit_code": exit_code,
+                "duration_ms": duration_ms,
+                "started_at": started_at,
+                "executed_at": iso_now(),
+                "stdout_ref": str(stdout_path),
+                "stderr_ref": str(stderr_path),
+            }
+        )
+
+    return {
+        "verification_mode": "controlled-generation",
+        "project_root": str(project_root),
+        "scaffold_manifest_ref": str(manifest_path),
+        "generated_at": iso_now(),
+        "status": "passed" if all(item["exit_code"] == 0 for item in command_results) else "failed",
+        "commands": command_results,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="运行 YSS 脚手架真实验证命令")
+    parser.add_argument("--project-root", required=True, help="已生成后端项目的根目录")
+    parser.add_argument("--evidence-dir", required=True, help="验证日志和 JSON 报告目录")
+    args = parser.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    evidence_dir = Path(args.evidence_dir).resolve()
+    report_path = evidence_dir / "scaffold-verification.json"
+    try:
+        report = run(project_root, evidence_dir)
+    except Exception as exception:
+        report = {
+            "verification_mode": "controlled-generation",
+            "project_root": str(project_root),
+            "generated_at": iso_now(),
+            "status": "failed",
+            "error": str(exception),
+            "commands": [],
+        }
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(
+            json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+        )
+        print(f"❌ 脚手架验证无法执行: {exception}", file=sys.stderr)
+        return 1
+
+    report_path.write_text(
+        json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    print(f"{report['status']}: {report_path}")
+    return 0 if report["status"] == "passed" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -29,7 +29,7 @@ branch: template
 ## Workflow
 
 1. 确认当前任务已经通过 Harness 入口分诊，且实现位置已记录在 proposal、design、build entry review、实施计划或实现路由记录中。
-2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/`。
+2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。
@@ -56,6 +56,7 @@ packages/package.json
 - 不直接创建远端 Git 项目，除非用户明确要求。
 - 不推送、不创建 MR / PR，除非用户明确要求。
 - 不绕过 OpenAPI Draft / Freeze；API client 生成必须有可追溯 OpenAPI source。
+- 不得把 `apps/frontend/` 容器根登记为项目根；Harness 内每个前端项目必须有独立的 `apps/frontend/<project>/` 路径。
 - 不把模板示例页面当作业务功能交付。
 - 生成后仍需使用 `yss-page-module-development`、`yss-components`、`api-integration` 等专项 skill 实现业务页面。
 

package/template/.qoder/skills/yss-product-lifecycle/SKILL.md

@@ -39,6 +39,9 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - YSS active 调用 `to-spec` 时，必须把 Matt 独立 flow 的 `ready-for-agent` 发布提示归一化为 Spec `ready-for-human`；不得把 Spec 初稿当作可直接实现的 Ticket。
 - `orchestrate`/`resume` 连续执行安全工作单元，直到人工门禁、真实阻塞、新授权、实现/发布裁决或专项失败。
 - 进入实现后继续主控，通过 `yss-router`、`implement`、`tdd` 和 YSS 专项 skills 执行；独立审查和 fresh verification 后才能作完成判断。
+- 原型确认 → 后端脚手架：当 YSS 高保真原型已经完成 Prototype Review、AntD CLI 校验和用户确认，且 backend `scaffold_status=required` 时，先完成工程基线，由 `yss-router` 编译脚手架受控生成工作单元合同，经生命周期编排器批准并持久化后，才使用 `yss-ddd-scaffold-generator` 生成后端骨架；随后由 `yss-backend-scaffold-parent` 校验并重新进入 `yss-router`，不得先写业务代码。
+- 所有后续生成的后端代码都必须消费生命周期批准、已持久化且版本当前的 Slice Implementation Contract，绑定最小 YSS skill 闭包、允许写路径、证据文件和 YSS Skill Execution Result；没有这些证据时必须阻断。
+- Harness 内承载运行时代码时，项目路径策略固定为 `apps/backend/<project>/` 和 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅是项目容器，`app/backend/`、`app/frontend/` 及其子路径禁止生成。外部实现仓库不强制使用该目录，但必须登记真实项目根路径并写入合同。
 - Setup readiness 每个任务只评估一次并在本轮缓存；只有 tracker、主远端、真实标签或配置变化时重查。
 - Ticket tracker 支持 `local-markdown`、GitHub 和 GitLab；模板默认 `local-markdown`，以 `docs/.scratch/<feature>/` 完整功能包为主载体。Git remote 只代表代码托管，不能覆盖已持久化的 tracker 选择；Local 主 tracker 不要求远程 Ticket。根 `.scratch/` 与 `docs/requirements/tickets/` 只作为旧路径迁移来源。
 - 小改动和中等变更允许同一独立执行者完成 Review 与 fresh verification；该执行者不得是实现者。新模块、高风险或职责冲突时拆分 Reviewer 与 Verifier。
@@ -50,6 +53,31 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - Matt `prototype` 是保留在 `prototype/<name>` 分支的单文件可分享 HTML 主来源；YSS 高保真 HTML 原型仍必须经过 Prototype Review、AntD CLI 校验和用户确认，两者不得互相替代。
 - Matt skill 返回结果必须先归一化为 `Matt Skill Result`；`drift`、`new_impacts`、`violation`、`stale_candidates`、缺失证据或不完整结果不得推进为 `completed`。
 
+### 原型完成后的后端脚手架与代码生成边界
+
+`prototype_confirmation` 是产品设计门禁，不是业务实现授权。后端新工程的顺序固定为：工程基线 → `yss-router` 编译脚手架合同 draft → 生命周期批准/持久化 → `yss-ddd-scaffold-generator` → `yss-backend-scaffold-parent` → `yss-router` 合同重编译 → 垂直切片实现。
+
+- `scaffold_status=required` 时，脚手架工作单元使用 `controlled-generation`，记录项目名、基础包名、输出目录、数据库类型、预期文件和实际 `./mvnw validate`、`./mvnw test`、`./mvnw package` 结果，并返回 YSS Skill Execution Result。
+- 脚手架合同必须结构化记录 `contract_id`、`contract_version`、`slice_id`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、实现仓库、允许写路径、预期证据文件和验证命令；生命周期批准记录至少包含 `approval_ref`、`approver`、`persisted_ref`、`current_version`。
+- `yss-ddd-scaffold-generator` 必须读取已持久化的结构化脚手架合同 JSON，并校验 `status=approved`、当前版本、主 skill、`controlled-generation` 和固定验证命令；只传任意字符串引用不得放行。
+- 生成项目必须包含 `.yss/scaffold-generation.json`，回勾实际使用的合同 ID、版本、Router draft 引用、生命周期批准引用、持久化引用、生成输入、受控模式和固定验证命令；元数据清单缺失或过期时阻断后续 Router。
+- 三条 `./mvnw` 命令必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的命令、输出目录存在或“生成成功”都不构成验证证据。
+- 脚手架只生成多模块工程结构、POM、配置、Wrapper、Smart Doc 和经验证的机械模板；不得生成或承载领域规则、状态机、权限、事务、复杂查询、错误映射或用户可见业务行为。
+- 该生命周期脚手架工作单元必须关闭 `--with-example`，不得把 User CRUD 或业务字段伪装成样板；目标目录非空时 `--force` 默认阻断，只有覆盖范围、备份、回滚点和明确批准全部进入合同后才能另行审查。
+- `scaffold_status=existing` 或 `initialized` 时不重复全量生成，但仍须完成 `yss-backend-scaffold-parent` 基线证据、Wrapper 校验和 `yss-router` 合同重编译。
+- 脚手架完成不等于实现仓库接入、架构放行、契约批准或 `ready-for-agent`。后续每一个 Agent / generator 写入的后端代码都必须绑定批准合同和对应 YSS skill；业务行为只能使用 `behavior-tdd`，机械生成才可使用 `controlled-generation`。
+
+| 压力诱因 | 统一裁决 |
+|---|---|
+| “脚手架本来就是 YSS，先生成代码再补合同” | 先阻断；Router draft 不能批准合同或替代生命周期放行。 |
+| “`./mvnw validate` 已通过，直接继续最省时间” | 只证明工程基线可验证，不证明业务、权限、事务或契约已获批；三条实际命令的结果还必须进入 Execution Result。 |
+| “后续代码也是生成物，不需要重新路由” | 只要写入业务代码，就必须重新消费当前 Slice Implementation Contract 和 YSS skill 闭包。 |
+| “发布窗口快结束了，可以把业务字段放进脚手架” | 时间、上级要求、已有产出和演示压力都不能放宽禁止模式；必须拆为 `behavior-tdd` 工作单元。 |
+
+**红旗：** 输出目录存在、脚手架成功、只打印了 `./mvnw` 命令、`validate` 通过、Router 只有 draft、或生成器参数中出现业务字段 / 权限 / 事务 / 状态机，均不足以继续业务实现；命中任一项即暂停并重路由。
+
+**项目路径策略：** 在 Harness 内生成项目时，先确认目标属于 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；把 `apps/backend/`、`apps/frontend/` 当作项目根，或把单数 `app/backend/`、`app/frontend/` 当作等价路径，均属于路径违规并阻断。
+
 状态和依赖规则见 [state-model.md](references/state-model.md) 与 [artifact-dependencies.md](references/artifact-dependencies.md)；Matt/YSS 对应见 [matt-yss-adapter.md](references/matt-yss-adapter.md)。
 机器可执行的模式、readiness、Wayfinder、影响传播和回流字段见 [orchestration-contract.yaml](references/orchestration-contract.yaml)。说明文档与该契约冲突时必须暂停并修订权威资产，不得猜测。
 

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

@@ -1,6 +1,15 @@
 schema_version: 1
 supported_state_schema_versions: [1]
 
+implementation_path_policy:
+  harness_layout:
+    backend: apps/backend/<project>/
+    frontend: apps/frontend/<project>/
+  container_roots: [apps/backend/, apps/frontend/]
+  forbidden_roots: [app/backend/, app/frontend/]
+  container_roots_are_projects: false
+  external_repository_uses_native_root: true
+
 review_verification:
   low_medium_combined_independent_executor: true
   implementer_must_be_separate: true
@@ -60,9 +69,68 @@ flow_preconditions:
     required: [openapi_freeze_or_no_api_impact, required_gates_satisfied, vertical_slice_scope, blocking_edges]
     output: vertical-slice-tickets
   implement:
-    required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable]
+    required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied]
     applies_to_single_session: true
 
+backend_scaffold:
+  applies_when: [backend_impact]
+  scaffold_statuses: [existing, required, initialized]
+  required_status: required
+  sequence:
+    after: [prototype_confirmation, engineering_baseline]
+    before_generator: [yss-router-scaffold-contract, lifecycle-approve-scaffold-contract]
+    before: [business_code_generation, implement]
+  generator_skill: yss-ddd-scaffold-generator
+  baseline_skill: yss-backend-scaffold-parent
+  tdd_mode: controlled-generation
+  contract_schema:
+    schema_version: 1
+    required: [contract_id, contract_version, slice_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, target_git_url_or_output_dir, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, overwrite_policy]
+    status_by_owner:
+      router: [draft, ready-for-lifecycle-review, blocked]
+      lifecycle: [approved, stale, blocked]
+    approval:
+      required: [approval_ref, approver, persisted_ref, current_version]
+    overwrite_policy:
+      required: [force_allowed, overwrite_scope, rollback_ref]
+  required_inputs: [implementation_repository, backend_repository, scaffold_status, scaffold_target_confirmed, target_git_url_or_output_dir, project_name, base_package, database, scaffold_contract_file, scaffold_contract_draft, scaffold_contract_id, scaffold_contract_version, scaffold_contract_status, scaffold_contract_approved, scaffold_contract_router_draft_ref, scaffold_contract_lifecycle_approval_ref, scaffold_contract_persisted, scaffold_contract_persisted_ref, scaffold_contract_current_version]
+  required_evidence: [generator_inputs, expected_files, scaffold_generation_manifest, generated_project_structure, generation_execution_result, verification_execution_result, ./mvnw_validate, ./mvnw_test, ./mvnw_package, yss_skill_execution_result]
+  generation_options:
+    with_example: false
+    force: forbidden-by-default
+    force_requires: [contract_file, contract_id, contract_version, approval_ref, router_draft_ref, persisted_ref, overwrite_scope, rollback_ref]
+  forbidden_generation: [business_rules, state_machine, permission, transaction, complex_query, error_mapping, user_visible_behavior, business_example_crud, unapproved_force_overwrite]
+  after_generation: [yss-backend-scaffold-parent, yss-router]
+  existing_or_initialized: [baseline_evidence, wrapper_verification, yss_router_contract_recompile]
+  verification:
+    commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
+    requires_execution: true
+    printed_commands_are_not_evidence: true
+    evidence: [command, exit_code, duration_ms, stdout_ref, stderr_ref, executed_at]
+    failure_action: blocked
+  failure_action: blocked
+
+scaffold_work_unit_policy:
+  applies_to: [scaffold_generator_output]
+  scope: pre_business_code_generation
+  required: [approved_scaffold_contract, primary_yss_skill, allowed_write_paths, expected_evidence_files, verification_commands]
+  controlled_generation:
+    allowed_for: [project_scaffold, pom, mechanical_config, wrapper, smart_doc_baseline]
+    forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+  on_violation: blocked
+
+post_scaffold_generated_code_policy:
+  applies_to: [post_scaffold_backend_code]
+  scope: post_scaffold_generated_code
+  required: [approved_persisted_current_slice_contract, primary_yss_skill, dependency_closure, allowed_write_paths, expected_evidence_files, yss_skill_execution_result]
+  business_behavior:
+    tdd_mode: behavior-tdd
+    impacts: [domain-rule, state-machine, transaction, permission, complex-query, error-mapping, user-visible-behavior]
+  controlled_generation:
+    allowed_for: [dto_boilerplate, po_boilerplate, mapstruct_generated, frozen_openapi_client, mechanical_config]
+    forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+  on_violation: blocked
+
 tracker:
   allowed_platforms: [local-markdown, github, gitlab]
   default_platform: local-markdown
@@ -108,7 +176,7 @@ wayfinder_completion:
   required: [no_open_children, no_open_blocked_or_claimed_children, no_fog, destination_clear]
 
 ready_for_agent:
-  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable]
+  required: [gates_satisfied, no_stale_artifacts, blockers_closed, implementation_context_ready, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied]
 
 unknown_impact:
   action: pause

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

@@ -25,6 +25,14 @@ Matt phase boundary 是工作阶段之间的上下文决策，不是新的生命
 
 在 checkpoint 记录 `phase_boundary.decision`；使用 `handoff`、subagent 或 `compact` 时同时记录契约要求的引用。phase boundary 不得改变生命周期阶段、门禁或 Ticket 五态。
 
+## 原型到后端脚手架的接力
+
+`prototype_confirmation` 通过后，先判断实现仓库登记中的 backend `scaffold_status`。当状态为 `required` 时，先完成工程基线，由 `yss-router` 编译脚手架 `controlled-generation` 工作单元合同，生命周期编排器批准并持久化后才能运行生成器；顺序为：工程基线 → Router 脚手架合同 draft → 生命周期批准/持久化 → 脚手架生成 → `yss-backend-scaffold-parent` 基线校验 → Router 合同重编译。`existing` / `initialized` 不重复全量生成，但不能跳过基线校验和 Router 重编译。
+
+脚手架工作单元必须使用结构化合同 JSON 文件，至少记录 `contract_id`、`contract_version`、`slice_id`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；批准记录至少含 `approval_ref`、`approver`、`persisted_ref`、`current_version`。生成器必须读取该合同文件并校验状态、版本、skill、工作模式和固定命令，不能只接受任意字符串参数。它还必须记录生成器输入、预期文件、目标目录、实际 `./mvnw validate` / `./mvnw test` / `./mvnw package` 结果和 YSS Skill Execution Result。三条命令必须由受控工作单元真实执行，逐条留存 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；生成器打印的下一步命令不构成证据。生命周期生成关闭 `--with-example`；非空目标目录使用 `--force` 默认阻断，除非覆盖范围、备份、回滚点和批准引用已进入合同。脚手架不得把业务规则、状态机、权限、事务、复杂查询、错误映射或用户可见行为放进生成物；`validate` 通过、输出目录存在或生成器成功都不是生命周期批准、架构放行或 `ready-for-agent`。
+
+脚手架完成后，所有后续生成的后端代码仍必须重新消费当前版本的批准 Slice Implementation Contract、YSS skill 依赖闭包、允许写路径、预期证据和 Execution Result。业务行为使用 `behavior-tdd`；只有机械结构、样板、配置和冻结客户端使用 `controlled-generation`。缺少合同、skill、证据或实际验证时立即阻断；生成范围从机械内容变成业务行为时触发完整重路由。
+
 ## Setup readiness
 
 Readiness 结果在同一任务内复用。只有 tracker、主远端、真实标签或配置发生变化，才重新执行检查；不得把 `setup-matt-pocock-skills` 当作每阶段或每工作单元的固定动作。
@@ -46,6 +54,7 @@ tracker 选择和冲突按 `docs/agents/issue-tracker.md` 裁决：已持久化
 - `to-spec` 只能在 `grill-with-docs` 退出条件满足且没有未回流 runnable blocker 时进入；产物默认为 `ready-for-human`。
 - `to-tickets` 只能在 OpenAPI Freeze 或无 API 影响记录完成后进入，并且只能生成垂直切片 Ticket。
 - `implement` 无论是多会话还是单会话，都必须满足 `ready-for-agent` 公式、批准并持久化的 Slice Implementation Contract 和 Build Architecture Checklist。
+- `implement` 遇到 backend `scaffold_status=required` 时，还必须满足原型确认后的脚手架策略：脚手架 Execution Result、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 合同重编译均已回写；否则停在工程基线，不得写业务代码。
 - Matt Result 出现 `drift`、`new_impacts`、`stale_candidates`、`violation`、`missing_evidence`、空 `evidence_refs` 或缺少必需字段时暂停当前工作单元。
 
 ## 审查与验证

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

@@ -44,6 +44,8 @@ AND implementation repo/branch/CI/test/rollback 已明确
 AND Slice Implementation Contract 已由生命周期编排器批准并持久化
 AND 当前工作单元消费的 contract_id/version 与最新批准版本一致
 AND Backend Slice Implementation Contract（后端适用）和 Build Architecture Checklist 已完成
+AND backend 影响且 scaffold_status=required 时，原型确认后的脚手架策略、`yss-backend-scaffold-parent` 基线、Wrapper 验证和 Router 重编译均已完成
+AND 所有后续生成代码均绑定主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result
 ```
 
 父 Ticket、Spec、设计、原型、OpenAPI Draft、wayfinder map 和 decision ticket 不得使用 `ready-for-agent`。

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

@@ -29,8 +29,12 @@ 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/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。
 - 当前用户、审计事件、普通技术日志、请求校验、错误映射或加解密命中时，必须按 `router-contract.yaml` 的 `component_impact_routing` 补齐长尾 skill；不能只在 `boundaries.md` 中提及。
 - 业务行为使用 `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` 并重新编译业务合同；脚手架不承载业务行为。
+- 脚手架合同在 Router 阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和 Router 重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
+- 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。
 - 专项结果中的越界路径、缺失证据、`drift`、`violation` 或 `new_impacts` 必须阻断或重路由。
 - 长尾 skill 不可用时显式 `blocked`，不得用通用知识假装已应用 YSS 规范。
 

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

@@ -1,6 +1,21 @@
 schema_version: 1
 allowed_statuses: [draft, blocked, ready-for-lifecycle-review]
 forbidden_statuses: [approved, ready-for-agent, completed]
+implementation_path_policy:
+  applies_to: harness-resident-runtime-code
+  project_roots:
+    backend: apps/backend/<project>/
+    frontend: apps/frontend/<project>/
+  container_roots:
+    - apps/backend/
+    - apps/frontend/
+  forbidden_roots:
+    - app/backend/
+    - app/frontend/
+  rules:
+    - "Harness 内每个运行时工程必须位于具体 project 目录，不能直接写入 apps/backend/ 或 apps/frontend/。"
+    - "app/backend/、app/frontend/ 及其子路径不是兼容别名，必须阻断。"
+    - "外部实现仓库使用登记的真实项目根路径，不用 Harness 容器路径冒充。"
 subcontract_statuses: [required, not-applicable]
 
 readiness:
@@ -26,7 +41,7 @@ slice_contract_required:
   root: [schema_version, contract_id, contract_version, slice_id, status, lifecycle_refs, readiness, common, frontend, backend, contract, cross_repo, work_units]
   lifecycle_refs: [spec, ticket, requirement_freeze, low_fidelity_review, high_fidelity_html, antd_cli_evidence, prototype_confirmation, openapi_freeze_or_no_impact, architecture_review, data_architecture, engineering_baseline, build_architecture_checklist, implementation_repository, frontend_repository, backend_repository, maven_wrapper]
   readiness: [blockers, stale_inputs, not_applicable]
-  common: [impacted_areas, required_skills, optional_skills, unavailable_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, human_review_points, full_reroute_triggers]
+  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, optional_skills, unavailable_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, human_review_points, full_reroute_triggers]
   frontend: [status, required_skills, approved_prototype_ref, state_matrix_ref, allowed_write_paths, component_test_seams, e2e_paths]
   backend: [status, affected_layers, component_impacts, required_skills, application_boundary, transaction_boundary, persistence_strategy, allowed_write_paths, forbidden_patterns, expected_evidence_files, seam_deferred, verification_commands]
   contract: [api_impact, freeze_ref, no_api_impact_ref, generated_clients, contract_tests, regeneration_commands]
@@ -54,7 +69,34 @@ work_unit_required: [id, behavior, primary_skill, supporting_skills, tdd_mode, a
 work_unit_nonempty_arrays: [allowed_write_paths, expected_evidence, verification_commands]
 slice_contract_nonempty: [contract_id, contract_version, slice_id, status]
 slice_contract_array_fields:
-  common: [impacted_areas, required_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, full_reroute_triggers]
+  common: [impacted_areas, implementation_path_policy, project_roots, required_skills, allowed_write_paths, forbidden_patterns, expected_evidence_files, verification_commands, full_reroute_triggers]
+
+scaffold_contract_schema:
+  schema_version: 1
+  compiled_by: yss-router
+  approved_by: yss-product-lifecycle
+  status_by_owner:
+    router: [draft, ready-for-lifecycle-review, blocked]
+    lifecycle: [approved, stale, blocked]
+  required: [contract_id, contract_version, slice_id, status, router_draft_ref, lifecycle_approval_ref, persisted_ref, current_version, implementation_repository, backend_repository, scaffold_status, target_git_url_or_output_dir, allowed_write_paths, expected_evidence_files, verification_commands, approval, work_unit, overwrite_policy]
+  approval:
+    required: [approval_ref, approver, persisted_ref, current_version]
+  overwrite_policy:
+    required: [force_allowed, overwrite_scope, rollback_ref]
+  lifecycle_boundary:
+    router_emits: [draft, ready-for-lifecycle-review, blocked]
+    lifecycle_approves: [approved]
+    generator_consumes: [approved]
+    after_generation: [yss-backend-scaffold-parent, yss-router-business-contract-recompile]
+  work_unit:
+    required: [id, behavior, primary_skill, supporting_skills, tdd_mode, allowed_write_paths, expected_evidence, verification_commands, controlled_generation]
+  generation_boundary:
+    allowed_for: [project_scaffold, pom, mechanical_config, wrapper, smart_doc_baseline]
+    forbidden_when: [business_behavior, business_fields, business_state, permission, transaction, complex_query, error_mapping, business_example_crud]
+  verification:
+    commands: ["./mvnw validate", "./mvnw test", "./mvnw package"]
+    requires_execution: true
+    evidence: [command, exit_code, duration_ms, stdout_ref, stderr_ref, executed_at]
 
 applicable_subcontract_nonempty:
   frontend:
@@ -72,6 +114,8 @@ applicable_subcontract_nonempty:
     array: [repositories, delivery_order, integration_verification, rollback_order]
 
 dependency_closure:
+  yss-ddd-scaffold-generator:
+    always: [yss-backend-scaffold-parent, alibaba-java-code-style]
   yss-domain:
     always: [yss-backend-scaffold-domain, alibaba-java-code-style]
     when_modeling: [domain-modeling]
@@ -144,6 +188,7 @@ tdd_modes:
     required: [exception_reason, generator, generator_inputs, expected_files, verification_commands, behavior_tests_after_generation]
 
 full_reroute_triggers:
+  - scaffold-baseline-drift
   - api-schema-impact
   - database-schema-impact
   - permission-impact
@@ -161,6 +206,7 @@ full_reroute_triggers:
   - delivery-order-changed
 
 reroute_destinations:
+  scaffold-baseline-drift: stage7-scaffold-revalidation
   api-schema-impact: system-data-architecture-and-contract-review
   database-schema-impact: data-architecture-and-migration-review
   permission-impact: spec-product-design-and-contract-review

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

@@ -34,6 +34,8 @@ slice_contract:
         reason:
   common:
     impacted_areas: []
+    implementation_path_policy: harness-apps-multi-project # or external-repository-native
+    project_roots: []
     required_skills: []
     optional_skills: []
     unavailable_skills:

package/template/.qoder/skills/yss-router/references/yss-skill-execution-result.md

@@ -58,4 +58,4 @@ Router 必须验证：
 
 专项 skill 自报 `implemented` 不等于最终通过，生命周期编排器和独立 Reviewer 必须复核。
 
-`verification_results` 不得为空，每项必须包含非空 `command`、`result` 和 `executed_at`。路径校验按完整目录边界判断，`apps/backend/order-escape` 不属于 `apps/backend/order/`。完整重路由时旧合同必须标记 `stale`，新合同版本递增并保留旧合同引用、失效原因和触发器。
+`verification_results` 不得为空，每项必须包含非空 `command`、`result` 和 `executed_at`。路径校验按完整目录边界判断，`apps/backend/project1-escape` 不属于 `apps/backend/project1/`；Harness 内路径还必须通过项目路径策略。完整重路由时旧合同必须标记 `stale`，新合同版本递增并保留旧合同引用、失效原因和触发器。

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

@@ -19,9 +19,10 @@ 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 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。
-5. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
-6. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
+4. 核对项目根路径：Harness 内项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。外部仓库记录各自的真实项目根。
+5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。
+6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
+7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
 
 ## Routing Matrix
 

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

@@ -20,8 +20,9 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
 3. 如果输入是远端 URL，优先使用只读 Git 查询；需要 clone 时只能 clone 到临时目录，不能 clone 到 Harness 仓库内。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
-5. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
-6. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
+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 的信息。
 
 ## Baseline Checks
 
@@ -37,6 +38,7 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 - 不直接提交、推送、创建 MR / PR 或修改实现仓库。
 - 不把实现仓库源码复制进 Harness 仓库。
 - 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
+- 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
 - 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。
 
 ## Output

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

@@ -24,11 +24,14 @@ description: 用于生成完整的 YSS DDD 多模块后端脚手架。当用户
 ## 优先流程
 
 1. 确认项目名、基础包名、输出目录、数据库类型。
+   Harness 内输出目录必须是 `apps/backend/` 容器，生成器再以 `project_name` 创建 `apps/backend/<project>/`；禁止使用 `app/backend/`、`app/frontend/` 或把 `apps/backend/` 之外的容器根当作后端项目根。
 2. 运行 `scripts/generate_scaffold.py` 生成骨架。
 3. 检查生成的模块名、POM、配置文件、Smart Doc 配置和包路径。
-4. 使用 `./mvnw` 执行 `validate`、测试和打包验证。
+4. 由生命周期受控工作单元在生成项目根目录实际执行 `./mvnw validate`、`./mvnw test` 和 `./mvnw package`；生成器打印的下一步命令不构成验证证据。
 5. 如需继续细化，再追加其他 YSS skill 补全领域、仓储和 Web。
 
+受控验证命令由本 skill 的 `scripts/run_scaffold_verification.py` 固定执行；验证器先检查 `.yss/scaffold-generation.json` 的合同元数据，再在指定 evidence 目录写入每条命令的 stdout/stderr、`exit_code`、耗时、执行时间和 `scaffold-verification.json`；任何一条命令失败或未执行都必须阻断。
+
 ## 推荐命令
 
 ```bash
@@ -36,7 +39,13 @@ python3 scripts/generate_scaffold.py \
   --project-name my-service \
   --base-package com.yss.myservice \
   --output-dir /path/to/implementation-repo \
-  --database mysql
+  --database mysql \
+  --contract-id <approved-scaffold-contract-id> \
+  --contract-version <current-version> \
+  --approval-ref <lifecycle-approval-ref> \
+  --router-draft-ref <router-draft-ref> \
+  --persisted-ref <persisted-contract-ref> \
+  --contract-file /path/to/persisted-scaffold-contract.json
 ```
 
 ## 生成结果应包含
@@ -47,20 +56,28 @@ python3 scripts/generate_scaffold.py \
 - `*-infrastructure`
 - `*-adapter`
 - `*-bootstrap`
-- 基础配置、模板代码、构建脚本
+- 基础配置、机械模板、构建脚本
 - `bootstrap/src/main/resources/smart-doc.json` 基础配置
 
 ## 使用约束
 
-- 先生成骨架，再做业务化定制，不要直接把脚手架当最终代码交付。
-- 默认不生成 `User CRUD` 示例；只有显式传入 `--with-example` 时才生成。
+- 先在生命周期批准的脚手架受控生成合同下生成骨架，再做业务化定制；不要直接把脚手架当最终代码交付。
+- 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若仓库已经存在相同工程，先核对覆盖范围。
 - 输出目录必须显式指定；非空目录默认拒绝写入，确认覆盖时才使用 `--force`。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等局部技能。
 - 当前脚手架第一阶段仅支持经过验证的 `mysql`；未提供完整模板和验证的数据库类型不得伪装成已支持。
 - 生成后的后端工程必须使用项目根目录 `./mvnw ...` 执行构建、测试、运行、OpenAPI 生成和 CI 验证；不得在 README、实施记录、Ticket、Review 或 Release 中默认写裸 `mvn ...`。既有仓库确实无法使用 wrapper 时，必须记录受控例外。
+- 原型确认后，`scaffold_status=required` 才能进入本 skill；本 skill 的生成边界是工程结构、POM、配置、Wrapper、Smart Doc 和机械模板，不是业务实现。
+- 脚手架合同必须携带 `contract_id`、`contract_version`、Router draft 引用、生命周期批准引用、持久化引用、当前版本、允许写路径、预期证据文件和验证命令；字段缺失或版本过期时阻断。
+- 运行生成器必须传入 `--contract-file`；生成器会校验合同 `status=approved`、`current_version`、`primary_skill`、`controlled-generation` 和固定三条验证命令，不接受仅凭任意字符串引用的放行。
+- 生成项目必须写入非业务元数据清单 `.yss/scaffold-generation.json`，回勾合同 ID、版本、批准引用、生成输入、受控模式和固定验证命令；清单缺失时不得交给后续 Router。
+- 严禁把领域规则、状态机、权限、事务、复杂查询、错误映射、业务字段或用户可见行为塞进脚手架生成步骤。`./mvnw validate`、输出目录存在或“生成成功”都不等于生命周期批准、架构放行或 `ready-for-agent`。
+- 生命周期脚手架生成必须关闭 `--with-example`，不得把 User CRUD 或业务字段当作样板；非空目标目录使用 `--force` 默认禁止，除非覆盖范围、备份、回滚点和批准引用已经进入当前合同。
+- 脚手架完成后，所有后续生成的后端代码必须回到 `yss-router`，消费批准且版本当前的 Slice Implementation Contract 和对应 YSS skill；业务行为使用 `behavior-tdd`，机械生成才使用 `controlled-generation`。
 - `.mvn/settings.xml` 只能通过 `${env.MAVEN_REPO_USERNAME}` 和 `${env.MAVEN_REPO_PASSWORD}` 读取 Maven 仓库凭据；内部仓库构建前由 CI 或本地安全环境注入变量，禁止把 Maven 仓库用户名、明文密码或 Maven 加密密码写入 skill、模板或生成工程。
 - 涉及 API 契约时，先确认 `docs/.scratch/<feature>/api/<feature>.yaml` 中的 OpenAPI Draft / Freeze 状态；不要用脚手架生成结果反向替代产品契约设计。
 
@@ -80,6 +97,7 @@ python3 scripts/generate_scaffold.py \
 ## 按需读取
 
 - 主脚本：`scripts/generate_scaffold.py`
+- 受控验证器：`scripts/run_scaffold_verification.py`
 - 模板目录：`assets/templates/`
 - 分层细化参考：`references/yss-backend-scaffold-parent/` 及其子 skill
 
@@ -87,4 +105,6 @@ python3 scripts/generate_scaffold.py \
 
 - 仅在实现仓库/输出目录、`scaffold_status=required` 和批准合同明确时运行。
 - 工程骨架属于 `controlled-generation`，必须记录生成器输入、预期文件和 `./mvnw ...` 编译/测试结果；不得将业务状态机、权限、事务或查询逻辑混入生成步骤。
+- 生成结果必须包含 `.yss/scaffold-generation.json`，并由验证器回勾该清单；清单与批准合同不一致时阻断。
+- `./mvnw validate`、`./mvnw test`、`./mvnw package` 必须由受控工作单元真实执行，并记录每条命令的 `exit_code`、耗时、stdout/stderr 引用和执行时间；只列命令计划、生成器成功或打印输出均视为缺失证据并阻断。
 - 生成后按统一 `YSS Skill Execution Result` 返回 changed/evidence files、实际验证结果和新增影响，再由 Router 为业务工作单元重新路由。

package/template/.trae/skills/yss-ddd-scaffold-generator/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS DDD Scaffold"
   short_description: "生成多模块 YSS DDD 后端脚手架与工程骨架规范"
-  default_prompt: "Use $yss-ddd-scaffold-generator to create a standard YSS DDD backend scaffold with domain, application, infrastructure, adapter, and bootstrap modules."
+  default_prompt: "Use $yss-ddd-scaffold-generator only with a lifecycle-approved scaffold contract JSON to create a pure YSS DDD backend skeleton with domain, application, infrastructure, adapter, and bootstrap module boundaries; route all business code back through yss-router and the applicable YSS skills."