create-yss-spec 3.2.0 → 3.3.0

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

@@ -110,6 +110,9 @@ evidence:
   - id: evidence.fresh-verification
     name: Fresh Verification 记录
     description: 本轮实际执行的验证命令、结果和时间。
+  - id: evidence.implementation-repository-preparation
+    name: 实现仓库准备证据
+    description: 按项目记录交付面、已有仓库接入或新脚手架合同、生成清单、实际验证结果、仓库位置、Git 边界和当前版本。
   - id: evidence.checkpoint-and-rollback
     name: Checkpoint 与回滚点
     description: 可追溯的变更边界、发布记录和恢复动作。
@@ -183,6 +186,12 @@ gates:
     stage: stage.system-data-engineering
     trigger: 高风险或跨边界变化。
     evidence: [evidence.design-review-result]
+  - id: gate.implementation-repositories-ready
+    name: 实现仓库准备就绪
+    stage: stage.system-data-engineering
+    trigger: 后端或前端交付面进入 Ticket 正式化；未命中的交付面须记录带原因的 not-applicable。
+    evidence: [evidence.implementation-repository-preparation, evidence.fresh-verification]
+    requires_gates: [gate.engineering-baseline-accepted]
   - id: gate.slice-contract-approved
     name: Slice Implementation Contract 批准
     stage: stage.ticket-formalization
@@ -285,6 +294,14 @@ artifacts:
     name: 技术设计合同
     stage: stage.system-data-engineering
     trigger: 后端技术设计需要按已确认 DDD 或 MVC 架构明确行为、分层、一致性或数据映射。
+  - id: artifact.project-scaffold-contract
+    name: Project Scaffold Contract
+    stage: stage.system-data-engineering
+    trigger: 命中的前端或后端交付面选择初始化新工程。
+  - id: artifact.implementation-repository-preparation-result
+    name: 实现仓库准备结果
+    stage: stage.system-data-engineering
+    trigger: 后端或前端交付面进入 Ticket 正式化。
   - id: artifact.tactical-design
     name: DDD 战术设计
     stage: stage.system-data-engineering
@@ -415,6 +432,12 @@ work_units:
     input: Spec、原型、API/数据/工程影响面。
     output: OpenAPI、数据架构、按确认架构形成的 DDD / MVC 技术设计合同、工程基线、架构审查和 Slice 合同草案。
     completion: 命中契约已冻结；无 API 影响有可读记录；命中技术设计影响时架构已确认、规则与场景承接无未解释冲突；工程基线通过。
+  - id: work-unit.implementation-repository-preparation
+    name: 实现仓库准备
+    scope: project-instance
+    input: 工程影响面、工程基线、逐项目用户决定、实现仓库位置；新建工程还需批准且当前的 Project Scaffold Contract。
+    output: 已有工程的 Repository Onboarding Result，或新工程的 Scaffold Manifest 与 Scaffold Verification；并汇总 Implementation Repository Preparation Result。
+    completion: 每个命中的交付面均为 existing-and-onboarded 或 initialized-and-verified，未命中的交付面有带原因的 not-applicable；聚合结果当前且证据可读。
   - id: work-unit.service-project-initialization
     name: 独立服务项目初始化
     scope: project-instance

package/template/docs/process/schemas/implementation-repository-preparation-result.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.example/schemas/implementation-repository-preparation-result.schema.json",
+  "title": "Implementation Repository Preparation Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "kind", "result", "current_version", "projects", "evidence_refs"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "kind": { "const": "implementation-repository-preparation-result" },
+    "result": { "const": "completed" },
+    "current_version": { "const": true },
+    "projects": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "required": ["project_id", "delivery_role", "status"],
+        "properties": {
+          "project_id": { "type": "string", "minLength": 1 },
+          "delivery_role": { "enum": ["backend", "frontend"] },
+          "status": { "enum": ["existing-and-onboarded", "initialized-and-verified", "not-applicable"] },
+          "reason": { "type": "string" },
+          "repository_ref": { "type": "string" },
+          "project_root": { "type": "string" },
+          "repository_scope": { "enum": ["external-repository", "harness-apps", "git-submodule"] },
+          "onboarding_result": { "type": "object" },
+          "scaffold_contract": { "type": "object" },
+          "scaffold_manifest_ref": { "type": "string" },
+          "scaffold_verification": { "type": "object" },
+          "template_available": { "type": "boolean" },
+          "architecture_family": { "type": "string" }
+        }
+      }
+    },
+    "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+  }
+}

