create-yss-spec 3.5.3 → 3.5.4

package/template/.template-spec/process/project-ci.md

@@ -0,0 +1,21 @@
+# 项目治理 CI 与恢复预检
+
+此入口适用于 `project-instance`。初始化、同步仅分发工具，不自动写 `.github`；业务构建仍使用实现仓库的工作流。远端分支保护由维护者配置，不由本工具更改。
+
+```sh
+node scripts/project-ci plan --provider github --root . --branch main > /tmp/yss-ci-plan.json
+node scripts/project-ci apply --root . --plan /tmp/yss-ci-plan.json
+node scripts/project-ci check --root . --json
+node scripts/project-ci check --root . --base <PR基线的40位提交> --json
+node scripts/lifecycle-status --root . --checkpoint docs/.scratch/feature/checkpoint.yaml --preflight
+```
+
+计划列出目标分支、范围、文件内容、输入摘要和冲突。仅显式 apply 写入独立工作流、接入配置和托管凭据；保留其他工作流。输出文件已被手工修改、计划过期或同名文件未托管时拒绝覆盖。中断后执行 `node scripts/project-ci apply --root . --recover`，按事务日志恢复旧字节；遇到后续人工修改时停止并保留现场。重复 apply 无变化；tracker 或工具输入变化后须重新 plan。
+
+范围来自 `.template-spec/agents/issue-tracker.md` 的 `tracker.root`，可用重复的 `--additional-path <根相对路径>` 显式补充。接入配置只登记范围与分支，不复制阶段状态。完整检查范围内已登记记录及其本地引用闭包；草案允许缺少未来阶段产物。当前批准、完成、流转和 `ready-for-agent` 声明必须具有可校验的依据。当前流转由 `stage_trace.completed_work_unit` 与 `next_work_unit` 交给现有流转校验器核验。只安装当前阶段能力即可；命中未来阶段检查但工具尚未安装时报告能力缺失，显式补齐后重验。
+
+报告包含实际校验命令、输入引用及摘要、退出码、耗时、日志、未知资产和诊断。命令来自固定校验入口；不会执行 checkpoint/合同中自由填写的业务命令。普通状态查询仍只读状态；只有 `--preflight` 执行当前校验。运行中、失败或未知任务不能当成完成或自动重复派发；任务结果确认后由主控恢复。
+
+GitHub 工作流运行于 PR、计划中目标分支 push、手动执行，固定汇总检查名 `YSS governance`，日志以 artifact 保留。PR 对照目标基线检查范围缩小、checkpoint 删除和批准依据删除。删除或归档必须先形成可审阅的显式处置，不能靠删除记录使检查变绿。维护者可在远端将 `YSS governance` 设为 required check；本地通过不代表远端已配置。
+
+`project-ci` 与恢复预检：0=适用检查通过或计划/应用成功；1=检查失败或计划冲突；2=输入、能力或执行异常。JSON 的 `status` 和诊断必须一起读取。查询工具的 0 只表示诊断执行完成，不能替代批准、执行授权或发布结论。`--history` 仅供历史记录只读兼容，CI、当前流转和恢复预检不使用历史结果放行。

package/template/.template-spec/process/reading-policy.yaml

@@ -0,0 +1,4 @@
+# 实际人工阅读试验通过前，新实例保持手动；存量实例由 contract plan-enable/apply-enable 显式登记。
+schema_version: 1
+mode: manual
+checkpoints: []

package/template/.template-spec/process/schemas/business-tickets-v1.schema.json

