create-yss-spec 3.0.0 → 3.1.0

package/template/scripts/fixtures/strategic-handoff/source-roles.json

@@ -0,0 +1,528 @@
+{
+  "schema_version": 1,
+  "registry_id": "yss.digital-human-roles",
+  "status": "active",
+  "description": "数字人角色、主控、阶段协作组、技能启用/禁止与生命周期会签的单一事实源。 角色配置与运行时无关；Claude / Cursor / Codex / Grok 等只通过 runtimes 绑定。 Ticket 五态不是数字人角色。",
+  "canonical_path": "docs/agents/digital-human-roles.yaml",
+  "runtime_policy": {
+    "overlay_on_lifecycle": true,
+    "consumed_by_lifecycle": true,
+    "git_is_ssot": true,
+    "default_invocation": "orchestrator",
+    "dispatch": "orchestrator-one-to-one",
+    "per_feature_instances": "forbidden",
+    "project_instance_instantiation": "duplicate-and-bind-repo-path",
+    "template_instantiation": "publish-singleton-profiles",
+    "biological_veto": true,
+    "implementer_must_differ": true,
+    "write_isolation": "task-package-policy",
+    "dual_hat_split_when": [
+      "cross-repo-load",
+      "responsibility-conflict"
+    ]
+  },
+  "runtimes": [
+    {
+      "id": "runtime.generic",
+      "kind": "generic",
+      "instance_kind": "agent-session",
+      "skill_root": null,
+      "covers_skill_registry_roots": false,
+      "collaboration": "task-package-and-handoff",
+      "max_collaboration_group_size": null,
+      "overflow": "not-applicable",
+      "shared_workspace_is_not_security_boundary": false,
+      "side_effect_approval": "biological-human",
+      "notes": "任何能加载 core_skills 并接受任务包的 Agent 会话。"
+    },
+    {
+      "id": "runtime.skill-projection",
+      "kind": "projected-agent-root",
+      "instance_kind": "agent-session-or-subagent",
+      "skill_root": "from-skill-registry",
+      "covers_skill_registry_roots": true,
+      "collaboration": "subagent-task-package",
+      "max_collaboration_group_size": null,
+      "overflow": "not-applicable",
+      "shared_workspace_is_not_security_boundary": false,
+      "side_effect_approval": "biological-human",
+      "notes": "覆盖 docs/agents/yss-skill-registry.yaml 的 agent_runtime_roots （claude / codex / cursor / pi / qoder / trae）。 技能仍从 .agents/skills 投影，不按职称再维护一份。"
+    },
+    {
+      "id": "runtime.grok",
+      "kind": "grok-bot",
+      "instance_kind": "durable-bot",
+      "skill_root": null,
+      "covers_skill_registry_roots": false,
+      "collaboration": "group-chat-or-async-dm",
+      "max_collaboration_group_size": 6,
+      "min_collaboration_group_size": 2,
+      "overflow": "one-to-one-handoff",
+      "shared_workspace_is_not_security_boundary": true,
+      "side_effect_approval": "biological-human",
+      "notes": "Grok Bot 适配。群聊 2–6 人；超出则改 1:1 交接，不改逻辑阶段协作组。 全部 Bot 共享云计算机，写范围只靠任务包。不新增 agent_runtime_roots.grok。"
+    }
+  ],
+  "orchestrator": {
+    "id": "role.lifecycle-orchestrator",
+    "name": "主控数字人",
+    "kind": "orchestrator",
+    "title": "YSS 生命周期主控",
+    "default_dual_hat": [
+      "role.project-manager"
+    ],
+    "stages": [
+      "stage.entry-triage",
+      "stage.discovery",
+      "stage.spec-architecture",
+      "stage.product-design",
+      "stage.system-data-engineering",
+      "stage.ticket-formalization",
+      "stage.vertical-slice-implementation",
+      "stage.verification-release-retrospective"
+    ],
+    "core_skills": [
+      "yss-product-lifecycle",
+      "yss-implementation-contract-compiler"
+    ],
+    "forbidden_skills": [
+      "yss-domain",
+      "yss-ui",
+      "yss-ui-business-page-generation",
+      "yss-web-controller",
+      "yss-repository",
+      "implement"
+    ],
+    "description": "Own YSS lifecycle routing. Read yss-project.yaml and CONTEXT.md first. Select the next unblocked work unit, compile a task package, and assign one owner per stage. Do not implement business code. Do not approve Slice contracts into ready-for-agent without the full formula. Do not announce releasable. Default dual-hat: project manager until a separate instance is required. Authoritative artifacts live in git."
+  },
+  "roles": [
+    {
+      "id": "role.requirements-manager",
+      "name": "需求经理",
+      "kind": "digital-human",
+      "contract_version": 1,
+      "title": "YSS 需求经理",
+      "stages": [
+        "stage.discovery",
+        "stage.spec-architecture"
+      ],
+      "draft_artifact_ids": [
+        "artifact.discovery-record",
+        "artifact.spec"
+      ],
+      "core_skills": [
+        "grilling",
+        "domain-modeling",
+        "yss-research",
+        "competitive-intelligence",
+        "grill-with-docs"
+      ],
+      "forbidden_skills": [
+        "yss-ui",
+        "yss-domain",
+        "yss-web-controller",
+        "yss-repository",
+        "yss-ddd-scaffold-generator",
+        "yss-layered-mvc-scaffold-generator",
+        "yss-frontend-scaffold-generator",
+        "implement",
+        "tdd"
+      ],
+      "description": "Own Discovery language, users, MVP, non-goals, success criteria, test seams, and Spec prose. Propose CONTEXT.md glossary entries. Do not freeze visual prototypes, OpenAPI, or code. Do not guess unconfirmed business rules. Hand off to the orchestrator when the frontier is empty."
+    },
+    {
+      "id": "role.product-manager",
+      "name": "产品经理",
+      "kind": "digital-human",
+      "contract_version": 1,
+      "title": "YSS 产品经理",
+      "stages": [
+        "stage.discovery",
+        "stage.spec-architecture",
+        "stage.product-design",
+        "stage.verification-release-retrospective"
+      ],
+      "draft_artifact_ids": [
+        "artifact.product-overview",
+        "artifact.functional-architecture",
+        "artifact.interaction-spec",
+        "artifact.state-matrix",
+        "artifact.prototype-confirmation"
+      ],
+      "core_skills": [
+        "yss-design-system",
+        "yss-prototype-stage",
+        "prototype-review",
+        "yss-antdv-next-design",
+        "yss-research",
+        "competitive-intelligence"
+      ],
+      "forbidden_skills": [
+        "yss-ui",
+        "yss-domain",
+        "yss-repository",
+        "yss-web-controller",
+        "yss-ddd-scaffold-generator",
+        "yss-layered-mvc-scaffold-generator",
+        "implement",
+        "tdd"
+      ],
+      "description": "Own priority, product-design impact, interaction, state matrix, prototype confirmation recommendation, and the commercial constraints, delivery commitments, release window, and commercial non-goals for Discovery and release. May reject Spec scope. Do not write production code or freeze OpenAPI alone. Do not independently approve external commercial contracts or formal commitments; those require biological-human approval. Frontend implementation uses the frontend-engineer role and yss-ui, not yss-antdv-next-design. Explicit React/AntD compatibility prototypes use yss-antd-design conditionally."
+    },
+    {
+      "id": "role.project-manager",
+      "name": "项目经理",
+      "kind": "digital-human",
+      "contract_version": 1,
+      "title": "YSS 项目经理",
+      "stages": [
+        "stage.entry-triage",
+        "stage.discovery",
+        "stage.spec-architecture",
+        "stage.product-design",
+        "stage.system-data-engineering",
+        "stage.ticket-formalization",
+        "stage.vertical-slice-implementation",
+        "stage.verification-release-retrospective"
+      ],
+      "draft_artifact_ids": [
+        "artifact.parent-ticket",
+        "artifact.vertical-slice-ticket"
+      ],
+      "core_skills": [
+        "yss-product-lifecycle",
+        "handoff",
+        "implementation-repo-onboarding",
+        "cross-repo-implementation-routing"
+      ],
+      "forbidden_skills": [
+        "yss-domain",
+        "yss-ui",
+        "implement",
+        "tdd",
+        "yss-web-controller"
+      ],
+      "description": "Own parent Ticket hygiene, checkpoints, handoff, risk, and implementation repo registry. Do not set ready-for-agent; the orchestrator recomputes that formula. Do not approve Spec or OpenAPI Freeze. Do not write business code or serve as independent Reviewer. Default dual-hat on the orchestrator instance until dual_hat_split_when (cross-repo-load or responsibility-conflict) requires a separate instance."
+    },
+    {
+      "id": "role.frontend-engineer",
+      "name": "前端工程师",
+      "kind": "digital-human",
+      "contract_version": 1,
+      "title": "YSS 前端工程师",
+      "stages": [
+        "stage.product-design",
+        "stage.system-data-engineering",
+        "stage.ticket-formalization",
+        "stage.vertical-slice-implementation",
+        "stage.verification-release-retrospective"
+      ],
+      "draft_artifact_ids": [
+        "artifact.frontend-implementation-plan"
+      ],
+      "core_skills": [
+        "yss-ui",
+        "yss-ui-business-page-generation",
+        "yss-components",
+        "yss-formily",
+        "formily-foundation",
+        "formily-linkage-effects",
+        "formily-mode-slot-detail",
+        "formily-step-flow",
+        "ytable-usage",
+        "ytree-usage",
+        "yedit-table-usage",
+        "yss-api-integration",
+        "yss-hook",
+        "theme-token-usage",
+        "page-skeleton",
+        "page-list-module",
+        "page-form-module",
+        "component-selection-imports",
+        "vue3-best-practices",
+        "tdd"
+      ],
+      "forbidden_skills": [
+        "yss-domain",
+        "yss-application",
+        "yss-repository",
+        "yss-mybatis",
+        "yss-web-controller",
+        "yss-ddd-scaffold-generator",
+        "yss-layered-mvc-scaffold-generator",
+        "java-backend-commit"
+      ],
+      "description": "Own Vue page modules, frontend tests, and frontend_implementation_plan. Review OpenAPI Draft for client fit and prototype feasibility. Write only contract-allowed frontend paths. Verify with pnpm. Do not freeze API, own backend domain, or countersign your own merge."
+    },
+    {
+      "id": "role.backend-engineer",
+      "name": "后端工程师",
+      "kind": "digital-human",
+      "contract_version": 1,
+      "title": "YSS 后端工程师",
+      "stages": [
+        "stage.system-data-engineering",
+        "stage.ticket-formalization",
+        "stage.vertical-slice-implementation",
+        "stage.verification-release-retrospective"
+      ],
+      "draft_artifact_ids": [
+        "artifact.openapi-draft",
+        "artifact.data-architecture"
+      ],
+      "core_skills": [
+        "yss-implementation-contract-compiler",
+        "yss-tactical-design",
+        "yss-domain",
+        "yss-application",
+        "yss-repository",
+        "yss-mybatis",
+        "yss-web-controller",
+        "yss-dto",
+        "mapstruct",
+        "lombok",
+        "alibaba-java-code-style",
+        "yss-exception",
+        "yss-validation",
+        "tdd",
+        "yss-ddd-scaffold-generator",
+        "yss-layered-mvc-scaffold-generator"
+      ],
+      "forbidden_skills": [
+        "yss-ui",
+        "yss-ui-business-page-generation",
+        "yss-formily",
+        "yss-frontend-scaffold-generator",
+        "yss-antd-design",
+        "yss-antdv-next-design",
+        "page-list-module",
+        "page-form-module"
+      ],
+      "description": "Own OpenAPI Draft, data-architecture contributions, and backend tests. Write only contract-allowed backend paths. Verify with ./mvnw. Do not Freeze OpenAPI, treat UI copy as requirements, or countersign your own implementation."
+    },
+    {
+      "id": "role.test-engineer",
+      "name": "测试工程师",
+      "kind": "digital-human",
+      "contract_version": 1,
+      "title": "YSS 测试工程师",
+      "stages": [
+        "stage.spec-architecture",
+        "stage.vertical-slice-implementation",
+        "stage.verification-release-retrospective"
+      ],
+      "draft_artifact_ids": [
+        "artifact.frontend-implementation-verification"
+      ],
+      "owned_evidence_ids": [
+        "evidence.fresh-verification",
+        "evidence.frontend-implementation-verification"
+      ],
+      "core_skills": [
+        "tdd",
+        "diagnosing-bugs",
+        "code-review",
+        "alibaba-java-code-style",
+        "yss-ui",
+        "yss-design-system",
+        "yss-ui-business-page-generation",
+        "yss-domain",
+        "yss-application",
+        "yss-repository",
+        "yss-web-controller",
+        "yss-dto",
+        "mapstruct",
+        "lombok"
+      ],
+      "forbidden_skills": [
+        "yss-ddd-scaffold-generator",
+        "yss-layered-mvc-scaffold-generator",
+        "yss-frontend-scaffold-generator",
+        "implement",
+        "to-spec"
+      ],
+      "description": "Own test code, defect records, fresh verification, and frontend implementation verification evidence. Review every implementation slice through the unique code-review skill, loading YSS and Alibaba specialist skills as read-only Standards sources. Recommend release readiness; do not close gate.release-ready. Do not change product scope or write feature implementation. Must be a different instance from the implementer."
+    }
+  ],
+  "stage_groups": [
+    {
+      "id": "group.discovery",
+      "name": "Discovery",
+      "stage": "stage.discovery",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.requirements-manager",
+        "role.product-manager"
+      ]
+    },
+    {
+      "id": "group.spec",
+      "name": "Spec",
+      "stage": "stage.spec-architecture",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.requirements-manager",
+        "role.product-manager",
+        "role.test-engineer"
+      ]
+    },
+    {
+      "id": "group.product-design",
+      "name": "产品设计",
+      "stage": "stage.product-design",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.product-manager",
+        "role.requirements-manager",
+        "role.frontend-engineer"
+      ]
+    },
+    {
+      "id": "group.contract",
+      "name": "契约",
+      "stage": "stage.system-data-engineering",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.backend-engineer",
+        "role.frontend-engineer",
+        "role.test-engineer",
+        "role.product-manager"
+      ]
+    },
+    {
+      "id": "group.tickets",
+      "name": "Ticket 正式化",
+      "stage": "stage.ticket-formalization",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.project-manager",
+        "role.frontend-engineer",
+        "role.backend-engineer",
+        "role.test-engineer"
+      ]
+    },
+    {
+      "id": "group.implementation",
+      "name": "实现",
+      "stage": "stage.vertical-slice-implementation",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.frontend-engineer",
+        "role.backend-engineer",
+        "role.test-engineer"
+      ]
+    },
+    {
+      "id": "group.release",
+      "name": "发布",
+      "stage": "stage.verification-release-retrospective",
+      "members": [
+        "role.lifecycle-orchestrator",
+        "role.project-manager",
+        "role.test-engineer",
+        "role.product-manager"
+      ]
+    }
+  ],
+  "gate_policy": {
+    "default_if_unlisted": "biological-human",
+    "unlisted_kept_biological": [
+      "gate.design-reviewed",
+      "gate.architecture-reviewed"
+    ],
+    "evidence_only": [
+      "gate.repository-identity-valid",
+      "gate.prototype-verified"
+    ],
+    "orchestrator": [
+      "gate.slice-contract-approved",
+      "gate.slice-ready-for-agent"
+    ],
+    "digital_human_review": [
+      {
+        "gate": "gate.prototype-reviewed",
+        "drafter": "role.product-manager",
+        "countersigners": [
+          "role.frontend-engineer"
+        ]
+      },
+      {
+        "gate": "gate.openapi-draft-reviewed",
+        "drafter": "role.backend-engineer",
+        "countersigners": [
+          "role.frontend-engineer"
+        ]
+      },
+      {
+        "gate": "gate.engineering-baseline-accepted",
+        "countersigners": [
+          "role.test-engineer"
+        ]
+      },
+      {
+        "gate": "gate.frontend-implementation-verified",
+        "drafter": "role.frontend-engineer",
+        "countersigners": [
+          "role.test-engineer"
+        ]
+      }
+    ],
+    "digital_human_review_work_units": [
+      {
+        "work_unit": "work-unit.code-review",
+        "countersigners": [
+          "role.test-engineer"
+        ],
+        "implementer_must_differ": true
+      }
+    ],
+    "dual_digital_human": [
+      {
+        "gate": "gate.spec-baseline-approved",
+        "drafter": "role.requirements-manager",
+        "countersigners": [
+          "role.product-manager"
+        ]
+      },
+      {
+        "gate": "gate.domain-strategy-approved",
+        "drafter": "role.requirements-manager",
+        "countersigners": [
+          "role.product-manager"
+        ]
+      },
+      {
+        "gate": "gate.stage-decision-package-approved",
+        "drafter": "role.requirements-manager",
+        "countersigners": [
+          "role.product-manager"
+        ]
+      },
+      {
+        "gate": "gate.openapi-frozen",
+        "drafter": "role.backend-engineer",
+        "countersigners": [
+          "role.product-manager",
+          "role.test-engineer"
+        ]
+      }
+    ],
+    "product_digital_human_with_biological_veto": [
+      "gate.user-confirmation"
+    ],
+    "biological_human": [
+      "gate.release-ready"
+    ],
+    "runtime_side_effect_approval": "biological-human",
+    "commercial_contract": "biological-human"
+  },
+  "user_decision_policy": {
+    "gates": [],
+    "work_units": {},
+    "source_kinds": [
+      "platform-message",
+      "session-export",
+      "user-confirmation-file"
+    ]
+  }
+}