package/template/docs/process/schemas/project-scaffold-contract.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.example/schemas/project-scaffold-contract.schema.json",
+  "title": "YSS Project Scaffold Contract v4",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "kind", "contract_id", "contract_version", "status", "persisted_ref", "current_version", "delivery_role", "scaffold_kind", "generator_skill", "implementation_repository", "target_output_dir", "repository_scope", "init_git", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "generation_policy"],
+  "properties": {
+    "schema_version": { "const": 4 },
+    "kind": { "const": "project-scaffold-contract" },
+    "contract_id": { "type": "string", "minLength": 1 },
+    "contract_version": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "integer", "minimum": 1 }] },
+    "scaffold_request_id": { "type": "string", "minLength": 1 },
+    "compiler_draft_ref": { "type": "string", "minLength": 1 },
+    "lifecycle_approval_ref": { "type": "string", "minLength": 1 },
+    "status": { "const": "approved" },
+    "persisted_ref": { "type": "string", "minLength": 1 },
+    "current_version": { "const": true },
+    "delivery_role": { "enum": ["backend", "frontend"] },
+    "scaffold_kind": { "enum": ["backend-ddd", "backend-layered-mvc", "frontend-yss-vue3"] },
+    "generator_skill": { "enum": ["yss-ddd-scaffold-generator", "yss-layered-mvc-scaffold-generator", "yss-frontend-scaffold-generator"] },
+    "implementation_repository": { "type": "string", "minLength": 1 },
+    "backend_repository": { "type": "string", "minLength": 1 },
+    "scaffold_status": { "const": "required" },
+    "target_output_dir": { "type": "string", "minLength": 1 },
+    "repository_scope": { "enum": ["external-repository", "harness-apps", "git-submodule"] },
+    "init_git": { "type": "boolean" },
+    "project_name": { "type": "string", "minLength": 1 },
+    "base_package": { "type": "string", "minLength": 1 },
+    "architecture_family": { "enum": ["domain-driven", "layered-mvc"] },
+    "architecture_profile": { "type": "string", "minLength": 1 },
+    "decision_ref": { "type": "string", "minLength": 1 },
+    "decision_id": { "type": "string", "minLength": 1 },
+    "decision_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "maven_coordinates": { "type": "object" },
+    "profiles": { "type": "object" },
+    "module_profile": { "type": "object" },
+    "frontend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["app_name", "microapp_name", "base_route", "package_manager", "template", "openapi_impact"],
+      "properties": {
+        "app_name": { "type": "string", "minLength": 1 },
+        "microapp_name": { "type": "string", "minLength": 1 },
+        "base_route": { "type": "string", "pattern": "^/" },
+        "package_manager": { "const": "pnpm" },
+        "template": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["repository", "commit"],
+          "properties": {
+            "repository": { "type": "string", "minLength": 1 },
+            "commit": { "type": "string", "pattern": "^[a-f0-9]{40}$" }
+          }
+        },
+        "openapi_impact": { "enum": ["frozen", "not-applicable"] },
+        "openapi_json_ref": { "type": "string", "minLength": 1 },
+        "openapi_json_digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+        "openapi_not_applicable_reason": { "type": "string", "minLength": 1 },
+        "replacements": { "type": "object", "additionalProperties": { "type": "string" } }
+      },
+      "allOf": [
+        { "if": { "properties": { "openapi_impact": { "const": "frozen" } } }, "then": { "required": ["openapi_json_ref", "openapi_json_digest"] } },
+        { "if": { "properties": { "openapi_impact": { "const": "not-applicable" } } }, "then": { "required": ["openapi_not_applicable_reason"] } }
+      ]
+    },
+    "allowed_write_paths": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "expected_evidence_files": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "verification_commands": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["approval_ref", "approver"],
+      "properties": { "approval_ref": { "type": "string", "minLength": 1 }, "approver": { "type": "string", "minLength": 1 }, "persisted_ref": { "type": "string", "minLength": 1 }, "current_version": { "oneOf": [{ "type": "boolean" }, { "type": "integer" }, { "type": "string" }] } }
+    },
+    "generation_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "existing_target", "old_project_migration", "template_upgrade"],
+      "properties": {
+        "mode": { "const": "initialize-only" },
+        "existing_target": { "const": "unsupported" },
+        "old_project_migration": { "const": "unsupported" },
+        "template_upgrade": { "const": "unsupported" }
+      }
+    },
+    "work_unit": {
+      "type": "object",
+      "required": ["id", "behavior", "primary_skill", "supporting_skills", "tdd_mode", "allowed_write_paths", "expected_evidence", "verification_commands", "controlled_generation"],
+      "properties": {
+        "id": { "type": "string" },
+        "behavior": { "enum": ["project-scaffold", "scaffold"] },
+        "primary_skill": { "type": "string" },
+        "supporting_skills": { "type": "array", "items": { "type": "string" } },
+        "tdd_mode": { "const": "controlled-generation" },
+        "allowed_write_paths": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "expected_evidence": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "verification_commands": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "controlled_generation": { "const": true }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "delivery_role": { "const": "frontend" } } },
+      "then": { "required": ["frontend"], "properties": { "generator_skill": { "const": "yss-frontend-scaffold-generator" }, "scaffold_kind": { "const": "frontend-yss-vue3" } } }
+    },
+    {
+      "if": { "properties": { "delivery_role": { "const": "backend" } } },
+      "then": { "required": ["scaffold_request_id", "compiler_draft_ref", "lifecycle_approval_ref", "backend_repository", "scaffold_status", "project_name", "base_package", "architecture_family", "decision_ref", "decision_id", "decision_digest", "maven_coordinates", "profiles", "module_profile", "work_unit"] }
+    }
+  ]
+}

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

