create-yss-spec 3.4.9 → 3.4.10

package/template/docs/process/schemas/lifecycle-checkpoint.schema.json

@@ -255,6 +255,265 @@
         }
       },
       "additionalProperties": false
+    },
+    "stage_tracking": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schema_version",
+        "feature_id",
+        "checkpoint_ref",
+        "entry_stage",
+        "entry",
+        "items"
+      ],
+      "properties": {
+        "schema_version": {
+          "const": 1
+        },
+        "feature_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "checkpoint_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "entry_stage": {
+          "type": "string",
+          "minLength": 1
+        },
+        "entry": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "ref"
+          ],
+          "properties": {
+            "kind": {
+              "enum": [
+                "parent-ticket",
+                "checkpoint"
+              ]
+            },
+            "ref": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "kind",
+              "title",
+              "stage",
+              "work_unit",
+              "owner",
+              "scope",
+              "acceptance",
+              "dependencies",
+              "source_refs",
+              "progress",
+              "split_reasons",
+              "completion"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$"
+              },
+              "kind": {
+                "const": "stage-work-item"
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1
+              },
+              "stage": {
+                "type": "string",
+                "minLength": 1
+              },
+              "work_unit": {
+                "type": "string",
+                "minLength": 1
+              },
+              "owner": {
+                "type": "string",
+                "minLength": 1
+              },
+              "scope": {
+                "type": "string",
+                "minLength": 1
+              },
+              "acceptance": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1,
+                "uniqueItems": true
+              },
+              "dependencies": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "uniqueItems": true
+              },
+              "source_refs": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "ref",
+                    "digest"
+                  ],
+                  "properties": {
+                    "ref": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "digest": {
+                      "type": "string",
+                      "pattern": "^sha256:[0-9a-f]{64}$"
+                    }
+                  }
+                }
+              },
+              "progress": {
+                "enum": [
+                  "pending",
+                  "running",
+                  "blocked",
+                  "completed",
+                  "cancelled"
+                ]
+              },
+              "split_reasons": {
+                "type": "array",
+                "items": {
+                  "enum": [
+                    "different-owner",
+                    "independent-acceptance",
+                    "blocks-other-work",
+                    "cross-stage-deferral"
+                  ]
+                },
+                "uniqueItems": true
+              },
+              "completion": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "criterion",
+                    "evidence_refs"
+                  ],
+                  "properties": {
+                    "criterion": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "evidence_refs": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "required": [
+                          "ref",
+                          "digest"
+                        ],
+                        "properties": {
+                          "ref": {
+                            "type": "string",
+                            "minLength": 1
+                          },
+                          "digest": {
+                            "type": "string",
+                            "pattern": "^sha256:[0-9a-f]{64}$"
+                          }
+                        }
+                      },
+                      "minItems": 1
+                    }
+                  }
+                }
+              },
+              "definition_ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "definition_digest": {
+                "type": "string",
+                "pattern": "^sha256:[0-9a-f]{64}$"
+              },
+              "recheck_required": {
+                "type": "boolean"
+              },
+              "cancellation_reason": {
+                "type": "string",
+                "minLength": 1
+              },
+              "deferred": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "owner",
+                  "resolve_by",
+                  "receiver",
+                  "verification_plan",
+                  "decision_ref",
+                  "risk",
+                  "follow_up_ref"
+                ],
+                "properties": {
+                  "owner": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "resolve_by": {
+                    "type": "string",
+                    "format": "date-time"
+                  },
+                  "receiver": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "verification_plan": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "decision_ref": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "risk": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "follow_up_ref": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "$id": "https://yss.dev/schemas/stage-tracking.schema.json",
+      "title": "阶段工作追踪 v1"
     }
   }
 }

package/template/docs/process/schemas/stage-tracking.schema.json

