create-yss-spec 3.3.4 → 3.3.7

package/template/.pi/skills/yss-stage-decision/tests/fixtures/valid-stage-decision-package.yaml

@@ -1,16 +1,41 @@
-schema_version: 2
+schema_version: 3
 stage_decision_id: stage-decision.supplier-admission
-package_version: v2
+package_version: v3
 status: approved
 problem_statement: 合规准入决定分散，采购无法稳定判断当前有效资格。
 target_users: [采购专员、合规专员]
 mvp: [提交供应商申请、合规准入决定、采购侧有效性校验]
 non_goals: [供应商结算、采购付款、通用工作流平台]
-success_criteria: [新采购订单 100% 校验当前有效准入决定]
-test_seams: [supplier-application-submit, admission-validity-check]
-confirmed_decisions: [ComplianceReview 拥有准入规则语义，ProcurementExecution 只消费决定]
-assumptions: [供应商已有唯一 subject_ref]
-constraints: [保留现有采购订单流程]
+success_criteria:
+  - id: success-criterion.current-admission
+    statement: 新采购订单 100% 校验当前有效准入决定。
+    source_refs: [rule.current-admission-required]
+    evidence_refs: [evidence.discovery.compliance]
+    status: confirmed
+test_seams:
+  - id: test-seam.admission-validity-check
+    statement: admission-validity-check
+    source_refs: [scenario.admission-expires, invariant.current-admission-required]
+    evidence_refs: [evidence.discovery.compliance]
+    status: confirmed
+confirmed_decisions:
+  - id: decision.compliance-owns-admission-rules
+    statement: ComplianceReview 拥有准入规则语义，ProcurementExecution 只消费决定。
+    source_refs: [rule.current-admission-required]
+    evidence_refs: [evidence.domain-strategy-review.supplier]
+    status: confirmed
+assumptions:
+  - id: assumption.unique-subject-ref
+    statement: 供应商已有唯一 subject_ref。
+    source_refs: [scenario.supplier-submits]
+    evidence_refs: [evidence.discovery.supplier]
+    status: confirmed
+constraints:
+  - id: constraint.preserve-procurement-flow
+    statement: 保留现有采购订单流程。
+    source_refs: [scenario.admission-expires]
+    evidence_refs: [evidence.discovery.compliance]
+    status: confirmed
 unresolved_items:
   - item: 供应商历史资料迁移范围
     type: deferred
@@ -25,7 +50,7 @@ context_snapshot:
   term_refs: [Global/Supplier, ComplianceReview/AdmissionDecision]
 domain_strategy_ref:
   domain_strategy_id: domain-strategy.supplier-admission
-  domain_version: v2
+  domain_version: v3
   digest: <domain-strategy-digest>
   status: approved
   persisted_ref: domain-strategy.yaml
@@ -38,17 +63,21 @@ impact_assessment:
   cross_repo: false
   high_risk: false
 downstream_mapping:
-  - domain_change: admission-decision-validity
-    consumer: spec-synthesis
+  - mapping_id: mapping.backend-admission-validity
+    source_refs: [rule.current-admission-required, invariant.current-admission-required]
+    consumer_capability: backend-technical-design
     propagation: direct
     reapproval_condition: 领域策略版本或有效性规则变化
-  - domain_change: admission-decision-validity
-    consumer: ticket-decomposition
+    evidence_refs: [evidence.domain-strategy-review.supplier]
+  - mapping_id: mapping.frontend-admission-validity
+    source_refs: [scenario.admission-expires]
+    consumer_capability: frontend-engineering-design
     propagation: transitive
     reapproval_condition: Spec 基线变更
+    evidence_refs: [evidence.domain-strategy-review.supplier]
 evidence_refs: [evidence.discovery.supplier, evidence.domain-strategy-review.supplier]
 approval:
   approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml
   approver: role.product-manager
   persisted_ref: docs/.scratch/supplier/stage-decision/stage-decision-package-v1.yaml
-  current_version: v2
+  current_version: v3

package/template/.pi/skills/yss-stage-decision/tests/fixtures/valid-supplier-domain.yaml

@@ -1,7 +1,19 @@
-schema_version: 2
+schema_version: 3
 domain_strategy_id: domain-strategy.supplier-admission
-domain_version: v2
+domain_version: v3
 status: approved
+traceability_version: 1
+rule_catalog:
+  - rule_id: rule.application-material-complete
+    statement: 申请材料必须完整
+    responsible_context: SupplierManagement
+    status: confirmed
+    evidence_refs: [evidence.discovery.supplier]
+  - rule_id: rule.current-admission-required
+    statement: 新采购订单必须引用当前有效的准入决定。
+    responsible_context: ComplianceReview
+    status: confirmed
+    evidence_refs: [evidence.discovery.compliance]
 contexts:
   - context_id: SupplierManagement
     name: 供应商管理