package/template/scripts/fixtures/user-decision/build-fixture.mjs

@@ -0,0 +1,61 @@
+// Synthetic sources for tests only. Never use these helpers to record a real user's approval.
+import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { decisionDigest, requestDigest, renderDecisionRequest } from "../../lib/user-decision.mjs";
+export function buildDecisionFixture(root, { boundary = "gate.spec-baseline-approved", scope = ["feature.demo"], subjectRef, subjectContent = "冻结业务基线 v1\n", extraItems = [] } = {}) {
+  mkdirSync(root, { recursive: true });
+  const write = (name, value) => {
+    const ref = path.join(root, name);
+    writeFileSync(ref, typeof value === "string" ? value : JSON.stringify(value, null, 2));
+    return ref;
+  };
+  const subject = subjectRef || write("subject.md", subjectContent);
+  const capture = (name, principal, actor, sentAt, text, kind = "session-export", replyTo = null) => {
+    const value = { source_kind: kind, messages: [{ id: name, principal_ref: principal, actor_kind: actor, sent_at: sentAt, text, ...(replyTo ? { reply_to: replyTo } : {}), original_ref: `test-only://${name}` }] };
+    const ref = write(`${name}.json`, value);
+    return { kind, ref, digest: decisionDigest(readFileSync(ref)), message_id: name };
+  };
+  const record = { schema_version: 1, kind: "user-decision", request: {
+    id: "request.demo", requester_ref: "person.requester",
+    requester_source: capture("requester", "person.requester", "biological-human", "2026-09-05T01:00:00Z", "请整理可审阅的功能方案。"),
+    items: [{ id: "decision.demo", boundary, title: "确认本次范围", subject: { ref: subject, version: "v1", digest: decisionDigest(readFileSync(subject)) }, basis: [], scope, changes: "新增已列明范围", risks: [], recommendation: "批准上述范围", next_actions: ["进入下一工作单元"], responder_ref: "person.requester" }, ...extraItems],
+  }, responses: [] };
+  const present = () => { record.request.presented_source = capture("presentation", "agent.orchestrator", "digital-human", "2026-09-05T01:02:00Z", renderDecisionRequest(record.request)); };
+  present();
+  const respond = ({ principal = "person.requester", actor = "biological-human", text = "同意", decision = "approved", selection = record.request.items.length === 1 ? "single" : "explicit-all", itemIds = record.request.items.map((item) => item.id), approvedScope = record.request.items.flatMap((item) => item.scope), time = "2026-09-05T01:03:00Z", name = `reply-${record.responses.length}` } = {}) => {
+    record.responses.push({ source: capture(name, principal, actor, time, text, "session-export", JSON.parse(readFileSync(record.request.presented_source.ref, "utf8")).messages[0].original_ref), principal_ref: principal, responded_at: time, text, request_digest: requestDigest(record.request), selection, item_ids: itemIds, decision, approved_scope: approvedScope });
+  };
+  respond({ text: extraItems.length ? "同意以上全部事项" : "同意" });
+  const ref = path.join(root, "decision.json");
+  const save = () => writeFileSync(ref, JSON.stringify(record, null, 2));
+  save();
+  return { record, ref, save, write, capture, present, respond, requirement: { boundary, subject_ref: subject, scope: [...scope], user_decision_ref: ref } };
+}
+export function buildImplementationFixture(root, ticketRef) {
+  mkdirSync(root, { recursive: true });
+  const baselineRef = path.join(root, "engineering-baseline.md");
+  const contractRef = path.join(root, "slice-contract.json");
+  const scopeRef = path.join(root, "implementation-scope.json");
+  writeFileSync(baselineRef, "已采纳工程基线 v1\n");
+  const contract = { lifecycle_refs: { ticket: ticketRef, engineering_baseline: baselineRef }, common: { project_roots: ["external/demo"], allowed_write_paths: ["src/demo/**"] } };
+  writeFileSync(contractRef, JSON.stringify(contract));
+  const asset = (ref) => ({ ref, version: "v1", digest: decisionDigest(readFileSync(ref)) });
+  writeFileSync(scopeRef, JSON.stringify({ kind: "implementation-scope", slices: [{ ticket_ref: ticketRef, contract: asset(contractRef), repositories: contract.common.project_roots, allowed_write_paths: contract.common.allowed_write_paths, baselines: [asset(baselineRef)] }] }));
+  const fixture = buildDecisionFixture(root, { boundary: "implementation-scope", scope: [ticketRef], subjectRef: scopeRef });
+  return { ...fixture, state: { slice_contract_ref: contractRef, vertical_slice_ticket_ref: ticketRef, user_decisions: [fixture.requirement] } };
+}
+
+export function attachScaffoldDecisionFixture(root, decision) {
+  mkdirSync(root, { recursive: true });
+  const { user_confirmation, status, decision_inputs_digest, ...snapshot } = decision;
+  const snapshotRef = path.join(root, "scaffold-inputs.json");
+  writeFileSync(snapshotRef, JSON.stringify(snapshot));
+  const f = buildDecisionFixture(root, { boundary: "scaffold-choice", subjectRef: snapshotRef, scope: [decision.project_id, decision.confirmed_architecture, decision.decision_inputs_digest] });
+  return { ...decision, user_confirmation: { ...user_confirmation, user_decision_ref: f.ref, decision_subject_ref: snapshotRef } };
+}
+if (process.argv[2] === "--scaffold") {
+  const file = process.argv[3];
+  const value = JSON.parse(readFileSync(file, "utf8"));
+  value.decisions = value.decisions.map((decision) => attachScaffoldDecisionFixture(path.join(path.dirname(file), `user-decision-${decision.project_id}`), decision));
+  writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+}