@@ -0,0 +1,259 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "feature_id",
+    "checkpoint_ref",
+    "entry_stage",
+    "entry",
+    "items"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "feature_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "checkpoint_ref": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry_stage": {
+      "type": "string",
+      "minLength": 1
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "ref"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "parent-ticket",
+            "checkpoint"
+          ]
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "kind",
+          "title",
+          "stage",
+          "work_unit",
+          "owner",
+          "scope",
+          "acceptance",
+          "dependencies",
+          "source_refs",
+          "progress",
+          "split_reasons",
+          "completion"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          },
+          "kind": {
+            "const": "stage-work-item"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1
+          },
+          "work_unit": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "type": "string",
+            "minLength": 1
+          },
+          "scope": {
+            "type": "string",
+            "minLength": 1
+          },
+          "acceptance": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "dependencies": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "uniqueItems": true
+          },
+          "source_refs": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "ref",
+                "digest"
+              ],
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "digest": {
+                  "type": "string",
+                  "pattern": "^sha256:[0-9a-f]{64}$"
+                }
+              }
+            }
+          },
+          "progress": {
+            "enum": [
+              "pending",
+              "running",
+              "blocked",
+              "completed",
+              "cancelled"
+            ]
+          },
+          "split_reasons": {
+            "type": "array",
+            "items": {
+              "enum": [
+                "different-owner",
+                "independent-acceptance",
+                "blocks-other-work",
+                "cross-stage-deferral"
+              ]
+            },
+            "uniqueItems": true
+          },
+          "completion": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "criterion",
+                "evidence_refs"
+              ],
+              "properties": {
+                "criterion": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "evidence_refs": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "ref",
+                      "digest"
+                    ],
+                    "properties": {
+                      "ref": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "digest": {
+                        "type": "string",
+                        "pattern": "^sha256:[0-9a-f]{64}$"
+                      }
+                    }
+                  },
+                  "minItems": 1
+                }
+              }
+            }
+          },
+          "definition_ref": {
+            "type": "string",
+            "minLength": 1
+          },
+          "definition_digest": {
+            "type": "string",
+            "pattern": "^sha256:[0-9a-f]{64}$"
+          },
+          "recheck_required": {
+            "type": "boolean"
+          },
+          "cancellation_reason": {
+            "type": "string",
+            "minLength": 1
+          },
+          "deferred": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "owner",
+              "resolve_by",
+              "receiver",
+              "verification_plan",
+              "decision_ref",
+              "risk",
+              "follow_up_ref"
+            ],
+            "properties": {
+              "owner": {
+                "type": "string",
+                "minLength": 1
+              },
+              "resolve_by": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "receiver": {
+                "type": "string",
+                "minLength": 1
+              },
+              "verification_plan": {
+                "type": "string",
+                "minLength": 1
+              },
+              "decision_ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "risk": {
+                "type": "string",
+                "minLength": 1
+              },
+              "follow_up_ref": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yss.dev/schemas/stage-tracking.schema.json",
+  "title": "阶段工作追踪 v1"
+}

package/template/docs/process/stage-tracking.md

