create-yss-spec 3.3.0 → 3.3.3

package/template/docs/discovery/reports/agent-governance-options.md

@@ -1,71 +0,0 @@
-# Agent Skill 治理升级决策分析
-
-## 结论摘要
-
-1. 逐技能结构 / 路由 / 行为 eval 不作为 YSS 模板首个升级方向。结构和路由已有确定性校验；行为 eval 成本高、易重复生命周期门禁，应降为后续按变更和风险触发的试验性能力。
-2. invocation metadata 进入 `yss-skill-registry.yaml`；实现合同编译器 合同只定义字段 schema、解析和阻断规则，不复制每个 skill 的示例。trigger examples 进入注册表，但保持少量、结构化、只为消歧服务。
-3. freshness audit 作为生命周期完成条件的 core 能力，不新建一个常驻通用 skill；Doubt-Driven 作为高风险条件触发的 core 路由策略；Wayfinder 保持 maintainer-only / 兼容入口的可选模式，不进入默认 core 路由。
-
-## Q1：eval 是否为首个升级方向
-
-### 现状事实
-
-- 技能身份、层级、成熟度、别名、默认可发现性和来源投影已经由 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml)、[`skill-registry.mjs`](../../../scripts/lib/skill-registry.mjs)、`sync-skills` 和 `skills-lock.json` 共同校验。
-- 生命周期路由和 实现合同编译器 已经对未登记技能、依赖闭包、原型独立评审、代码审查唯一入口等关键路由做确定性检查。
-- 生命周期完成已经要求 fresh verification、证据可读、阻断信号清空和 stale / drift 重路由。
-
-### 决策
-
-不把“每个 skill 三层 eval”作为 P0。采用以下顺序：
-
-| 层次 | 初始策略 | 原因 |
-|---|---|---|
-| 结构 | 继续使用现有静态 / schema 校验 | 成本最低，收益已覆盖大部分缺陷 |
-| 路由 | 只对注册表、实现合同编译器、生命周期变更做确定性增量校验 | 与现有门禁直接对齐，避免重复运行 |
-| 行为 | P2 试验；只覆盖变更中的 core / 高风险 skill | 避免全量运行导致 token 和维护成本失控 |
-
-行为 eval 的进入条件应是：skill 内容或路由发生变化、命中高风险影响、或出现真实 finding；退出条件是连续真实任务证明它能发现现有静态校验抓不到的问题，且没有形成第二套生命周期门禁。
-
-## Q2：invocation metadata 与 trigger examples 的归属
-
-### 决策
-
-- **注册表**是技能级调用元数据的唯一事实源：调用模式、触发条件、排除条件、主要输出、依赖和少量 trigger examples 均放在这里。
-- **实现合同编译器 合同**定义 schema、解析顺序、依赖闭包和阻断规则；不复制每个技能的完整示例，避免注册表与 实现合同编译器 漂移。
-- **生命周期编排合同**继续保留工作单元级 `workflow_reference.invocation_mode`（例如 `model-invoked` / `reference`）。它描述一次工作单元如何被执行，不与注册表的 `user` / `model` / `both` 技能级模式混用。
-
-### trigger examples 约束
-
-- 仅为消歧提供 1–3 个正向示例，必要时提供反向排除示例。
-- 示例优先使用 `impact:<name>`、显式用户入口或工作单元 ID 等稳定标识；长篇自然语言放入 skill reference，不放在注册表核心字段。
-- specialist 技能可继承 `impacts` 触发条件；只有存在歧义时才增加显式 examples。
-- examples 只影响发现和路由提示，不直接批准门禁、Ticket 状态或 `ready-for-agent`。
-
-当前已落地的低成本基础见 [`yss-skill-registry.yaml`](../../agents/yss-skill-registry.yaml) 的 `invocation_contract`，以及 [`compiler-contract.yaml`](../../.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml) 的合同字段。
-
-## Q3：三项能力的路由层级
-
-| 能力 | 推荐层级 | 具体落点 | 不应做什么 |
-|---|---|---|---|
-| freshness audit | core 能力 | 生命周期完成条件、候选快照、fresh verification、stale / drift 检查 | 不再新增一个对所有任务常驻的通用审计 skill |
-| Doubt-Driven | core 条件路由 | 实现合同编译器 / 工程基线 / 架构与契约审查中的高风险分支 | 不升级为所有低风险任务的默认步骤，不新建生命周期阶段 |
-| Wayfinder | maintainer-only / 兼容入口的可选模式 | 超长、多 Agent、多会话或 frontier 不清晰时，完成后回 `handoff → to-spec` | 不改变阶段、门禁、Ticket 角色或 `ready-for-agent` |
-
-### Doubt-Driven 的高风险触发器
-
-API schema、数据库 schema / 迁移、跨仓库契约、发布 / 回滚、实际改变的认证授权 / 租户 / 敏感数据行为，以及生命周期或生成语义。反证记录进入既有决策、架构、契约或发布审查记录；缺反证、证据不足或残余风险未处理时阻断。
-
-### freshness audit 的边界
-
-freshness 是“完成结论可信度”的 core 约束，而不是新的工作单元。模板维护继续使用 L1/L2/L3 checkpoint；产品切片继续使用 Slice Contract 和候选快照。这样可以复用同一条 finding 闭环，不增加每次调用的上下文负担。
-
-## 证据来源
-
-- [YSS skill registry](../../agents/yss-skill-registry.yaml)
-- [Skill registry validator](../../../scripts/lib/skill-registry.mjs)
-- [YSS 实现合同编译器 contract](../../.agents/skills/yss-implementation-contract-compiler/references/compiler-contract.yaml)
-- [Slice Implementation Contract](../../.agents/skills/yss-implementation-contract-compiler/references/slice-implementation-contract.md)
-- [Lifecycle orchestration contract](../../.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml)
-- [Harness process tailoring](../../process/harness-process-tailoring.md)
-- [Addy Osmani agent-skills](https://github.com/addyosmani/agent-skills)
-- [Matt Pocock skills](https://github.com/mattpocock/skills)

package/template/docs/discovery/templates/discovery-template.md

@@ -1,94 +0,0 @@
----
-pipeline: <feature-id>
-stage: discovery
-status: draft
-owner: ai
----
-
-# <功能名称> Discovery 收敛文档
-
-> 适用场景：机会探索、竞品分析或用户材料已经有初步输入，需要收敛为 Spec 上游事实。
-> 本文回答“为谁、为什么、第一版做什么、不做什么、如何判断成功、产品能力往哪里建设、后续可能影响哪些设计资产”，不替代 Spec、业务架构、功能架构、OpenAPI 或系统 / 数据架构。
-
-## 1. 输入材料
-
-| 材料 | 路径 / 链接 | 状态 | 备注 |
-|------|-------------|------|------|
-| 机会想法 / 用户反馈 |  |  |  |
-| 竞品 / 市场分析 |  |  |  |
-| 现有系统 / 业务材料 |  |  |  |
-| 约束 / 决策 |  |  |  |
-
-## 2. 目标用户与场景
-
-| 用户 / 角色 | 核心场景 | 当前痛点 | 影响范围 |
-|-------------|----------|----------|----------|
-|  |  |  |  |
-
-## 3. 问题与机会
-
-- 问题陈述：
-- 为什么现在做：
-- 差异化机会：
-- 不做的机会：
-
-## 4. MVP 边界
-
-| 能力 | 是否进入 MVP | 理由 | 成功信号 |
-|------|---------------|------|----------|
-|  | 是 / 否 / 待定 |  |  |
-
-## 5. 非目标范围
-
-| 非目标 | 排除原因 | 后续观察条件 |
-|--------|----------|--------------|
-|  |  |  |
-
-## 6. 产品功能指引 / 能力候选
-
-> 本节用于给 Spec 和功能架构输入方向，不冻结最终功能架构或技术系统方案。
-
-| 能力候选 | 用户价值 | 优先级假设 | 是否进入 MVP | 证据 / 依据 | 下游影响 |
-|----------|----------|------------|---------------|-------------|----------|
-|  |  | P0 / P1 / P2 | 是 / 否 / 待定 |  | UI / API / 数据 / 权限 / 架构 |
-
-## 7. 下游影响清单
-
-> 只记录影响信号和待验证假设；具体方案在 Spec、产品设计、API、系统 / 数据架构和设计审查阶段收敛。
-
-| 影响域 | 是否可能影响 | 说明 | 需要进入的后续门禁 |
-|--------|--------------|------|--------------------|
-| 页面 / 交互 | 是 / 否 / 待定 |  | 产品设计 / Prototype Review |
-| OpenAPI / 契约 | 是 / 否 / 待定 |  | API 影响分析 / 契约草案 |
-| 数据模型 / 持久化 | 是 / 否 / 待定 |  | 数据架构 / Design Review |
-| 外部系统 / 集成 | 是 / 否 / 待定 |  | 系统架构 / ADR |
-| 发布 / 回滚 / 运维 | 是 / 否 / 待定 |  | 系统架构 / Release Review |
-| 高风险变更 / 人工确认项 | 是 / 否 / 待定 |  | 人工确认项 |
-
-## 8. 成功标准
-
-| 指标 / 结果 | 目标 | 验证方式 |
-|-------------|------|----------|
-|  |  |  |
-
-## 9. 风险与待澄清
-
-| 风险 / 问题 | 影响 | 处理方式 | 截止点 |
-|-------------|------|----------|--------|
-|  |  |  | Spec 前 |
-
-## 10. 完成标准
-
-- [ ] 目标用户、痛点、为什么现在做已经明确。
-- [ ] MVP 和非目标范围可直接输入 Spec。
-- [ ] 产品功能指引已经形成能力候选和优先级假设，但未替代正式功能架构。
-- [ ] 下游 UI、API、数据、权限、架构、安全影响信号已列出。
-- [ ] 成功标准可验收。
-- [ ] 业务架构需要的用户旅程、价值流、角色 / 外部系统线索已列出。
-- [ ] 需要回写 `CONTEXT.md` 的术语已标注。
-
-## 11. 下一步门禁
-
-- 结论：Approved / Blocked
-- 下一步：业务架构 / Spec / 继续 Discovery
-- 阻断项：

package/template/docs/process/maintenance-intensity.yaml

@@ -1,25 +0,0 @@
-schema_version: 1
-default_level: L2
-levels:
-  L1:
-    triggers:
-      - textual-only
-      - link-only
-      - deterministic-projection
-  L2:
-    triggers:
-      - local-rule
-      - template-structure
-      - non-core-validator
-  L3:
-    triggers:
-      - lifecycle-gate
-      - ticket-state
-      - permission-boundary
-      - generation-semantics
-      - release-semantics
-      - cross-repo-contract
-      - core-validator
-      - historical-important-escape
-      - aggregate-behavior-change
-      - release-candidate

package/template/docs/process/schemas/maintenance-review-record.schema.json

@@ -1,49 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://yss.dev/schemas/maintenance-review-record.schema.json",
-  "title": "YSS Template Maintenance Independent Review Record",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "schema_version",
-    "record_kind",
-    "review_mode",
-    "status",
-    "reviewer_id",
-    "implementation_actor_id",
-    "candidate_digest",
-    "candidate_snapshot_ref",
-    "task_package_ref",
-    "review_report_ref",
-    "reviewed_at",
-    "findings"
-  ],
-  "properties": {
-    "schema_version": { "const": 1 },
-    "record_kind": { "const": "maintenance-independent-review" },
-    "review_mode": { "enum": ["focused-independent", "formal-independent"] },
-    "status": { "enum": ["approved", "changes-requested", "blocked"] },
-    "reviewer_id": { "type": "string", "minLength": 1 },
-    "implementation_actor_id": { "type": "string", "minLength": 1 },
-    "candidate_digest": { "type": "string", "pattern": "^(sha256:)?[a-f0-9]{64}$" },
-    "candidate_snapshot_ref": { "type": "string", "minLength": 1 },
-    "task_package_ref": { "type": "string", "minLength": 1 },
-    "review_report_ref": { "type": "string", "minLength": 1 },
-    "reviewed_at": { "type": "string", "format": "date-time" },
-    "findings": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["id", "severity", "disposition", "status", "summary"],
-        "properties": {
-          "id": { "type": "string", "minLength": 1 },
-          "severity": { "enum": ["critical", "high", "medium", "low"] },
-          "disposition": { "enum": ["violation", "drift", "new_impacts", "judgement-call", "not-applicable"] },
-          "status": { "enum": ["open", "resolved", "not-applicable"] },
-          "summary": { "type": "string", "minLength": 1 }
-        }
-      }
-    }
-  }
-}