package/template/scripts/generate-yss-skill-boundaries

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { loadCompilerContract } from "./lib/implementation-contract-compiler.mjs";
+import { loadSkillRegistry } from "./lib/skill-registry.mjs";
+import { ROOT } from "./lib/skill-supply-chain.mjs";
+import path from "node:path";
+
+const target = path.join(ROOT, ".agents/skills/yss-implementation-contract-compiler/references/boundaries.md");
+const registry = loadSkillRegistry();
+const compiler = loadCompilerContract();
+
+const lines = [
+  "# YSS Skill Boundaries",
+  "",
+  "> Generated by `scripts/generate-yss-skill-boundaries` from `docs/agents/yss-skill-registry.yaml` and `compiler-contract.yaml`. Do not hand-edit.",
+  "",
+  "实现入口先选择 capability 或窄 Recipe，再由实现合同编译器计算最小 skill 闭包。下面是派生阅读视图，不是第二套路由事实源。",
+  "",
+  "## Dependency Semantics",
+  "",
+  "| Type | Compiler behavior |",
+  "| --- | --- |",
+  "| `context-required` | 自动递归加入执行上下文。 |",
+  "| `context-conditional` | 仅当显式 condition 命中时递归加入。 |",
+  "| `coordination-only` | 记录协作原因，不扩张执行上下文。 |",
+  "| `review-only` | 仅作为审查输入记录，不扩张实现上下文。 |",
+  "| `component-dependency` | 记录组件关系；由 capability/Recipe 显式选择，不自动加载。 |",
+  "",
+  "## Capability Catalog",
+  "",
+  "| Capability | Primary skill | Task modes |",
+  "| --- | --- | --- |",
+  ...registry.capabilities.map((item) => `| \`${item.id}\` | \`${item.primary_skill}\` | ${item.task_modes.map((mode) => `\`${mode}\``).join(", ")} |`),
+  "",
+  "## Narrow Recipes",
+  "",
+  "一个切片可以组合多个 Recipe，但只计算一次闭包。Recipe 仅引用 capability。",
+  "",
+  "| Recipe | Capabilities |",
+  "| --- | --- |",
+  ...registry.recipes.map((item) => `| \`${item.id}\` | ${item.capabilities.map((capability) => `\`${capability}\``).join(", ")} |`),
+  "",
+  "## Impact Entry Mapping",
+  "",
+  "| Impact | Entry capabilities |",
+  "| --- | --- |",
+  ...Object.entries(compiler.impact_to_capabilities).map(([impact, capabilities]) => `| \`${impact}\` | ${capabilities.map((capability) => `\`${capability}\``).join(", ")} |`),
+  "",
+  "## Typed Skill Dependencies",
+  "",
+  "| Skill | Dependency | Type | Condition |",
+  "| --- | --- | --- | --- |",
+  ...Object.entries(registry.skill_dependencies).flatMap(([skill, dependencies]) => dependencies.map((dependency) => `| \`${skill}\` | \`${dependency.skill}\` | \`${dependency.type}\` | ${dependency.when ? `\`${dependency.when}\`` : "—"} |`)),
+  ""
+];
+
+const expected = lines.join("\n");
+if (process.argv.includes("--check")) {
+  const actual = readFileSync(target, "utf8");
+  if (actual !== expected) {
+    process.stderr.write("boundaries.md 与 Registry/Compiler 合同不一致；运行 scripts/generate-yss-skill-boundaries\n");
+    process.exitCode = 1;
+  } else process.stdout.write("YSS skill boundaries are current\n");
+} else {
+  writeFileSync(target, expected);
+  process.stdout.write("generated YSS skill boundaries\n");
+}