@@ -0,0 +1,62 @@
+# Plan / Spec / Design 阶段工作追踪
+
+本合同由主 tracker 与生命周期编排器消费。阶段、注册工作单元及父 Ticket 创建时点以生命周期注册表为准；工作项结构以 `schemas/stage-tracking.schema.json` 为准。
+
+## 启用与职责
+
+`docs/agents/issue-tracker.md` 的 `tracker.lifecycle_tracking_version: 1` 表示项目已启用。新初始化默认启用；attach / sync 保留已有配置，未声明的旧项目不自动启用。只读检查不修改项目；旧项目先 plan 再显式 apply。模板源只维护机制，不在模板根生成产品工作项。
+
+完整研发从 Plan（或接入的最近可信阶段）建立唯一父 Ticket。Design 继续使用 checkpoint / map，不创建工程父 Ticket。Backend / Frontend 只消费已交接资产，不因本协议取得 Plan、Spec 或产品设计的编写权限。Dev 消费主模板的同一协议。
+
+checkpoint 的 `stage_tracking` 是阶段工作项当前进度的唯一机器状态源。父 Ticket、map、远程镜像只引用它。业务 Ticket 与工程切片仍由现有 tracker 管理；本协议不替代 Ticket 五态、业务批准、工作单元结果或实现合同。
+
+## 工作项
+
+同一负责人可连续完成的小工作以内联项记录。不同负责人、独立验收、阻塞其他工作或跨阶段延期时创建 `work-items/<id>.md`，类型为 `stage-work-item`。`issues/` 继续承载各 profile 的业务 Ticket / 实现切片。
+
+工作项包含 ID、标题、阶段、注册工作单元、负责人、范围、验收条件、依赖、源资产摘要、进度和验收证据；独立说明文件不保存 `Status` 或进度。相同 ID 恢复时复用；同 ID 不同定义返回冲突。每项 `source_refs` 绑定实际消费的输入；`completion` 逐条将验收条件关联到可读取且当前的证据摘要，不能以文件存在代替验收。
+
+进度为 `pending / running / blocked / completed / cancelled`。取消要有理由；延期保留未完成进度，并记录风险、负责人、解决时点、接收方、后续引用、验证计划和既有决定引用。延期不绕过原有门禁或风险接受规则。完成要求所有依赖已完成、逐条验收有证据且来源未漂移。阶段工作项不得出现 `ready-for-agent`，也不能绑定为 Slice 的实现 Ticket。
+
+## 推进与恢复
+
+1. 正式写入阶段资产前，先建立 checkpoint 与当前工作项；缺负责人 / 范围 / 验收时保留缺口，不推断历史完成。
+2. 进入当前阶段前检查 `scripts/stage-tracking check`；恢复时同样执行。阻塞、责任变化、资产批准和阶段退出必须回写，普通编辑仍集中记录。
+3. `Workflow Execution Result.checkpoint_ref` 引用当前持久 checkpoint。流转验证读取真实 checkpoint，拒绝仅在结果中自述追踪已完成。
+4. 上游或验收证据摘要变化时，用 `plan --refresh` 生成受影响项回到 pending / recheck_required 的差异，再 apply；旧摘要与证据原样保留。复验后由主控更新源摘要及验收映射，清除 recheck_required。
+5. 流转要求当前工作单元的必需项完成或按原规则延期；跨阶段检查当前阶段。无依赖工作可继续，延期并不使依赖它的工作可执行。
+6. 完成工作项只代表其验收通过，不能替代 Spec、Design 或工程合同批准。
+
+## 公共命令
+
+```sh
+scripts/stage-tracking check --root <项目> --checkpoint docs/.scratch/<feature>/checkpoint.yaml
+scripts/stage-tracking plan --root <项目> --checkpoint docs/.scratch/<feature>/checkpoint.yaml --items <工作项数组.yaml> > <plan.json>
+scripts/stage-tracking apply --root <项目> --plan <plan.json>
+scripts/stage-tracking plan --root <项目> --checkpoint docs/.scratch/<feature>/checkpoint.yaml --refresh > <refresh-plan.json>
+```
+
+check / plan 不写项目。首次 checkpoint 不存在时，plan 从本项目 checkpoint 模板形成草稿。没有明确工作项时输出 gaps，apply 拒绝。items 只登记 pending 项，不把历史产物推断为完成，也不覆盖已有同 ID 项。
+
+apply 复验项目身份、计划摘要、全部观察文件及源证据摘要，备份后写入。写入失败恢复本次已写内容；若检测到后续并发修改，保留文件并报告恢复冲突。备份和失败清单保存在功能包 verification/stage-tracking-migrations 内；不得删除后续执行证据。相同成功计划再次应用返回 unchanged。
+
+远程 tracker 不可用时，父票保留 publication: pending 和 pending_publication_to；本工具不访问远程平台。下游正式化业务票 / 切片时关联本阶段资产与工作项引用，不将已完成设计工作项改写为开发切片。
+
+首次登记的工作项数组示例（路径、负责人、范围与验收按真实任务填写）：
+
+```yaml
+- id: clarify-scope
+  title: 明确本轮范围
+  stage: stage.plan
+  work_unit: work-unit.plan-requirements
+  owner: 当前需求负责人
+  scope: 明确本轮包含与排除的业务行为
+  acceptance:
+    - 范围及至少一个边界例子可供审阅
+  dependencies: []
+  source_refs:
+    - docs/.scratch/example/plan/input.md
+  split_reasons: []
+```
+
+不同负责人和被其他项依赖的工作会自动拆分；独立验收使用 `split_reasons: [independent-acceptance]`。登记只创建 pending 项，不能把输入文件当成已通过的验收证据。启用项目缺少 checkpoint 时，check 返回非零退出码；先审阅并应用登记计划，再进入阶段写入。