@@ -64,6 +76,10 @@ scenarios:
     preconditions: [供应商资料可编辑]
     commands: [SubmitSupplierApplication]
     rules: [申请材料必须完整]
+    rule_refs: [rule.application-material-complete]
+    critical: true
+    success_results: [完整申请进入合规审查]
+    evidence_refs: [evidence.discovery.supplier]
     events: [SupplierApplicationSubmitted]
     failure_results: [材料不完整时拒绝提交]
     responsible_context: SupplierManagement
@@ -73,7 +89,11 @@ scenarios:
     actor: compliance-officer
     preconditions: [批准决定存在]
     commands: [EvaluateAdmissionValidity]
-    rules: [过期决定不得支持新采购订单]
+    rules: [新采购订单必须引用当前有效的准入决定。]
+    rule_refs: [rule.current-admission-required]
+    critical: true
+    success_results: [过期准入决定不能支持新采购订单]
+    evidence_refs: [evidence.discovery.compliance]
     events: [SupplierAdmissionExpired]
     failure_results: [采购下单时资格校验失败]
     responsible_context: ComplianceReview
@@ -94,6 +114,8 @@ invariants:
     responsible_context: ComplianceReview
     scenario_refs: [scenario.admission-expires]
     verification_method: 领域场景测试和事件版本校验
+    rule_ref: rule.current-admission-required
+    evidence_refs: [evidence.discovery.compliance]
 context_snapshot:
   context_ref: CONTEXT.md
   context_schema_version: 1
@@ -101,13 +123,23 @@ context_snapshot:
   referenced_terms_digest: <referenced-terms-digest>
   term_refs: [Global/Supplier, ComplianceReview/AdmissionDecision]
 downstream_mapping:
-  - domain_change: admission-decision-validity
+  - mapping_id: mapping.backend-admission-validity
+    source_refs: [rule.current-admission-required, invariant.current-admission-required]
+    consumer_capability: backend-technical-design
     impacts: [spec, openapi, procurement-acceptance-tests]
     propagation: stale
     reapproval_condition: ComplianceReview 决定和有效期重新批准
+    evidence_refs: [evidence.discovery.compliance]
+  - mapping_id: mapping.frontend-admission-validity
+    source_refs: [scenario.admission-expires]
+    consumer_capability: frontend-engineering-design
+    impacts: [ui, frontend]
+    propagation: direct
+    reapproval_condition: 场景结果或视觉基线变化
+    evidence_refs: [evidence.discovery.compliance]
 evidence_refs: [evidence.discovery.supplier, evidence.discovery.compliance]
 approval:
   approval_ref: .agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml
   approver: role.product-manager
   persisted_ref: docs/.scratch/supplier/domain/domain-strategy-v1.yaml
-  current_version: v2
+  current_version: v3

package/template/.pi/skills/yss-stage-decision/tests/run-scenarios.mjs

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { buildDecisionFixture } from "../../../../scripts/fixtures/user-decision/build-fixture.mjs";
 import { createHash } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
@@ -14,6 +13,7 @@ const validator = join(testsRoot, "..", "scripts", "validate-domain-strategy.mjs
 const packageValidator = join(testsRoot, "..", "scripts", "validate-stage-decision-package.mjs");
 const contextValidator = join(projectRoot, "scripts", "verify-context-contract");
 const migrationTool = join(testsRoot, "..", "scripts", "migrate-context-references.mjs");
+const v3MigrationTool = join(testsRoot, "..", "scripts", "migrate-contract-v3.mjs");
 const validTemplate = join(testsRoot, "fixtures", "valid-supplier-domain.yaml");
 const validPackageTemplate = join(testsRoot, "fixtures", "valid-stage-decision-package.yaml");
 
@@ -29,6 +29,58 @@ function digestYaml(source) {
   return `sha256:${createHash("sha256").update(JSON.stringify(canonical(document.toJS({ maxAliasCount: 0 })))).digest("hex")}`;
 }
 
+function parseYaml(source) {
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length) throw new Error(document.errors[0].message);
+  return document.toJS({ maxAliasCount: 0 });
+}
+
+function toV2Domain(source) {
+  const value = structuredClone(parseYaml(source));
+  value.schema_version = 2;
+  value.domain_version = "v2";
+  delete value.traceability_version;
+  delete value.rule_catalog;
+  for (const scenario of value.scenarios) {
+    delete scenario.rule_refs;
+    delete scenario.critical;
+    delete scenario.success_results;
+    delete scenario.evidence_refs;
+  }
+  for (const invariant of value.invariants) {
+    delete invariant.rule_ref;
+    delete invariant.evidence_refs;
+  }
+  value.downstream_mapping = [{
+    domain_change: "admission-decision-validity",
+    impacts: ["spec", "openapi", "procurement-acceptance-tests"],
+    propagation: "stale",
+    reapproval_condition: "ComplianceReview 决定和有效期重新批准"
+  }];
+  value.approval.current_version = "v2";
+  return value;
+}
+
+function toV2Stage(source, domainDigest) {
+  const value = structuredClone(parseYaml(source));
+  value.schema_version = 2;
+  value.package_version = "v2";
+  for (const field of ["success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints"]) {
+    value[field] = value[field].map((item) => item.statement);
+  }
+  value.domain_strategy_ref.domain_version = "v2";
+  value.domain_strategy_ref.digest = domainDigest;
+  value.domain_strategy_ref.persisted_ref = "domain-strategy-v2.yaml";
+  value.downstream_mapping = [{
+    domain_change: "admission-decision-validity",
+    consumer: "spec-synthesis",
+    propagation: "direct",
+    reapproval_condition: "领域策略版本或有效性规则变化"
+  }];
+  value.approval.current_version = "v2";
+  return value;
+}
+
 function run(command, file, contextRoot) {
   return spawnSync(process.execPath, [command, file, "--root", contextRoot], { cwd: projectRoot, encoding: "utf8" });
 }