@@ -57,6 +57,9 @@ required_files:
   - .agents/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md
   - .agents/skills/yss-implementation-contract-compiler/tests/compiler-scenarios.test.mjs
   - .agents/skills/yss-skill-source-index-refresh/SKILL.md
+  - .agents/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs
+  - .agents/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs
+  - .agents/skills/yss-repository/tests/profile-routing.test.mjs
   - docs/agents/yss-ui-skills-integration.md
   - docs/agents/strategic-design-skills-integration.md
   - docs/user-guide/yss-ui-mcp.md
@@ -72,6 +75,8 @@ required_files:
   - docs/process/schemas/strategic-design-handoff.schema.json
   - docs/process/schemas/frontend-implementation-evidence.schema.json
   - docs/process/schemas/scaffold-architecture-decisions.schema.json
+  - docs/process/schemas/project-scaffold-contract.schema.json
+  - docs/process/schemas/implementation-repository-preparation-result.schema.json
   - docs/design/schemas/visual-baseline.schema.json
   - docs/process/schemas/subagent-task-package.schema.json
   - docs/process/templates/lifecycle-checkpoint-template.yaml
@@ -117,6 +122,9 @@ required_files:
   - scripts/verify-template-candidate
   - scripts/verify-template
   - scripts/verify-business-language-scenarios
+  - scripts/query-lifecycle-context
+  - scripts/lib/lifecycle-context-query.mjs
+  - scripts/verify-lifecycle-context-query-scenarios
   - scripts/verify-frontend-implementation-evidence-scenarios
   - scripts/prepare-maintenance-review
   - scripts/evaluate-maintenance-review-round
@@ -131,6 +139,9 @@ syntax_files:
   - scripts/update-skill-lock
   - scripts/verify-upstream-skill-source
   - scripts/lib/skill-supply-chain.mjs
+  - .agents/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs
+  - .agents/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs
+  - .agents/skills/yss-repository/tests/profile-routing.test.mjs
   - scripts/generate-lifecycle-artifacts
   - scripts/verify-lifecycle-registry
   - scripts/verify-lifecycle-checkpoint