package/template/docs/process/strategic-handoff-package.md

@@ -106,3 +106,11 @@ scripts/strategic-feedback verify-adjudication --root <消费者项目根> <adju
 `gate.strategic-design-handoff-approved` 不要求新的用户回复，也不把旧决定改写为交接决定。产品经理形成完整交接包后，由需求经理独立复核来源批准新鲜度、完整包摘要、风险与范围，并以 Fresh Verification 关闭交接门禁。缺少独立复核、来源批准过期、摘要漂移或验证失败均阻断 finalize。
 
 历史包中的 `strategic-decision-reuse-v1`、`decision_reuse_ref` 和旧门禁批准保持可读，供离线 `verify/import` 复核当时证据。它们不能关闭当前聚合门禁；任何修改、重发或继续流转都必须先完成战略门禁迁移并重新批准。
+
+## 插件接收入口与目标路由
+
+`yss-product-design` 在战略 profile 内完成设计与 Handoff v5 交付，`yss-backend-delivery` 通过 `project-import-design` 调用目标项目的 `scripts/strategic-consumer-entry --root <目标根> --bundle <交付目录或ZIP>`。入口先验证源包与后端路线，再执行既有 import；返回收据和目标工程设计入口，固定 `ready_for_agent: false`。恢复以 `--receipt <项目内收据路径>` 重新验证，查询不导入文件。
+
+源 `work-unit.technical-design` 保留不变，目标主控 `consumer_entry_routes` 持有精确映射；`plan-to-backend` 和完整主模板进入 `work-unit.technical-analysis`，专职后端进入自己的 `work-unit.technical-design`。目标工作单元不存在或超出 profile/职责范围时阻断。后端插件的 scope 只选择 backend-technical-design；源包保留完整前端、协调路线，不宣称已接管或完成。
+
+正式交付目录导入生成 Receipt v3；现有运输 package.zip 按已有协议生成 v2 收据，源包、批准、逻辑摘要仍须完整校验，不能补造 source-delivery-record。消费校验、反馈裁决和 Slice Contract 的实现门禁保持不变。

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md

@@ -92,6 +92,8 @@ npx create-yss-harness-frontend@latest init --target-dir ./frontend-project --pr
 
 完整演练见[设备借用贯穿案例](设备借用贯穿案例.md)，后端技术设计见[技术设计用户指南](技术设计用户指南.md)。
 
+已有 Spec、设计、冻结接口或后端交付包时，按[阶段接入与产物复用使用手册](阶段接入与产物复用使用手册.md)从最近可信阶段继续。手册提供可复制指令、前端接收操作、命令及阻塞处理，帮助复用有效上游资产并补齐当前阶段缺口。
+
 ## 接管、同步与恢复
 
 综合 CLI 示例：

package/template/docs/user-guide//347/224/250/346/210/267/346/211/213/345/206/214/347/264/242/345/274/225.md

@@ -5,6 +5,7 @@
 1. [YSS 用户手册](用户手册.md)：四个现行家族的选型、CLI、确认、同步和恢复。
 2. [设备借用贯穿案例](设备借用贯穿案例.md)：战略、后端、前端与统一验收的完整练习。
 3. [技术设计用户指南](技术设计用户指南.md)：批准战略或 Spec 如何进入 DDD / layered-mvc 技术设计和实现合同。
+4. [阶段接入与产物复用使用手册](阶段接入与产物复用使用手册.md)：从已有产物继续，含后端交付后前端接收、准备、开发及恢复步骤。
 
 ## 按职责进入子项目