create-yss-spec 3.0.1 → 3.1.3

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/instantiate-harness

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Repository-local distribution for the two dedicated Harness templates.
+import { existsSync, readFileSync, mkdirSync, mkdtempSync, renameSync, rmSync, statSync, lstatSync, readlinkSync, realpathSync, symlinkSync, chmodSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { ROOT, read, safe, ensure, hash, digest, write, json } from './lib/strategic-handoff-io.mjs';
+
+try {
+  const args=process.argv.slice(2),options={};
+  while(args.length) {
+    const key=args.shift();
+    if(key==='--allow-working-tree')options.working=true;
+    else if(['--target','--project-name'].includes(key)) {ensure(args.length&&!args[0].startsWith('--'),`${key} 缺少值`);options[key.slice(2)]=args.shift();}
+    else throw new Error(`未知参数 ${key}；使用 --target <新目录> [--project-name <名称>]`);
+  }
+  ensure(options.target,'必须指定 --target <新目录>');
+  const identity=read(safe(ROOT,'yss-project.yaml'));
+  ensure(identity.schema_version===1&&identity.repository_mode==='template-source','仅模板源可初始化新项目');
+  const profile=read(safe(ROOT,'docs/process/harness-profile.yaml'));
+  ensure(['harness.backend-delivery','harness.frontend-delivery'].includes(profile.profile_id),'仅支持后端/前端专职模板');
+  const target=path.resolve(options.target);
+  ensure(!target.startsWith(ROOT+path.sep)&&!ROOT.startsWith(target+path.sep)&&target!==ROOT,'目标不得包含模板源或位于模板源内');
+  ensure(!existsSync(target),'目标已存在；不覆盖或静默转换既有项目 profile');
+  const git=args=>execFileSync('git',args,{cwd:ROOT,encoding:'utf8',maxBuffer:16*1024*1024}).trim();
+  const commit=git(['rev-parse','HEAD']);
+  ensure(/^[0-9a-f]{40}$/.test(commit),'模板必须有不可变 Git 提交');
+  const dirty=Boolean(git(['status','--porcelain','--untracked-files=all']));
+  ensure(!dirty||options.working,'模板工作树未提交；维护测试可显式使用 --allow-working-tree，正式分发须先提交');
+  const manifest=read(safe(ROOT,profile.instantiation.distribution_manifest));
+  const names=execFileSync('git',['ls-files','-co','--exclude-standard','-z'],{cwd:ROOT,encoding:'utf8',maxBuffer:16*1024*1024}).split('\0').filter(Boolean);
+  const prefix=(ref,base)=>ref===base||ref.startsWith(base+'/');
+  const selected=[...new Set(names)].filter(ref=>{
+    const top=ref.split('/')[0];
+    const allowed=(manifest.allowRootEntries||[]).includes(top)||(manifest.allowRootFiles||[]).includes(ref)||(manifest.allowFiles||[]).includes(ref);
+    return allowed&&![...(manifest.excludeRootEntries||[]),...(manifest.initExcludeRootEntries||[])].includes(top)
+      &&![...(manifest.excludeRootFiles||[]),...(manifest.initExcludeRootFiles||[])].includes(ref)
+      &&![...(manifest.excludePaths||[]),...(manifest.initExcludePaths||[])].some(excluded=>prefix(ref,excluded));
+  }).sort();
+  ensure(selected.includes('yss-project.yaml')&&selected.includes('AGENTS.md')&&selected.includes('CONTEXT.md'),'分发缺少入口合同');
+  const capture=ref=>{
+    const file=path.join(ROOT,ref);if(path.dirname(ref)!=='.')safe(ROOT,path.dirname(ref));
+    if(lstatSync(file).isSymbolicLink()) {
+      const link=readlinkSync(file),resolved=realpathSync(file);
+      ensure(!path.isAbsolute(link)&&resolved.startsWith(path.join(ROOT,'.agents/skills')+path.sep),'仅允许指向本仓 canonical skills 的相对投影链接');
+      return {ref,link,bytes:Buffer.from(`symlink:${link}`),mode:0o777};
+    }
+    return {ref,bytes:readFileSync(safe(ROOT,ref)),mode:statSync(file).mode&0o777};
+  };
+  const captured=selected.map(capture);
+  const sourceFiles=captured.map(({ref,bytes,mode})=>({ref,digest:hash(bytes),mode}));
+  const sourceDigest=digest(sourceFiles);
+  mkdirSync(path.dirname(target),{recursive:true});
+  const staging=mkdtempSync(path.join(path.dirname(target),'.harness-init-'));
+  try {
+    const managed={};
+    for(const file of captured) {
+      let bytes=file.bytes;
+      if(file.ref==='yss-project.yaml') bytes=Buffer.from('schema_version: 1\nrepository_mode: project-instance\n');
+      if(file.ref==='README.md') bytes=Buffer.from(`# ${options['project-name']||path.basename(target)}\n\n本仓是 \`${profile.profile_id}\` 的 \`project-instance\`。先读 [AGENTS.md](AGENTS.md)、根 CONTEXT.md 与 [profile](docs/process/harness-profile.yaml)。接力输入与执行条件见 [交付合同](docs/process/frontend-backend-delivery.md)。\n`);
+      if(file.link) {mkdirSync(path.dirname(path.join(staging,file.ref)),{recursive:true});symlinkSync(file.link,path.join(staging,file.ref));}
+      else {write(staging,file.ref,bytes);chmodSync(path.join(staging,file.ref),file.mode);}
+      managed[file.ref]={digest:hash(bytes),mode:file.mode};
+    }
+    write(staging,profile.instantiation.metadata_file,json({schema_version:1,profile_id:profile.profile_id,template_source:profile.instantiation.template_source,template_commit:commit,source_tree_digest:sourceDigest,source_files:sourceFiles,source_working_tree:dirty,release_snapshot:!dirty,managed_files:managed}));
+    for(const {ref,bytes} of captured)ensure(hash(capture(ref).bytes)===hash(bytes),`初始化期间模板变化: ${ref}`);
+    ensure(!existsSync(target),'目标目录并发冲突');renameSync(staging,target);
+    process.stdout.write(json({result:'initialized',profile_id:profile.profile_id,target,template_commit:commit,source_tree_digest:sourceDigest,release_snapshot:!dirty}));
+  } finally {rmSync(staging,{recursive:true,force:true});}
+} catch(error) {process.stderr.write(`${error.message}\n`);process.exitCode=1;}