package/template/docs/process/template-engineering-overview.md

@@ -1,104 +0,0 @@
-# YSS 模板工程说明
-
-## 1. 工程定位
-
-YSS 模板工程是一套可版本化的研发治理系统。它用仓库身份、生命周期、条件门禁、工程契约、Agent skills 和可读证据，把产品研发从需求澄清连接到实现、审查、发布与复盘。
-
-本仓默认是研发管理仓库，不是前端或后端运行时工程。它维护可复用的流程规则、文档模板、技能、验证脚本和分发契约；运行时代码默认位于已登记的独立实现仓库。
-
-## 2. 首次进入时读取什么
-
-按以下顺序建立上下文：
-
-1. 读取根目录 `yss-project.yaml`，确认 `repository_mode`。
-2. 读取 `AGENTS.md`，取得当前仓库的入口规则、硬门禁和禁止事项。
-3. 读取 `CONTEXT.md`，统一领域与流程语言。
-4. 按任务读取生命周期注册表、裁剪规则、技能注册表和数字人角色注册表。
-
-完成标准：仓库身份合法，任务属于模板维护还是产品研发已经明确，影响面和下一工作单元可以由权威资产解释。
-
-## 3. 两种仓库身份
-
-| 身份 | 用途 | 允许的主要工作 | 边界 |
-|---|---|---|---|
-| `template-source` | 维护通用模板与治理规则 | 更新单一事实来源、同步技能投影、构建 CLI 快照、验证与审查 | 不生成具体产品的 Spec、原型、OpenAPI 或垂直切片 Ticket |
-| `project-instance` | 承载具体产品或模块的研发管理资产 | 执行 Discovery、Spec、设计、工程契约、Ticket、实现、验证和发布流程 | 不反向成为通用模板的权威来源 |
-
-身份只由 `yss-project.yaml` 声明。目录结构、Git remote 和占位符都不能替代该清单。
-
-## 4. Harness 产品线
-
-模板工程按研发责任边界拆成三个互不混用的 Harness 产品：
-
-| 产品线 | 模板源 | 实例化 CLI | 生命周期边界 |
-|---|---|---|---|
-| 全产品生命周期 | `yss-spec-project-template` | `create-yss-spec` | 从 Discovery 到发布与复盘 |
-| DDD 战略设计交接 | `yss-harness-design-agent` | `create-yss-harness-design` | 从机会、需求和战略设计到 Strategic Design Handoff |
-| 开发落地 | `yss-harness-dev-agent` | `create-yss-harness-dev` | 从已批准 Spec 或战略设计交接包到 Tactical Design、Slice Contract、实现与验证 |
-
-每条产品线使用独立的 profile、metadata 和固定模板 commit。CLI 之间遇到其他产品线的 metadata 时必须 fail closed，不能自动接管。
-
-## 5. 控制平面
-
-### 5.1 生命周期
-
-`docs/process/lifecycle-registry.yaml` 是阶段、门禁、产物、工作单元、证据和稳定 ID 的结构事实源。`docs/process/harness-process-tailoring.md` 决定任务从哪个可信阶段进入，以及哪些条件门禁可以记录为 `not-applicable`。
-
-生命周期编排器只推进第一个未阻塞工作单元。文件存在不等于产物已批准；完成结论必须同时具备内容、审查结论、上游新鲜度和可读取证据。
-
-### 5.2 技能供应链
-
-`.agents/skills` 是跨 Agent 共享技能的权威内容。`.claude/skills`、`.codex/skills`、`.cursor/skills`、`.pi/skills`、`.qoder/skills` 和 `.trae/skills` 是生成投影。
-
-`docs/agents/yss-skill-registry.yaml` 管理技能分层、成熟度、别名和运行时发现；`skills-lock.json` 管理来源、版本、hash 与投影完整性。修改共享技能后必须同步投影并更新 lock，不能分别编辑平台副本。
-
-### 5.3 数字人协作
-
-`docs/agents/digital-human-roles.yaml` 定义数字人角色、运行时绑定、阶段协作组和会签策略。角色叠加在生命周期编排器上，不形成第二套生命周期；实现者与独立审查者必须是不同实例。
-
-正式派发使用结构化任务包，任务包声明角色、运行时、合同、允许写路径、预期证据和汇合条件。共享工作区不替代写入边界。
-
-## 6. 模板源与实例分发边界
-
-模板实例分发面包含根规则、`CONTEXT.md`、共享 skills、`docs/` 中的实例流程资产和共享验证脚本。CLI 从固定模板 commit 构建 bundled snapshot，并在 metadata 中保存模板身份和版本。
-
-`.template-source/` 是模板源治理区，保存维护证据、研究记录、源仓 ADR、跨仓契约、发布路线和模板源 Wiki。该目录不进入 `project-instance`，避免把模板维护历史误当成产品研发资产。
-
-## 7. 模板维护工作流
-
-1. **分级**：根据 `docs/process/maintenance-intensity.yaml` 计算 L1、L2 或 L3；未知 trigger 先更新策略。
-2. **更新权威资产**：修改对应的单一事实来源，避免在说明文档中复制规则。
-3. **生成投影**：涉及 skills 时同步 Agent roots 和 `skills-lock.json`；涉及生命周期结构时同步派生视图；涉及实例分发时构建固定 commit 的 CLI 快照。
-4. **Fresh verification**：实现内循环执行 `scripts/verify-template-fast` 并默认停在 `implementation-ready`；准备审查时执行 candidate 核验和首次完整 `scripts/verify-template`，跨仓 CLI 还要执行固定 commit 的集成测试和打包校验。
-5. **审查与发布**：L2 按需使用聚焦独立审查；L3 日常记录维护者自检，不冻结候选、不派发正式独立审查。正式发布前仍执行一次完整 `scripts/verify-template`。
-6. **发布与回滚**：先发布或提交子仓，再更新父仓 gitlink；跨仓版本、验证命令、发布顺序和回滚点必须可以重建。
-
-完成标准：当前强度要求的自检 / 审查证据通过，跨仓固定引用闭合，正式发布前完整 `scripts/verify-template` 通过，并且不存在未处理的 `violation`、`drift` 或 `new_impacts`。
-
-## 8. 常用入口
-
-| 目标 | 入口 |
-|---|---|
-| 判断仓库身份和下一阶段 | `yss-product-lifecycle` |
-| 修改或退役共享 skill | `maintaining-skills` |
-| 模板实现内循环 | `scripts/verify-template-fast` |
-| 准备模板审查候选 | `scripts/verify-template-candidate`、`scripts/prepare-maintenance-review` |
-| 校验根模板发布候选 | `scripts/verify-template` |
-| 同步共享 skill 投影 | `scripts/sync-skills` |
-| 校验 skills lock | `scripts/update-skill-lock --check` |
-| 校验生命周期注册表 | `scripts/verify-lifecycle-registry` |
-| 校验维护 checkpoint | `scripts/verify-maintenance-checkpoint <file>` |
-
-## 9. 权威阅读地图
-
-| 问题 | 权威资产 |
-|---|---|
-| 仓库是什么 | `yss-project.yaml`、`AGENTS.md` |
-| 统一语言是什么 | `CONTEXT.md` |
-| 阶段、门禁和工作单元是什么 | `docs/process/lifecycle-registry.yaml` |
-| 如何裁剪流程和判定维护强度 | `docs/process/harness-process-tailoring.md`、`docs/process/maintenance-intensity.yaml` |
-| skills 如何发现与校验 | `docs/agents/yss-skill-registry.yaml`、`skills-lock.json` |
-| 数字人如何协作和会签 | `docs/agents/digital-human-roles.yaml` |
-| 实现仓库如何接入 | `docs/process/implementation-repo-integration.md` |
-
-说明文档负责导航和解释；当说明与权威资产冲突时，以表中权威资产为准，并修复说明文档的漂移。