@@ -56,34 +108,59 @@ context_schema_version: 1
 | 准入决定 | 合规审查形成的准入结论。 | AdmissionDecision | ComplianceReview | 避免：\`审批结果\` |
 `;
 
-const temporaryRoot = await mkdtemp(join(tmpdir(), "yss-stage-decision-v2-"));
+const temporaryRoot = await mkdtemp(join(tmpdir(), "yss-stage-decision-v3-"));
 try {
   await writeFile(join(temporaryRoot, "CONTEXT.md"), contextSource);
   const contextResult = spawnSync(process.execPath, [contextValidator, "--root", temporaryRoot, "--allowed-context", "SupplierManagement", "--allowed-context", "ComplianceReview", "--allowed-context", "ProcurementExecution", "--term-ref", "Global/Supplier", "--term-ref", "ComplianceReview/AdmissionDecision", "--json"], { cwd: projectRoot, encoding: "utf8" });
   if (contextResult.status !== 0) throw new Error(`context fixture should pass: ${contextResult.stderr}`);
   const context = JSON.parse(contextResult.stdout);
 
-  const domainApprovalRef = join(temporaryRoot, "domain-approval.json");
   const domainSource = (await readFile(validTemplate, "utf8"))
-    .replace(".agents/skills/yss-stage-decision/tests/fixtures/domain-strategy-approval.yaml", domainApprovalRef)
     .replace("<document-digest>", context.document_digest)
     .replace("<referenced-terms-digest>", context.referenced_terms_digest);
   const domainFile = join(temporaryRoot, "domain-strategy.yaml");
   await writeFile(domainFile, domainSource);
-  const domainDecision = buildDecisionFixture(join(temporaryRoot, "domain-decision"), { boundary: "check.domain-strategy-approved", subjectRef: domainFile });
-  const domainApproval = parseDocument(await readFile(join(testsRoot, "fixtures/domain-strategy-approval.yaml"), "utf8")).toJS();
-  await writeFile(domainApprovalRef, JSON.stringify({ ...domainApproval, subject_ref: domainFile, approval_scope: domainDecision.requirement.scope, user_decision_ref: domainDecision.ref }));
   const pass = run(validator, domainFile, temporaryRoot);
-  if (pass.status !== 0) throw new Error(`valid v2 fixture should pass: ${pass.stderr}`);
+  if (pass.status !== 0) throw new Error(`valid v3 fixture should pass: ${pass.stderr}`);
+
+  const v2Domain = toV2Domain(domainSource);
+  const v2DomainSource = JSON.stringify(v2Domain, null, 2);
+  const v2DomainFile = join(temporaryRoot, "domain-strategy-v2.yaml");
+  await writeFile(v2DomainFile, v2DomainSource);
+  const v2Pass = run(validator, v2DomainFile, temporaryRoot);
+  if (v2Pass.status !== 0) throw new Error(`read-only v2 fixture should pass: ${v2Pass.stderr}`);
+
+  const migratedDomainV3 = spawnSync(process.execPath, [v3MigrationTool, v2DomainFile, "--kind", "domain-strategy", "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
+  if (migratedDomainV3.status !== 0) throw new Error(`v2 domain strategy should migrate: ${migratedDomainV3.stderr}`);
+  const migratedDomainV3Value = JSON.parse(migratedDomainV3.stdout);
+  if (migratedDomainV3Value.schema_version !== 3 || migratedDomainV3Value.status !== "draft" || migratedDomainV3Value.approval.approval_ref !== "migration-required") throw new Error("domain v2 -> v3 migration must reset approval and status");
+
+  const duplicateRule = join(temporaryRoot, "duplicate-rule.yaml");
+  const duplicateRuleValue = parseYaml(domainSource);
+  duplicateRuleValue.rule_catalog.push(structuredClone(duplicateRuleValue.rule_catalog[0]));
+  await writeFile(duplicateRule, JSON.stringify(duplicateRuleValue, null, 2));
+  expectBlocked(run(validator, duplicateRule, temporaryRoot), /rule_id.*重复|重复.*rule_id/, "duplicate v3 rule id");
+
+  const danglingRule = join(temporaryRoot, "dangling-rule.yaml");
+  const danglingRuleValue = parseYaml(domainSource);
+  danglingRuleValue.scenarios[0].rule_refs = ["rule.missing"];
+  await writeFile(danglingRule, JSON.stringify(danglingRuleValue, null, 2));
+  expectBlocked(run(validator, danglingRule, temporaryRoot), /rule_refs.*未声明|悬空/, "dangling v3 rule ref");
+
+  const missingEvidence = join(temporaryRoot, "missing-rule-evidence.yaml");
+  const missingEvidenceValue = parseYaml(domainSource);
+  missingEvidenceValue.rule_catalog[0].evidence_refs = [];
+  await writeFile(missingEvidence, JSON.stringify(missingEvidenceValue, null, 2));
+  expectBlocked(run(validator, missingEvidence, temporaryRoot), /evidence_refs/, "missing v3 evidence");
 
   const legacyFile = join(temporaryRoot, "legacy-domain.yaml");
-  await writeFile(legacyFile, domainSource.replace("schema_version: 2", "schema_version: 1"));
+  await writeFile(legacyFile, JSON.stringify({ ...v2Domain, schema_version: 1 }, null, 2));
   expectBlocked(run(validator, legacyFile, temporaryRoot), /migration-required/, "legacy domain contract");
 
   const migratableLegacy = join(temporaryRoot, "migratable-legacy-domain.yaml");
-  const migratableLegacySource = domainSource
-    .replace("schema_version: 2", "schema_version: 1")
-    .replace(/context_snapshot:\n[\s\S]*?\ndownstream_mapping:/, "terminology_refs: [CONTEXT.md#Supplier, contexts/ComplianceReview/CONTEXT.md#AdmissionDecision]\ndownstream_mapping:");
+  const migratableLegacyValue = { ...structuredClone(v2Domain), schema_version: 1, terminology_refs: ["CONTEXT.md#Supplier", "contexts/ComplianceReview/CONTEXT.md#AdmissionDecision"] };
+  delete migratableLegacyValue.context_snapshot;
+  const migratableLegacySource = JSON.stringify(migratableLegacyValue, null, 2);
   await writeFile(migratableLegacy, migratableLegacySource);
   const migrated = spawnSync(process.execPath, [migrationTool, migratableLegacy, "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
   if (migrated.status !== 0) throw new Error(`migratable v1 contract should migrate: ${migrated.stderr}`);
@@ -91,7 +168,7 @@ try {
   if (migratedValue.schema_version !== 2 || migratedValue.terminology_refs !== undefined || migratedValue.context_snapshot.context_ref !== "CONTEXT.md" || migratedValue.context_snapshot.term_refs.join(",") !== "ComplianceReview/AdmissionDecision,Global/Supplier") throw new Error("migrated context snapshot is incomplete");
 
   const ambiguousLegacy = join(temporaryRoot, "ambiguous-legacy-domain.yaml");
-  await writeFile(ambiguousLegacy, migratableLegacySource.replace("CONTEXT.md#Supplier, contexts/ComplianceReview/CONTEXT.md#AdmissionDecision", "contexts/ComplianceReview/CONTEXT.md"));
+  await writeFile(ambiguousLegacy, JSON.stringify({ ...migratableLegacyValue, terminology_refs: ["contexts/ComplianceReview/CONTEXT.md"] }, null, 2));
   const ambiguousMigration = spawnSync(process.execPath, [migrationTool, ambiguousLegacy, "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
   expectBlocked(ambiguousMigration, /migration-required.*无法唯一定位|无法唯一定位.*migration-required/, "ambiguous legacy reference");
 
@@ -115,32 +192,48 @@ try {
   await writeFile(unknownContext, domainSource.replace("to_context: ComplianceReview", "to_context: UnknownContext"));
   expectBlocked(run(validator, unknownContext, temporaryRoot), /未引用已声明上下文|未在领域战略中登记/, "unknown context");
 
-  const packageApprovalRef = join(temporaryRoot, "package-approval.json");
   const packageSource = (await readFile(validPackageTemplate, "utf8"))
-    .replace(".agents/skills/yss-stage-decision/tests/fixtures/stage-decision-approval.yaml", packageApprovalRef)
     .replace("<document-digest>", context.document_digest)
     .replace("<referenced-terms-digest>", context.referenced_terms_digest)
     .replace("<domain-strategy-digest>", digestYaml(domainSource));
   const packageFile = join(temporaryRoot, "stage-decision.yaml");
   await writeFile(packageFile, packageSource);
-  const packageDecision = buildDecisionFixture(join(temporaryRoot, "package-decision"), { boundary: "check.stage-decision-package-approved", subjectRef: packageFile });
-  const packageApproval = parseDocument(await readFile(join(testsRoot, "fixtures/stage-decision-approval.yaml"), "utf8")).toJS();
-  await writeFile(packageApprovalRef, JSON.stringify({ ...packageApproval, subject_ref: packageFile, approval_scope: packageDecision.requirement.scope, user_decision_ref: packageDecision.ref }));
   const packagePass = run(packageValidator, packageFile, temporaryRoot);
-  if (packagePass.status !== 0) throw new Error(`valid v2 stage decision package should pass: ${packagePass.stderr}`);
+  if (packagePass.status !== 0) throw new Error(`valid v3 stage decision package should pass: ${packagePass.stderr}`);
+
+  const v2Stage = toV2Stage(packageSource, digestYaml(v2DomainSource));
+  const v2StageFile = join(temporaryRoot, "stage-decision-v2.yaml");
+  await writeFile(v2StageFile, JSON.stringify(v2Stage, null, 2));
+  const v2StagePass = run(packageValidator, v2StageFile, temporaryRoot);
+  if (v2StagePass.status !== 0) throw new Error(`read-only v2 stage decision package should pass: ${v2StagePass.stderr}`);
+
+  const migratedV3 = spawnSync(process.execPath, [v3MigrationTool, v2StageFile, "--kind", "stage-decision", "--root", temporaryRoot], { cwd: projectRoot, encoding: "utf8" });
+  if (migratedV3.status !== 0) throw new Error(`v2 stage decision should migrate: ${migratedV3.stderr}`);
+  const migratedV3Value = JSON.parse(migratedV3.stdout);
+  if (migratedV3Value.schema_version !== 3 || migratedV3Value.status !== "draft" || migratedV3Value.approval.approval_ref !== "migration-required") throw new Error("v2 -> v3 migration must reset approval and status");
+
+  const wrongSourceRef = join(temporaryRoot, "stage-decision-wrong-source-ref.yaml");
+  const wrongSourceRefValue = parseYaml(packageSource);
+  wrongSourceRefValue.success_criteria[0].source_refs = ["rule.missing"];
+  await writeFile(wrongSourceRef, JSON.stringify(wrongSourceRefValue, null, 2));
+  expectBlocked(run(packageValidator, wrongSourceRef, temporaryRoot), /source_refs.*未在领域战略中声明|悬空/, "stage decision dangling source ref");
 
   const packageLegacy = join(temporaryRoot, "legacy-stage-decision.yaml");
-  await writeFile(packageLegacy, packageSource.replace("schema_version: 2", "schema_version: 1"));
+  await writeFile(packageLegacy, JSON.stringify({ ...v2Stage, schema_version: 1 }, null, 2));
   expectBlocked(run(packageValidator, packageLegacy, temporaryRoot), /migration-required/, "legacy stage decision contract");
 
   const packageBlocker = join(temporaryRoot, "stage-decision-blocker.yaml");
-  await writeFile(packageBlocker, packageSource.replace("type: deferred", "type: blocker"));
+  const blockerValue = parseYaml(packageSource);
+  blockerValue.unresolved_items[0].type = "blocker";
+  await writeFile(packageBlocker, JSON.stringify(blockerValue, null, 2));
   expectBlocked(run(packageValidator, packageBlocker, temporaryRoot), /blocker/, "blocker package");
 
   const packageWrongArray = join(temporaryRoot, "stage-decision-wrong-array.yaml");
-  await writeFile(packageWrongArray, packageSource.replace("target_users: [采购专员、合规专员]", "target_users: [42]"));
+  const wrongArrayValue = parseYaml(packageSource);
+  wrongArrayValue.target_users = [42];
+  await writeFile(packageWrongArray, JSON.stringify(wrongArrayValue, null, 2));
   expectBlocked(run(packageValidator, packageWrongArray, temporaryRoot), /target_users\[0\]/, "package non-string array item");
 } finally {
   await rm(temporaryRoot, { recursive: true, force: true });
 }
-process.stdout.write("业务边界与规则设计 v2 场景验证通过\n");
+process.stdout.write("业务边界与规则设计 v2/v3 场景验证通过\n");

package/template/.pi/skills/yss-technical-design/SKILL.md

@@ -7,6 +7,12 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
+文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+
+## 文档写作
+
+起草或修订技术设计解释正文前，读取 `docs/process/document-writing.md` 的共用写法及工程契约指引，并在分支派发中传递该引用；结构化合同保持原 schema 和验证要求。
+
 ## 输入与架构选择
 
 先读根 `CONTEXT.md`、已批准且当前的 Spec、业务规则、关键场景、适用的 API 契约、ADR 和工程约束。没有 API 或其他专项影响时记录有依据的不适用，不生成占位设计。

package/template/docs/agents/yss-skill-registry.yaml

@@ -57,6 +57,7 @@ capability_contract:
     preserve_all_reasons: true
   deterministic_order: [recipe-declaration, dependency-topology, skill-id]
 capabilities:
+  - { id: writing.lifecycle-document, primary_skill: i-have-adhd, task_modes: [guidance] }
   - { id: architecture.technical-design, primary_skill: yss-technical-design, task_modes: [guidance, integration, review-input] }
   - { id: architecture.mvc-design, primary_skill: yss-mvc-design, architecture_family: layered-mvc, task_modes: [guidance, integration, review-input] }
   - { id: layer.mvc-service, primary_skill: yss-application, architecture_family: layered-mvc, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
@@ -110,10 +111,24 @@ recipes:
   - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  prototype-review:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-implementation-contract-compiler:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-openapi-governance:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-stage-decision:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-research:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
+  yss-product-lifecycle:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
   code-review:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
     - { skill: yss-repository, type: context-conditional, when: backend-persistence-impact }
     - { skill: yss-mybatis, type: context-conditional, when: backend-persistence-impact }
   yss-prototype-stage:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
     - { skill: prototype-review, type: review-only }
     - { skill: yss-design-system, type: coordination-only }
     - { skill: yss-antdv-next-design, type: context-conditional, when: h2-vue-antdv-next-default }
@@ -129,6 +144,7 @@ skill_dependencies:
     - { skill: yss-tactical-design, type: context-conditional, when: tactical-domain }
     - { skill: lombok, type: context-conditional, when: pojo }
   yss-technical-design:
+    - { skill: i-have-adhd, type: context-conditional, when: lifecycle-document-output }
     - { skill: yss-tactical-design, type: coordination-only, when: domain-driven }
     - { skill: yss-mvc-design, type: coordination-only, when: layered-mvc }
   yss-mvc-design:
@@ -198,6 +214,11 @@ invocation_contract:
       invocation_mode: user
       primary_output: maintenance-operation
   overrides:
+    i-have-adhd:
+      invocation_mode: model
+      trigger_conditions: [lifecycle-document-output]
+      exclusion_conditions: [code-only-work, command-only-work, unrelated-conversation, user-disabled]
+      primary_output: document-writing-assistance
     yss-prototype-stage:
       invocation_mode: both
       trigger_conditions: [impact:prototype]
@@ -218,6 +239,7 @@ agent_runtime_roots:
   cursor: .cursor/skills
   pi: .pi/skills
 skills:
+  - { id: i-have-adhd, layer: core, maturity: supported, instance_default_discoverable: true, aliases: [], impacts: [writing] }
   - id: alibaba-java-code-style
     layer: specialist
     maturity: supported

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

@@ -9,18 +9,22 @@ owner: <负责人>
 
 > 生命周期身份：`stage.plan` / `artifact.plan-record`。按影响面填写，不制造未命中项的空产物。进入 Spec 的退出条件以 `docs/process/lifecycle-registry.yaml` 为准。
 
-## 1. 输入与复用依据
+填写前读取[中文写作规范](../../process/document-writing.md)和 [Plan 对照](../../templates/examples/lifecycle-writing-examples.md#1-plan让业务问题和取舍可见)。先说明问题和本期取舍，假设与事实分开；以下各项按实际影响填写。
 
-| 资产 / 证据引用 | 版本 | 本次仍有效的依据 | 需要重新探索的部分 |
-|---|---|---|---|
+## 1. 用户、问题与目标
 
-## 2. 用户、问题与目标
+用一段话说明谁在什么情境下遇到什么问题、本期建议改变什么；收益未经验证时保持候选语气。
 
 - 目标用户和关键业务故事：
 - 问题、为什么现在做：
 - 期望结果、成功标准及验证方式：
 - 约束、假设及事实证据：
 
+## 2. 输入与复用依据
+
+| 资产 / 证据引用 | 版本 | 本次仍有效的依据 | 需要重新探索的部分 |
+|---|---|---|---|
+
 ## 3. 战略资产引用
 
 | 权威资产 | 当前版本 / 引用 | 确认状态 / 未命中原因 |

package/template/docs/process/document-writing.md

@@ -0,0 +1,77 @@
+# 研发文档中文写作规范
+
+起草或修订生命周期文档时，先读本规范的共用写法，再按阶段查阅第 3 节；发送进度与会签提示时读取第 4 节。按当前写入范围应用，正文、摘要和结构化信息应保持同一语义。
+
+[Plan、Spec、Ticket 写作对照](../templates/examples/lifecycle-writing-examples.md)提供同一事实输入下的改写样例；示例不构成真实需求或批准。
+
+## 1. 适用范围与保留项
+
+适用于研究结论、Plan、Spec、产品设计说明、工程契约的解释正文、Ticket、审查、发布和复盘。聊天中的进度通知按第 4 节处理。
+
+本文件是生命周期文档的共用写作规范。生命周期身份、门禁、资产所有权、批准和状态由根 `AGENTS.md` 指定的权威资产决定；标准术语消费根 `CONTEXT.md`。本规范约束表达，不新增阶段、审批或业务规则。
+
+写作调整应保留这些内容的原意：主体、触发条件、规则、例外、量词、范围、非目标、数值及单位、证据引用、未决项、责任人、时点和依赖。稳定 ID、API 标识、schema、metadata、版本及批准记录按原合同保存。已经冻结的内容若需要改变行为，应回交资产所有者处理，不作为润色顺手修改。
+
+## 2. 共用写法
+
+### 先回答读者当前需要判断的问题
+
+开头说明业务问题、本次结论或交付行为。必要背景紧接其后，让读者知道结论为什么成立。正式模板要求的 metadata 和身份信息仍保留；表达顺序的建议不能自行覆盖校验器要求的结构。
+
+只在内容较长或需要导航时添加摘要。摘要引用正文，不另写一套范围和状态；维护时检查二者一致。
+
+### 用主体、条件和结果表达需求
+
+把“提升效率”“完善体验”等目标落实到具体场景：谁在什么情况下做什么，系统产生什么可观察结果。保留支持判断的业务动机，不把所有文字都拆成短句或编号。
+
+输入没有规则时，记录待确认问题；不要为了让句子具体而补出时限、阈值、错误码或默认行为。重要缺口交回拥有该决定的工作单元。非阻断细节按既有流程记录责任人、解决时点和接收方。
+
+### 让确定程度与证据一致
+
+事实给出处；推断说明依据；方案使用建议语气；假设写明如何验证。章节开头已明确整段是假设或建议时，无须每句重复标签。
+
+保留表达真实不确定性的“尚未确认”“可能”“取决于”。只有测试失败现象时，报告现象和下一项诊断，不编造原因；只有期望收益时，写目标和验证方法，不写成已实现收益。估算需有执行者、依据、范围和条件；无依据时不填精确工期。
+
+### 让每段承担一项用途
+
+一段解释一个问题、一项规则或一个取舍。顺序动作使用编号；同类规则、状态或选项比较使用表格；因果和取舍使用连贯段落。列表长度、段落数量和总字数按内容决定。
+
+删除只有态度、没有事实或决定的修饰句。技术术语、业务术语和必要限定词保持准确，不使用同义词轮换制造变化。评价文档看它是否明确、可信和可执行，不追求模拟人的口头习惯或降低 AI 检测分数。
+
+### 复用上游事实，交代本阶段新增内容
+
+引用上游规则的可定位位置和必要版本，本阶段写新增细化、适用范围和交接。直接决定本地验收的条件可以在场景中重述，并绑定同一规则 ID；以一致性核验控制漂移。
+
+不要用“详见相关文档”代替必要信息。引用不可读或版本不明时按现有合同处理。条件项只在流程允许时记录带原因的 `not-applicable`；命中的要求和必要异常场景应完整展示。
+
+## 3. 各阶段怎么写
+
+| 阶段 | 正文优先回答 | 本阶段需要写具体的内容 |
+|---|---|---|
+| 研究 | 已知什么，证据支持到哪里？ | 结论与来源、反证、限制分开；建议与事实区分 |
+| Plan | 谁遇到什么问题，本期为什么这样取舍？ | 业务故事、MVP / 非目标、优先级依据、成功标准的确认情况、关键未决项 |
+| Spec | 什么条件下，系统必须怎样表现？ | 规则与验收对应；按影响面覆盖成功、拒绝、边界、状态变化和恢复 |
+| 产品设计 | 用户如何完成任务，失败后如何继续？ | 入口、操作、反馈、状态和恢复路径；引用 Spec，保留设计待确认项 |
+| 工程契约 | 实现必须遵守什么，哪些地方有取舍？ | 精确协议与解释正文配合；标识、版本、范围及约束保持可核验 |
+| Ticket | 本切片交付什么，如何证明完成？ | 窄而完整的行为、依赖、验收、公共测试 seam、当前合同及验证证据 |
+| 审查 | 哪个具体条件下存在什么问题？ | 定位、触发条件、影响、依据与修复建议；推测和已复现问题分开 |
+| 发布 / 复盘 | 验证了什么，还剩什么风险或决定？ | 实际验证范围、未覆盖部分、发布决定或失误机制与改进行动 |
+
+这些指引帮助填写既有模板，不新增必填字段、阶段或门禁。Plan 不提前承诺详细 API 和工程实现；Spec 的例子不代替完整规则；Ticket 不重新设计已冻结行为。
+
+## 4. 进度与会签提示
+
+进度更新说明本轮有意义的变化、当前阻塞和接下来由谁处理。状态没有变化时，无须重述全部计划。已授权且 Agent 可以完成的动作继续执行，避免把操作转交用户。
+
+请求决定时展示当前版本、推荐方案及理由、实质选项和取舍、风险、批准范围与后续动作，遵守既有用户决定协议。可以突出当前最重要的问题，但所有影响决定的阻塞和选项都应可见。一次回复需要多个相互独立的决定时，分别说明各自影响。
+
+示例：“规则说明已补齐。成功标准仍缺统计口径，负责人需在 Plan 进入 Spec 前确认；当前材料尚不能支持流转。”这类表述需要实际资产支持，不能成为固定的完成话术。
+
+## 5. 起草与修订时的检查
+
+1. 确认文档读者、当前阶段、权威输入和允许改动的范围；区分从事实起草与对既有正文作等义改写。
+2. 起草时按本阶段的问题组织内容；修订时先列出必须保留的规则和约束，再调整文字。
+3. 对照输入检查有无新增承诺、规则丢失、范围扩大、责任转移或不确定性被抹去。发现源资产冲突时记录并回交，不自行选一个版本。
+4. 检查正文、摘要、表格和状态是否一致；验证适用的引用、结构和合同。自检结论不代替独立审查或批准。
+
+规则、例外、证据或状态变化属于实质差异，不能被“字数减少”抵消。不要只用禁用词扫描或模型给自己的分数判断效果。

package/template/docs/process/frontend-backend-delivery.md

@@ -6,7 +6,7 @@
 
 战略方维护业务规则、Spec、页面流程和视觉基线；后端维护 API 及后端交付；前端维护工程设计、页面和验收证据；统一管理方维护基线引用、跨仓切片与业务验收汇总。
 
-前端消费需求可在上游设计时提前反馈。前端项目在战略和后端交付尚未齐备时，只能验包、诊断和回交缺口。两类输入通过接收核验后，可以准备前端工程设计、实现计划和 Slice Contract；合同获准前不得写代码。
+前端消费需求可在上游设计时提前反馈。Handoff v4 导入后的 Frontend Strategic Preflight 可在后端交付前完成战略输入、Context、视觉基线和源规则追踪核验，并允许起草前端工程设计与实现计划；它固定返回 `ready_for_agent: false`。仅当 Backend/API/Data 影响命中时，最终接收才等待后端交付；UI-only 路径使用有依据的 `backend-not-applicable`。Slice Contract 获准前均不得写代码。
 
 ## 后端导出与前端导入
 
@@ -28,11 +28,14 @@ scripts/backend-delivery import --bundle <directory-or-zip> --target-root <front
 
 ## 接收与启动
 
-导入只产生 `frontend-acceptance-draft.json`，不会批准资产。接收方完成正式词汇对账并按 `schemas/frontend-delivery-acceptance.schema.json` 准备接收记录：
+Handoff v4 先生成 `frontend-strategic-preflight-draft.json`；补齐正式 Context Reconciliation 后执行 `scripts/verify-frontend-strategic-preflight`。通过仅允许进入前端工程设计草案。
 
-- `backend_delivery` 绑定后端导入收据和包摘要。
+后端交付导入只新增匹配的 backend binding 并产生 `frontend-acceptance-draft.json`，不会覆盖已填写的前端预检/设计草案，也不会批准资产。最终接收方按当前 `schemas/frontend-delivery-acceptance.schema.json`（v2）准备记录；v1 仅服务历史 Handoff v3，继续要求真实后端交付：
+
+- `strategic_preflight` 绑定当前预检文件及字节摘要。
+- `backend_dependency.mode: required` 时，`backend_delivery` 绑定真实后端导入收据和包摘要；`not-applicable` 时必须与 Handoff v4 backend 路由的影响引用、原因和证据一致，且不得绑定后端收据。
 - `strategic_handoff` 绑定战略导入收据、包摘要、正式 `context_reconciliation_ref` 和全部源规则/关键场景的承接 rows。
-- `frontend_cases` 绑定业务规则/场景、成功或失败结果、已交付接口、Visual Baseline `case_id` 和可读取的用例说明。
+- `frontend_cases` 绑定业务规则/场景、成功或失败结果、Visual Baseline `case_id` 和可读取的用例说明；有后端依赖时绑定已交付接口，`backend-not-applicable` 时 `operation_ids` 必须为空。
 - 已规划的承接使用 `mapped`，表示已映射用例，不声称代码已实现。当前交付范围必须 mapped 到当前切片；其他范围的 pending、conflict、deferred 或 not-applicable 沿用战略逐条承接的理由、证据和依赖阻断规则。
 
 完成接收核对后记录 `status: accepted` 并执行：

package/template/docs/process/schemas/backend-delivery.schema.json

@@ -25,6 +25,10 @@
       "type": "string",
       "pattern": "^sha256:[0-9a-f]{64}$"
     },
+    "strategic_route_id": {
+      "type": "string",
+      "pattern": "^route\\.[a-z0-9][a-z0-9-]*$"
+    },
     "scope": {
       "type": "object",
       "additionalProperties": false,