@@ -0,0 +1,449 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "business-tickets-v1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": {
+          "const": 1
+        },
+        "kind": {
+          "const": "business-ticket"
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^BT-[A-Za-z0-9][A-Za-z0-9._-]*$"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^v[1-9][0-9]*$"
+        },
+        "status": {
+          "enum": [
+            "draft",
+            "ready-for-human"
+          ]
+        },
+        "spec": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "ref": {
+              "type": "string",
+              "minLength": 1
+            },
+            "version": {
+              "type": "string",
+              "pattern": "^v[1-9][0-9]*$"
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            },
+            "locator": {
+              "type": "string",
+              "minLength": 1
+            },
+            "locator_kind": {
+              "enum": [
+                "id",
+                "heading"
+              ]
+            }
+          },
+          "required": [
+            "ref",
+            "version",
+            "digest"
+          ]
+        },
+        "requirement_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "acceptance_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 0,
+          "uniqueItems": true
+        },
+        "source_refs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "version": {
+                "type": "string",
+                "pattern": "^v[1-9][0-9]*$"
+              },
+              "digest": {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              },
+              "locator": {
+                "type": "string",
+                "minLength": 1
+              },
+              "locator_kind": {
+                "enum": [
+                  "id",
+                  "heading"
+                ]
+              }
+            },
+            "required": [
+              "ref",
+              "version",
+              "digest"
+            ]
+          },
+          "minItems": 0,
+          "uniqueItems": true
+        },
+        "open_questions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "question": {
+                "type": "string",
+                "minLength": 1
+              },
+              "owner": {
+                "type": "string",
+                "minLength": 1
+              },
+              "resolve_by": {
+                "type": "string",
+                "minLength": 1
+              },
+              "blocking": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "id",
+              "question",
+              "owner",
+              "resolve_by",
+              "blocking"
+            ]
+          },
+          "minItems": 0,
+          "uniqueItems": true
+        }
+      },
+      "required": [
+        "schema_version",
+        "kind",
+        "id",
+        "version",
+        "status",
+        "spec",
+        "requirement_refs",
+        "acceptance_refs",
+        "dependencies",
+        "source_refs",
+        "open_questions"
+      ]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": {
+          "const": 1
+        },
+        "kind": {
+          "const": "business-ticket-set"
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^v[1-9][0-9]*$"
+        },
+        "status": {
+          "enum": [
+            "draft",
+            "ready-for-human"
+          ]
+        },
+        "spec": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "ref": {
+              "type": "string",
+              "minLength": 1
+            },
+            "version": {
+              "type": "string",
+              "pattern": "^v[1-9][0-9]*$"
+            },
+            "digest": {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            },
+            "locator": {
+              "type": "string",
+              "minLength": 1
+            },
+            "locator_kind": {
+              "enum": [
+                "id",
+                "heading"
+              ]
+            }
+          },
+          "required": [
+            "ref",
+            "version",
+            "digest"
+          ]
+        },
+        "tickets": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "version": {
+                "type": "string",
+                "pattern": "^v[1-9][0-9]*$"
+              },
+              "digest": {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              }
+            },
+            "required": [
+              "id",
+              "ref",
+              "version",
+              "digest"
+            ]
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "coverage_deferred": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1
+              },
+              "risk": {
+                "type": "string",
+                "minLength": 1
+              },
+              "owner": {
+                "type": "string",
+                "minLength": 1
+              },
+              "target_version": {
+                "type": "string",
+                "minLength": 1
+              },
+              "followup_ticket_ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "verification_plan": {
+                "type": "string",
+                "minLength": 1
+              },
+              "decision": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "ref": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "version": {
+                    "type": "string",
+                    "pattern": "^v[1-9][0-9]*$"
+                  },
+                  "digest": {
+                    "type": "string",
+                    "pattern": "^sha256:[a-f0-9]{64}$"
+                  },
+                  "locator": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "locator_kind": {
+                    "enum": [
+                      "id",
+                      "heading"
+                    ]
+                  }
+                },
+                "required": [
+                  "ref",
+                  "version",
+                  "digest"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "reason",
+              "risk",
+              "owner",
+              "target_version",
+              "followup_ticket_ref",
+              "verification_plan"
+            ]
+          },
+          "minItems": 0,
+          "uniqueItems": true
+        },
+        "review_ref": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "schema_version",
+        "kind",
+        "id",
+        "version",
+        "status",
+        "spec",
+        "tickets",
+        "coverage_deferred"
+      ]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": {
+          "const": 1
+        },
+        "kind": {
+          "const": "business-ticket-review"
+        },
+        "result": {
+          "enum": [
+            "passed",
+            "blocked"
+          ]
+        },
+        "subject_ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "subject_digest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$"
+        },
+        "reviewer": {
+          "type": "string",
+          "minLength": 1
+        },
+        "drafter": {
+          "type": "string",
+          "minLength": 1
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "version": {
+                "type": "string",
+                "pattern": "^v[1-9][0-9]*$"
+              },
+              "digest": {
+                "type": "string",
+                "pattern": "^sha256:[a-f0-9]{64}$"
+              },
+              "locator": {
+                "type": "string",
+                "minLength": 1
+              },
+              "locator_kind": {
+                "enum": [
+                  "id",
+                  "heading"
+                ]
+              }
+            },
+            "required": [
+              "ref",
+              "version",
+              "digest"
+            ]
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "required": [
+        "schema_version",
+        "kind",
+        "result",
+        "subject_ref",
+        "subject_digest",
+        "reviewer",
+        "drafter",
+        "evidence"
+      ]
+    }
+  ]
+}