@@ -138,6 +149,9 @@ syntax_files:
   - scripts/verify-context-contract
   - scripts/verify-context-contract-scenarios
   - scripts/verify-business-language-scenarios
+  - scripts/query-lifecycle-context
+  - scripts/lib/lifecycle-context-query.mjs
+  - scripts/verify-lifecycle-context-query-scenarios
   - scripts/verify-context-reconciliation
   - scripts/verify-context-reconciliation-scenarios
   - scripts/verify-grill-with-docs-context-scenarios
@@ -172,6 +186,10 @@ syntax_files:
   - scripts/lib/lifecycle-transition.mjs
   - scripts/verify-lifecycle-scenarios
   - scripts/verify-lifecycle-transition-scenarios
+  - scripts/verify-frontend-scaffold-generator-scenarios
+  - .agents/skills/yss-frontend-scaffold-generator/scripts/generate_scaffold.mjs
+  - .agents/skills/yss-frontend-scaffold-generator/scripts/run_scaffold_verification.mjs
+  - .agents/skills/yss-frontend-scaffold-generator/scripts/generate_and_verify_scaffold.mjs
   - scripts/verify-matt-yss-integration-scenarios
   - scripts/verify-prototype-backend-scaffold-scenarios
   - scripts/verify-yss-implementation-contract-compiler-scenarios
@@ -269,6 +287,8 @@ groups:
       - { run: "scripts/verify-skill-governance" }
       - { run: "scripts/verify-upstream-skill-source --source=iloveZzz/yss-harness-design-agent --source-root=submodules/yss-harness-design-agent", when: template-source }
       - { run: "node .agents/skills/yss-antdv-next-design/tests/run-scenarios.mjs" }
+      - { run: "node --test .agents/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs" }
+      - { run: "node --test .agents/skills/yss-repository/tests/profile-routing.test.mjs" }
   tactical-design:
     commands:
       - { run: "node .agents/skills/yss-technical-design/scripts/generate-schema.mjs --check" }
@@ -301,6 +321,7 @@ groups:
       - { run: "scripts/verify-grill-with-docs-context-scenarios" }
       - { run: "scripts/verify-strategic-context-import-scenarios" }
       - { run: "scripts/verify-lifecycle-registry" }
+      - { run: "scripts/verify-lifecycle-context-query-scenarios" }
       - { run: "scripts/verify-lifecycle-checkpoint docs/process/templates/lifecycle-checkpoint-template.yaml" }
       - { run: "scripts/verify-frontend-implementation-evidence --allow-template docs/process/templates/frontend-implementation-plan-template.yaml" }
       - { run: "scripts/verify-frontend-implementation-evidence --allow-template docs/process/templates/frontend-implementation-verification-template.yaml" }
@@ -309,6 +330,7 @@ groups:
       - { run: "scripts/verify-scaffold-architecture-decision-scenarios" }
       - { run: "scripts/verify-lifecycle-scenarios" }
       - { run: "scripts/verify-lifecycle-transition-scenarios" }
+      - { run: "scripts/verify-frontend-scaffold-generator-scenarios" }
   maintenance:
     commands:
       - { run: "scripts/verify-maintenance-checkpoint .template-source/evidence/maintenance/yss-tactical-design-l3-checkpoint-2026-08-27.yaml", when: template-source }
@@ -321,6 +343,7 @@ groups:
       - { run: "scripts/verify-scaffold-generator-scenarios" }
       - { run: "node --test .agents/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs" }
       - { run: "node --test .agents/skills/yss-layered-mvc-scaffold-generator/scripts/scaffold-generator.test.mjs" }
+      - { run: "scripts/verify-frontend-scaffold-generator-scenarios" }
       - { run: "scripts/verify-prototype-backend-scaffold-scenarios" }
       - { run: "scripts/verify-matt-yss-integration-scenarios" }
       - { run: "scripts/verify-yss-implementation-contract-compiler-scenarios" }

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

@@ -28,11 +28,17 @@ owner: ai
 | superproject_git_url | 父仓远端；必须与 `git_url` 不同 |
 | checkout_state | attached-branch / detached-head / uninitialized / empty-gitlink / 不适用 |
 | scaffold_status | existing / required / initialized |
+| preparation_status | existing-and-onboarded / initialized-and-verified / not-applicable |
+| preparation_result_ref | `artifact.implementation-repository-preparation-result` 的当前引用 |
+| project_scaffold_contract_ref | 新建工程必填；统一 schema v4，历史已批准后端 v3 只读兼容 |
+| scaffold_manifest_ref | 新建工程必填 |
+| scaffold_verification_ref | 新建工程必填，且 status=passed |
 | scaffold_architecture | `domain-driven` / `layered-mvc` / 不适用；required 时必须由用户确认 |
 | scaffold_decision_ref | `scaffold-architecture-decisions.yaml` 的 decision_id + digest |
 | scaffold_skill | `yss-ddd-scaffold-generator` / `yss-layered-mvc-scaffold-generator` / `yss-frontend-scaffold-generator` / none |
 | scaffold_target_confirmed | 是 / 否 / 不适用 |
 | target_git_url_or_output_dir |  |
+| init_git | true / false；必须来自真实用户确认 |
 | owner |  |
 | ci_system | GitLab CI / GitHub Actions / Jenkins / other / none |
 | issue_tracker | GitLab / GitHub / other |
@@ -85,4 +91,6 @@ Harness 内项目路径约束：`apps/backend/`、`apps/frontend/` 只能作为
 - 关联 Harness change：
 - 关联垂直切片：
 - 关联阶段 checkpoint：
+- 实现仓库准备聚合结果：
+- `gate.implementation-repositories-ready`：approved / blocked
 - fresh verification 命令：

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

@@ -59,7 +59,8 @@ Approved / Changes requested / Blocked
 | 已存在 `Backend Slice Implementation Contract`，且 required skills / allowed paths / forbidden patterns / evidence / seam / verification 完整 | pass / violation / not-applicable |  |
 | `yss-domain` 已按影响面落实，Domain 不依赖 Adapter、Infrastructure、Mapper、Controller 或 Web DTO | pass / violation / not-applicable |  |
 | `yss-application` 已按影响面落实，Application 只做用例编排、事务边界和跨聚合协调 | pass / violation / not-applicable |  |
-| `yss-repository` 已按影响面落实，需要持久化的切片有 PO / Repository / Convertor / GatewayImpl | pass / seam-deferred / violation / not-applicable |  |
+| `yss-repository` 已按影响面落实；所选 Profile、层边界、PO / Repository / Convertor / GatewayImpl 或 MVC repository 结构、事务归属均有文件和测试证据 | pass / seam-deferred / violation / not-applicable |  |
+| `yss-mybatis` 已按影响面落实；基类、Mapper/XML 扫描、分页责任、批量 SQL、条件开关和数据源能力与当前组件索引一致；精确结论已核验 component tree / clean 状态 | pass / seam-deferred / violation / missing_evidence / not-applicable |  |
 | `yss-web-controller` / `yss-dto` 已按影响面落实，CMD / Query / VO / Result 按既有 DTO 体系定义或复用，Controller 不用内部类或非约定包临时承载主要 DTO / VO、不手工分页主要业务集合、不穿透 Repository | pass / violation / not-applicable |  |
 | `mapstruct` 已按影响面落实，PO / Domain Model / DTO / VO / CMD / Query 转换使用 MapStruct Convertor / Mapper，未使用 `BeanUtils.copyProperties`、反射拷贝或重复手写字段赋值；例外已记录测试和补齐落点 | pass / violation / not-applicable |  |
 | `lombok` 已按影响面落实，POJO 样板代码使用 Lombok，未成片手写 getter/setter、constructor、builder、logger；实体 / POJO 未触发 `@Data` 等反模式或已说明例外 | pass / violation / not-applicable |  |
@@ -72,10 +73,11 @@ Approved / Changes requested / Blocked
 ### 后端 smoke check
 
 ```bash
-rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .*(Command|Cmd|Query|VO)|subList\\(|InMemory.*Gateway|implements .*Gateway|extends .*Repository|@TableName|Mappers\\.getMapper" apps/backend
+# <review-root...> 必须由本体项目、实现仓登记、Slice project_roots 与 allowed_write_paths 解析。
+rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .*(Command|Cmd|Query|VO)|subList\\(|InMemory.*Gateway|implements .*Gateway|extends Base(Plus)?Repository|@TableName|@MapperScan|Mappers\\.getMapper|PageQuery|insertBatchSomeColumn|yss\\.mybatis" <review-root...>
 ```
 
-命中说明：`SingleResult` / `PageResult`、`CMD` / `Query` / `VO` 命中不等于失败；需要说明其是否来自 `yss-dto` / 项目既有体系、是否位于约定包路径、是否继承约定基类。
+命中说明：DTO/Result 或 MyBatis 基类、`PageQuery`、批量/扫描配置命中不等于失败；需要按当前合同、Repository Profile 和 MyBatis source index 说明其来源、分页责任与配置是否匹配。
 
 | 命中 | 解释 | 结论 |
 |---|---|---|
@@ -119,6 +121,8 @@ rg -n "from 'ant-design-vue'|<(Table|Tree|Form)[ >]|YFormily|YssFormily|YTable|Y
 | Agent 尝试用 `BeanUtils.copyProperties`、反射拷贝或大段手写字段赋值完成 POJO 转换 | 应被标记为 `violation`，回到 `mapstruct` 补 Convertor / Mapper，或补受控例外、测试和 review 证据 |  |
 | Agent 尝试成片手写 getter/setter、constructor、builder 或 logger | 应被标记为 `violation`，回到 `lombok` 补注解，或补受控例外、测试和 review 证据 |  |
 | Agent 尝试用 `InMemory*Gateway` 完成正式持久化 | 只能 `seam-deferred`，必须有补齐切片和风险说明 |  |
+| Agent 未核验 Profile/source index 就选择 `BaseRepository` / `BasePlusRepository`，或把两套分页责任混在同一查询 seam | 应按 `yss-repository` / `yss-mybatis` 标记 `violation` 或 `missing_evidence` |  |
+| Agent 把多数据源实例集合误当成线程上下文动态路由，或在事务进入后才尝试切换 | 应标记 `violation`；先核验组件能力，再由批准的上层适配承担路由 |  |
 | Agent 只写“符合 YSS”但没有 skill / 文件 / 测试证据 | 应被标记为 `violation` |  |
 | Agent 在后端验证、CI、README 或发布说明中写裸 `mvn ...` | 应改为项目根目录 `./mvnw ...`，否则标记为 `violation` |  |
 | Agent 将英文 skill / 模板的标题和说明原样输出为项目持久化文档 | 应改为中文正文和中文章节标题，否则标记为 `violation` |  |

package/template/scripts/lib/lifecycle-context-query.mjs

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+import { ROOT, loadRegistry, semanticDigest, validateRegistry } from "./lifecycle-registry.mjs";
+import { loadSkillRegistry } from "./skill-registry.mjs";
+
+const LIFECYCLE_REGISTRY_REF = "docs/process/lifecycle-registry.yaml";
+const ORCHESTRATION_CONTRACT_REF = ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml";
+const SKILL_REGISTRY_REF = "docs/agents/yss-skill-registry.yaml";
+
+function read(relativePath) {
+  return readFileSync(path.join(ROOT, relativePath), "utf8");
+}
+
+function sha256(source) {
+  return createHash("sha256").update(source).digest("hex");
+}
+
+function loadYaml(relativePath, label) {
+  const document = parseDocument(read(relativePath), { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new TypeError(`无法解析${label}: ${document.errors[0].message}`);
+  const value = document.toJS({ maxAliasCount: 0 });
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label}必须是对象`);
+  return value;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  }
+  return value;
+}
+
+function selectById(records, id, label) {
+  if (!id) return null;
+  const selected = records.find((record) => record.id === id);
+  if (!selected) throw new TypeError(`未知${label}: ${id}`);
+  return selected;
+}
+
+function collectPathReferences(value, references = new Set()) {
+  if (Array.isArray(value)) {
+    for (const item of value) collectPathReferences(item, references);
+  } else if (value && typeof value === "object") {
+    for (const item of Object.values(value)) collectPathReferences(item, references);
+  } else if (typeof value === "string" && /(?:^|\/)[^\s]+\.(?:md|ya?ml|json|mjs)(?:#.*)?$/.test(value)) {
+    references.add(value);
+  }
+  return references;
+}
+
+function selectedSkills(route, skillRegistry) {
+  if (!route) return [];
+  const ids = new Set([
+    route.primary_skill,
+    route.native?.skill,
+    ...(route.supporting_skills ?? []),
+    ...(route.skills ?? []),
+  ].filter(Boolean));
+  return skillRegistry.skills.filter((skill) => ids.has(skill.id));
+}
+
+export function queryLifecycleContext({ mode, stageId, workUnitId, include = [] } = {}) {
+  if (!mode && !stageId && !workUnitId && include.length === 0) {
+    throw new TypeError("至少提供 --mode、--stage、--work-unit 或 --include 之一");
+  }
+
+  const lifecycle = validateRegistry(loadRegistry());
+  const orchestration = loadYaml(ORCHESTRATION_CONTRACT_REF, "生命周期编排合同");
+  const skillRegistry = loadSkillRegistry();
+  const stage = selectById(lifecycle.stages, stageId, "阶段");
+  const workUnit = selectById(lifecycle.work_units, workUnitId, "工作单元");
+
+  if (mode && !(mode in orchestration.modes)) throw new TypeError(`未知模式: ${mode}`);
+  const normalizedIncludes = [...new Set(include.flatMap((value) => value.split(",")).map((value) => value.trim()).filter(Boolean))].sort();
+  for (const key of normalizedIncludes) {
+    if (!(key in orchestration)) throw new TypeError(`未知编排合同子树: ${key}`);
+  }
+
+  const route = workUnitId ? orchestration.work_unit_routes?.[workUnitId] ?? null : null;
+  const gates = stageId ? lifecycle.gates.filter((gate) => gate.stage === stageId) : [];
+  const artifacts = stageId ? lifecycle.artifacts.filter((artifact) => artifact.stage === stageId) : [];
+  const evidenceIds = new Set(gates.flatMap((gate) => gate.evidence ?? []));
+  const selected = Object.fromEntries(normalizedIncludes.map((key) => [key, orchestration[key]]));
+  const transition = workUnitId ? {
+    next: orchestration.transition_graph?.routes?.[workUnitId] ?? [],
+    forbidden_shortcuts: (orchestration.transition_graph?.forbidden_shortcuts ?? [])
+      .filter((edge) => edge.from === workUnitId || edge.to === workUnitId),
+  } : null;
+
+  const result = {
+    schema_version: 1,
+    query: {
+      include: normalizedIncludes,
+      mode: mode ?? null,
+      stage: stageId ?? null,
+      work_unit: workUnitId ?? null,
+    },
+    sources: {
+      lifecycle_registry: {
+        ref: LIFECYCLE_REGISTRY_REF,
+        semantic_sha256: semanticDigest(lifecycle),
+        status: lifecycle.status,
+      },
+      orchestration_contract: {
+        ref: ORCHESTRATION_CONTRACT_REF,
+        sha256: sha256(read(ORCHESTRATION_CONTRACT_REF)),
+      },
+      skill_registry: {
+        ref: SKILL_REGISTRY_REF,
+        sha256: sha256(read(SKILL_REGISTRY_REF)),
+        status: skillRegistry.status,
+      },
+    },
+    lifecycle: {
+      artifacts,
+      evidence: lifecycle.evidence.filter((item) => evidenceIds.has(item.id)),
+      gates,
+      stage,
+      work_unit: workUnit,
+    },
+    execution: {
+      mode: mode ? orchestration.modes[mode] : null,
+      selected,
+      transition,
+      work_unit_route: route,
+    },
+    skills: selectedSkills(route, skillRegistry),
+  };
+  result.references = [...collectPathReferences(result), LIFECYCLE_REGISTRY_REF, ORCHESTRATION_CONTRACT_REF, SKILL_REGISTRY_REF]
+    .filter((value, index, all) => all.indexOf(value) === index)
+    .sort();
+  return canonicalize(result);
+}
+