create-yss-spec 3.5.8 → 3.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/cli-core.lock.json +1 -1
  2. package/package.json +1 -1
  3. package/src/commands/doctor.js +40 -0
  4. package/src/commands/skills.js +7 -2
  5. package/src/template/asset-runtime.js +120 -21
  6. package/template/.agents/skills/.strategic-design-skills-manifest.json +3 -3
  7. package/template/.agents/skills/yss-implementation-contract-compiler/SKILL.md +2 -0
  8. package/template/.agents/skills/yss-product-lifecycle/SKILL.md +20 -16
  9. package/template/.agents/skills/yss-product-lifecycle/references/matt-yss-adapter.md +3 -1
  10. package/template/.agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml +43 -0
  11. package/template/.agents/skills/yss-product-lifecycle/references/orchestration.md +3 -1
  12. package/template/.agents/skills/yss-product-lifecycle/references/plan-requirements.md +7 -6
  13. package/template/.agents/skills/yss-prototype-stage/scripts/verify-prototype-design.mjs +1 -0
  14. package/template/.agents/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs +8 -5
  15. package/template/.agents/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs +8 -5
  16. package/template/.agents/skills/yss-stage-decision/tests/run-scenarios.mjs +83 -13
  17. package/template/.codex/skills/yss-implementation-contract-compiler/SKILL.md +2 -0
  18. package/template/.codex/skills/yss-product-lifecycle/SKILL.md +20 -16
  19. package/template/.codex/skills/yss-product-lifecycle/references/matt-yss-adapter.md +3 -1
  20. package/template/.codex/skills/yss-product-lifecycle/references/orchestration-contract.yaml +43 -0
  21. package/template/.codex/skills/yss-product-lifecycle/references/orchestration.md +3 -1
  22. package/template/.codex/skills/yss-product-lifecycle/references/plan-requirements.md +7 -6
  23. package/template/.codex/skills/yss-prototype-stage/scripts/verify-prototype-design.mjs +1 -0
  24. package/template/.codex/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs +8 -5
  25. package/template/.codex/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs +8 -5
  26. package/template/.codex/skills/yss-stage-decision/tests/run-scenarios.mjs +83 -13
  27. package/template/.cursor/skills/yss-implementation-contract-compiler/SKILL.md +2 -0
  28. package/template/.cursor/skills/yss-product-lifecycle/SKILL.md +20 -16
  29. package/template/.cursor/skills/yss-product-lifecycle/references/matt-yss-adapter.md +3 -1
  30. package/template/.cursor/skills/yss-product-lifecycle/references/orchestration-contract.yaml +43 -0
  31. package/template/.cursor/skills/yss-product-lifecycle/references/orchestration.md +3 -1
  32. package/template/.cursor/skills/yss-product-lifecycle/references/plan-requirements.md +7 -6
  33. package/template/.cursor/skills/yss-prototype-stage/scripts/verify-prototype-design.mjs +1 -0
  34. package/template/.cursor/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs +8 -5
  35. package/template/.cursor/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs +8 -5
  36. package/template/.cursor/skills/yss-stage-decision/tests/run-scenarios.mjs +83 -13
  37. package/template/.pi/skills/yss-implementation-contract-compiler/SKILL.md +2 -0
  38. package/template/.pi/skills/yss-product-lifecycle/SKILL.md +20 -16
  39. package/template/.pi/skills/yss-product-lifecycle/references/matt-yss-adapter.md +3 -1
  40. package/template/.pi/skills/yss-product-lifecycle/references/orchestration-contract.yaml +43 -0
  41. package/template/.pi/skills/yss-product-lifecycle/references/orchestration.md +3 -1
  42. package/template/.pi/skills/yss-product-lifecycle/references/plan-requirements.md +7 -6
  43. package/template/.pi/skills/yss-prototype-stage/scripts/verify-prototype-design.mjs +1 -0
  44. package/template/.pi/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs +8 -5
  45. package/template/.pi/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs +8 -5
  46. package/template/.pi/skills/yss-stage-decision/tests/run-scenarios.mjs +83 -13
  47. package/template/.template-spec/plan/entry-review.md +2 -1
  48. package/template/.template-spec/plan/templates/plan-template.md +11 -5
  49. package/template/.template-spec/process/script-execution.md +37 -0
  50. package/template/.template-spec/user-guide//347/224/250/346/210/267/346/211/213/345/206/214.md +2 -0
  51. package/template/skills-lock.json +11 -11
  52. package/template.snapshot.json +4 -4
@@ -35,6 +35,40 @@ function parseYaml(source) {
35
35
  return document.toJS({ maxAliasCount: 0 });
36
36
  }
37
37
 
38
+ const hashBytes = source => createHash("sha256").update(source).digest("hex");
39
+ // This independent, test-only consumer context is never reconstructed from a record.
40
+ function bindSource(source, file, approvalRef, contextDigest) {
41
+ const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
42
+ if (document.errors.length) throw new Error(document.errors[0].message);
43
+ document.setIn(["approval", "approval_ref"], approvalRef);
44
+ document.setIn(["approval", "persisted_ref"], file);
45
+ document.set("approval_context", {
46
+ subject_ref: file,
47
+ approval_scope: ["feature.supplier-admission"],
48
+ basis: [{ ref: "CONTEXT.md", digest: contextDigest }],
49
+ drafter_principal_ref: "instance:role.requirements-manager"
50
+ });
51
+ return document.toString();
52
+ }
53
+
54
+ function fixtureApproval(gateId, file, source, contextDigest) {
55
+ return {
56
+ schema_version: 1, gate_id: gateId, decision: "approved", actor_kind: "digital-human",
57
+ role_id: "role.product-manager", runtime_id: "runtime.generic", principal_ref: "instance:role.product-manager",
58
+ drafter_role_id: "role.requirements-manager", drafter_principal_ref: "instance:role.requirements-manager",
59
+ subject_ref: file, subject_digest: hashBytes(source), approval_scope: ["feature.supplier-admission"],
60
+ basis: [{ ref: "CONTEXT.md", digest: contextDigest }], evidence_refs: [file, "CONTEXT.md"]
61
+ };
62
+ }
63
+
64
+ async function writeApprovedFixture(source, file, gateId, contextDigest) {
65
+ const approvalRef = `${file}.approval.json`;
66
+ const bound = bindSource(source, file, approvalRef, contextDigest);
67
+ await writeFile(file, bound);
68
+ await writeFile(approvalRef, JSON.stringify(fixtureApproval(gateId, file, bound, contextDigest), null, 2));
69
+ return bound;
70
+ }
71
+
38
72
  function toV2Domain(source) {
39
73
  const value = structuredClone(parseYaml(source));
40
74
  value.schema_version = 2;
@@ -115,18 +149,18 @@ try {
115
149
  if (contextResult.status !== 0) throw new Error(`context fixture should pass: ${contextResult.stderr}`);
116
150
  const context = JSON.parse(contextResult.stdout);
117
151
 
118
- const domainSource = (await readFile(validTemplate, "utf8"))
152
+ const domainTemplateSource = (await readFile(validTemplate, "utf8"))
119
153
  .replace("<document-digest>", context.document_digest)
120
154
  .replace("<referenced-terms-digest>", context.referenced_terms_digest);
121
155
  const domainFile = join(temporaryRoot, "domain-strategy.yaml");
122
- await writeFile(domainFile, domainSource);
156
+ const contextDigest = hashBytes(contextSource);
157
+ const domainSource = await writeApprovedFixture(domainTemplateSource, domainFile, "check.domain-strategy-approved", contextDigest);
123
158
  const pass = run(validator, domainFile, temporaryRoot);
124
159
  if (pass.status !== 0) throw new Error(`valid v3 fixture should pass: ${pass.stderr}`);
125
160
 
126
161
  const v2Domain = toV2Domain(domainSource);
127
- const v2DomainSource = JSON.stringify(v2Domain, null, 2);
128
162
  const v2DomainFile = join(temporaryRoot, "domain-strategy-v2.yaml");
129
- await writeFile(v2DomainFile, v2DomainSource);
163
+ const v2DomainSource = await writeApprovedFixture(JSON.stringify(v2Domain, null, 2), v2DomainFile, "check.domain-strategy-approved", contextDigest);
130
164
  const v2Pass = run(validator, v2DomainFile, temporaryRoot);
131
165
  if (v2Pass.status !== 0) throw new Error(`read-only v2 fixture should pass: ${v2Pass.stderr}`);
132
166
 
@@ -192,12 +226,12 @@ try {
192
226
  await writeFile(unknownContext, domainSource.replace("to_context: ComplianceReview", "to_context: UnknownContext"));
193
227
  expectBlocked(run(validator, unknownContext, temporaryRoot), /未引用已声明上下文|未在领域战略中登记/, "unknown context");
194
228
 
195
- const packageSource = (await readFile(validPackageTemplate, "utf8"))
229
+ const packageTemplateSource = (await readFile(validPackageTemplate, "utf8"))
196
230
  .replace("<document-digest>", context.document_digest)
197
231
  .replace("<referenced-terms-digest>", context.referenced_terms_digest)
198
232
  .replace("<domain-strategy-digest>", digestYaml(domainSource));
199
233
  const packageFile = join(temporaryRoot, "stage-decision.yaml");
200
- await writeFile(packageFile, packageSource);
234
+ const packageSource = await writeApprovedFixture(packageTemplateSource, packageFile, "check.stage-decision-package-approved", contextDigest);
201
235
  const packagePass = run(packageValidator, packageFile, temporaryRoot);
202
236
  if (packagePass.status !== 0) throw new Error(`valid v3 stage decision package should pass: ${packagePass.stderr}`);
203
237
  for (const format of ['yaml', 'json']) {
@@ -215,16 +249,14 @@ try {
215
249
 
216
250
  const bundleFile = join(temporaryRoot, "plan-review-bundle.json");
217
251
  const bundledDomainValue = parseYaml(domainSource);
218
- bundledDomainValue.approval.approval_ref = bundleFile;
219
- const bundledDomainSource = JSON.stringify(bundledDomainValue, null, 2);
220
252
  const bundledDomainFile = join(temporaryRoot, "domain-strategy-bundled.yaml");
253
+ const bundledDomainSource = bindSource(JSON.stringify(bundledDomainValue, null, 2), bundledDomainFile, bundleFile, contextDigest);
221
254
  await writeFile(bundledDomainFile, bundledDomainSource);
222
255
  const bundledPackageValue = parseYaml(packageSource);
223
256
  bundledPackageValue.domain_strategy_ref.persisted_ref = "domain-strategy-bundled.yaml";
224
257
  bundledPackageValue.domain_strategy_ref.digest = digestYaml(bundledDomainSource);
225
- bundledPackageValue.approval.approval_ref = bundleFile;
226
- const bundledPackageSource = JSON.stringify(bundledPackageValue, null, 2);
227
258
  const bundledPackageFile = join(temporaryRoot, "stage-decision-bundled.yaml");
259
+ const bundledPackageSource = bindSource(JSON.stringify(bundledPackageValue, null, 2), bundledPackageFile, bundleFile, contextDigest);
228
260
  await writeFile(bundledPackageFile, bundledPackageSource);
229
261
  await writeFile(bundleFile, JSON.stringify({
230
262
  schema_version: 1,
@@ -237,8 +269,8 @@ try {
237
269
  runtime_id: "runtime.generic",
238
270
  principal_ref: "instance:role.product-manager",
239
271
  reviews: [
240
- { schema_version: 1, gate_id: "check.domain-strategy-approved", decision: "approved", actor_kind: "digital-human", role_id: "role.product-manager", runtime_id: "runtime.generic", principal_ref: "instance:role.product-manager", drafter_role_id: "role.requirements-manager", drafter_principal_ref: "instance:role.requirements-manager", subject_ref: bundledDomainFile, subject_digest: digestYaml(bundledDomainSource).slice(7), approval_scope: ["feature.supplier-admission"], evidence_refs: [bundledDomainFile] },
241
- { schema_version: 1, gate_id: "check.stage-decision-package-approved", decision: "approved", actor_kind: "digital-human", role_id: "role.product-manager", runtime_id: "runtime.generic", principal_ref: "instance:role.product-manager", drafter_role_id: "role.requirements-manager", drafter_principal_ref: "instance:role.requirements-manager", subject_ref: bundledPackageFile, subject_digest: digestYaml(bundledPackageSource).slice(7), approval_scope: ["feature.supplier-admission"], evidence_refs: [bundledPackageFile] }
272
+ fixtureApproval("check.domain-strategy-approved", bundledDomainFile, bundledDomainSource, contextDigest),
273
+ fixtureApproval("check.stage-decision-package-approved", bundledPackageFile, bundledPackageSource, contextDigest)
242
274
  ]
243
275
  }, null, 2));
244
276
  const bundledDomainPass = run(validator, bundledDomainFile, temporaryRoot);
@@ -246,9 +278,47 @@ try {
246
278
  const bundledPackagePass = run(packageValidator, bundledPackageFile, temporaryRoot);
247
279
  if (bundledPackagePass.status !== 0) throw new Error(`stage decision should select its conclusion from Plan review-bundle: ${bundledPackagePass.stderr}`);
248
280
 
281
+ // Both consumers reject coherent record edits unless independently current inputs match.
282
+ for (const [kind, command, source, gateId] of [
283
+ ["domain", validator, domainSource, "check.domain-strategy-approved"],
284
+ ["stage", packageValidator, packageSource, "check.stage-decision-package-approved"]
285
+ ]) {
286
+ for (const [label, mutateAsset, mutateRecord, pattern] of [
287
+ ["missing-context", value => { delete value.approval_context; }, null, /APPROVAL_CONTEXT_REQUIRED/],
288
+ ["context-missing-basis", value => { value.approval_context.basis = []; }, null, /APPROVAL_CONTEXT_REQUIRED/],
289
+ ["context-stale-basis", value => { value.approval_context.basis[0].digest = "0".repeat(64); }, null, /当前消费上下文.*证据过期/],
290
+ ["context-missing-drafter", value => { delete value.approval_context.drafter_principal_ref; }, null, /独立起草者来源/],
291
+ ["context-drafter", value => { value.approval_context.drafter_principal_ref = "instance:other-drafter"; }, null, /起草者身份.*不匹配/],
292
+ ["context-scope", value => { value.approval_context.approval_scope.push("feature.other"); }, null, /审查范围不匹配/],
293
+ ["record-subject", null, record => { record.subject_ref = domainFile; }, /审查对象不匹配/],
294
+ ["record-scope", null, record => { record.approval_scope.push("feature.other"); }, /审查范围不匹配/],
295
+ ["record-drafter", null, record => { record.drafter_principal_ref = "instance:other-drafter"; }, /起草者身份.*不匹配/],
296
+ ["record-self-sign", null, record => { record.principal_ref = record.drafter_principal_ref; }, /起草者自签/],
297
+ ["record-missing-basis", null, record => { record.basis = []; }, /批准记录.*缺少当前证据摘要/],
298
+ ["record-stale-basis", null, record => { record.basis[0].digest = "0".repeat(64); }, /批准记录.*证据过期/],
299
+ ["record-semantic-digest", null, record => { record.subject_digest = digestYaml(record.fixtureSource).slice(7); }, /审查资产摘要不匹配/]
300
+ ]) {
301
+ const file = join(temporaryRoot, `${kind}-${label}.yaml`);
302
+ let bound = await writeApprovedFixture(source, file, gateId, contextDigest);
303
+ if (mutateAsset) {
304
+ const value = parseYaml(bound); mutateAsset(value);
305
+ bound = JSON.stringify(value, null, 2);
306
+ await writeFile(file, bound);
307
+ }
308
+ const record = fixtureApproval(gateId, file, bound, contextDigest);
309
+ // Keep the raw bytes current even for consumer-context changes: an unrelated stale
310
+ // subject must not be what makes the current-context negative pass.
311
+ if (mutateRecord) {
312
+ record.fixtureSource = bound; mutateRecord(record); delete record.fixtureSource;
313
+ }
314
+ await writeFile(`${file}.approval.json`, JSON.stringify(record, null, 2));
315
+ expectBlocked(run(command, file, temporaryRoot), pattern, `${kind} ${label}`);
316
+ }
317
+ }
318
+
249
319
  const v2Stage = toV2Stage(packageSource, digestYaml(v2DomainSource));
250
320
  const v2StageFile = join(temporaryRoot, "stage-decision-v2.yaml");
251
- await writeFile(v2StageFile, JSON.stringify(v2Stage, null, 2));
321
+ await writeApprovedFixture(JSON.stringify(v2Stage, null, 2), v2StageFile, "check.stage-decision-package-approved", contextDigest);
252
322
  const v2StagePass = run(packageValidator, v2StageFile, temporaryRoot);
253
323
  if (v2StagePass.status !== 0) throw new Error(`read-only v2 stage decision package should pass: ${v2StagePass.stderr}`);
254
324
 
@@ -16,11 +16,12 @@
16
16
  - `plan_ref`:本次 Plan 正文;`context_reconciliation_ref`:本次已通过的 Context 调和记录。
17
17
  - `basis`:非空 `{ref, digest}` 列表,digest 为实际文件字节的 `sha256:` 摘要。必须包含 Plan 正文、根 `CONTEXT.md`、生命周期注册表、Context 调和记录及各检查和门禁引用的文件。远程事实先保存可追溯证据快照。
18
18
  - `checks`:注册表要求的全部检查 ID,每项包含 `status: pending | passed` 和非空 `evidence_refs`,引用 `basis`。必需检查不接受 `not-applicable`。缺项、未知项、pending 均阻断。
19
+ - `checks.grill_exit=passed` 表示澄清材料及前置条件就绪:当前必要决策已逐项确认、问题依赖已收敛、事实和验证证据已回流、关键与可执行阻塞已关闭,并已整理共同理解总述。它不单独证明最终共同理解或 Plan 批准;完整 `grill_exit` 由入口联合上述准备检查与当前 `gate.plan-approved` 用户决定判定。
19
20
  - `open_items`:显式数组,空数组代表无未决项。每项有 `id`、`critical`、`runnable_blocker`、`status` 和 `evidence_refs`。影响业务边界、关键规则或 MVP 的问题属于 critical。`resolved` 须有解决证据;仅非关键、非可执行阻塞项可 `deferred`,并填写 `noncritical_reason`、`owner`、`resolution_point`、`downstream_recipient`。延期内容随整个审阅包展示并取得用户确认。
20
21
  - `impacts`:显式评估 `domain_strategy`(领域边界、词汇、协作或核心规则影响)和 `stage_decision`(需要稳定阶段决策合同)。证据和判断必须呈现给用户;缺值不解释为 false。
21
22
  - `internal_checks`:注册表 `check_impacts` 内部专业审查全部逐项记录。命中项须 `status: approved`、`approval_ref`、`subject_ref`、`approval_scope`、`evidence_refs`,会签记录及对应资产均加入 `basis`;未命中项须 `status: not-applicable`、`reason`、`evidence_refs`,并由用户确认影响面判断。阶段决策检查的上游依赖必须批准,不能用 N/A 跳过。
22
23
 
23
- 先固定审阅包及依据,展示当前内容、范围、风险、延期、N/A 理由和下一动作,再取得真实用户回复。`plan_user_decision_ref` 采用 `.template-spec/process/schemas/user-decision.schema.json`:边界为 `gate.plan-approved`,subject 为当前 `plan_review_ref`,scope 包含当前 `feature_id`。不得将旧“继续”、数字人会签或合成测试回复当作本次批准。
24
+ 按主控 `planning.clarification_policy` 完成分轮澄清,先固定审阅包及依据,再一次展示共同理解总述、当前内容、范围、风险、延期、N/A 理由和进入 Spec 的动作。用户同一真实回复可同时确认共同理解并批准当前 Plan;展示或回复范围不完整时继续阻断。`plan_user_decision_ref` 采用 `.template-spec/process/schemas/user-decision.schema.json`:边界为 `gate.plan-approved`,subject 为当前 `plan_review_ref`,scope 包含当前 `feature_id`。回复独立保存于该记录,不写回审阅包或 `basis`,避免改变其摘要;收取最终回复前不宣布共同理解已确认或 Plan 已批准。不得将旧“继续”、数字人会签或合成测试回复当作本次批准。
24
25
 
25
26
  审阅包、注册表、Plan、词汇、依据或批准来源变化均要求重新校验;摘要漂移时先展示差异并按用户决定协议重验:排版、措辞或派生内容变化,经独立等价审查证明决定依据与授权范围未变,且原始决定和适用外部审批仍有效时,可用 `plan_continuation_ref` 延续;范围、关键规则、验收、契约承诺、授权或风险接受发生实质变化时重新取得决定。未知影响先补分析,不能视为等价。检查器保证结构、引用、摘要和回复绑定,不证明业务事实或身份来源绝对真实;主控仍须按证据核查影响面,不能为了放行而填 false 或空问题列表。
26
27
 
@@ -71,16 +71,22 @@ owner: <负责人>
71
71
 
72
72
  ## 6. 未决项
73
73
 
74
- | ID | 问题 | 是否影响业务边界 / 关键规则 / MVP | 判断依据 | 责任人 | 解决时点 | 接收方 / 解决证据 |
75
- |---|---|---|---|---|---|
74
+ 按原生主控 `planning.clarification_policy` 分流:必须解决的需求、业务规则、范围或取舍决策主动调用 `grilling`;事实自行查证,实验及专业审查安排实际执行。问题按依赖分轮,复用有效真实确认;用户纠正理解时重开受影响项。无依赖工作继续。
75
+
76
+ | ID | 问题及前提依赖 | 类型 / critical / runnable_blocker | 状态及判断依据 | 决策结论 / 原始回复 / 解决证据 | 责任人 | 解决时点 | 下游接收方 |
77
+ |---|---|---|---|---|---|---|---|
78
+
79
+ `resolved` 附实际解决证据;`deferred` 仅限非关键、非执行阻塞细节,附理由、责任人、解决时点和下游接收方,并随最终审阅包取得用户确认。`open`、关键项违规延期或未回流执行阻塞均不能进入 Spec;调查、验证失败和专业审查不能仅凭问答关闭。
76
80
 
77
81
  ## 7. 退出核查与用户决定
78
82
 
79
83
  - [ ] 已按注册表核查 Plan 退出条件;关键未决项已解决。
80
84
  - [ ] 非关键未决项有依据、责任人、解决时点及接收方;无 runnable blocker。
81
- - [ ] 用户已确认规划结论,命中的门禁及根词汇对账证据可读且版本当前。
82
- - 当前资产版本、确认范围和原始用户决定引用:
83
- - 结论:ready-for-human / blocked / 已满足进入 Spec 的条件(附证据)。
85
+ - [ ] 澄清材料和前置条件已就绪:目标、MVP、非目标、关键规则、验收例子、逐项未决结论与解决证据、剩余不确定性可审阅;命中审查和根词汇对账证据当前。
86
+ - 当前资产版本、拟确认范围及各轮原始决策回复引用:
87
+ - 结论:ready-for-human / blocked(说明缺口及解除证据)。
84
88
  - 下一工作单元:
85
89
 
90
+ 完整审阅包固定后,最终共同理解与 Plan 批准合并一次真实回复。当前 `plan_user_decision_ref` 与批准记录单独保存,不在回复后回写本 Plan 或审阅包 `basis`;本页的材料就绪不等于已批准。完整 `grill_exit` 和进入 Spec 的条件由入口结合当前决定及 `verify-plan-spec-entry` 结果判定,引用外部状态与证据。
91
+
86
92
  表达约定与只读诊断见 [Plan / Spec 内容诊断](../../process/plan-spec-quality.md)。`content_profile` 可选,仅声明创作格式;检查结果不改变既有门禁或批准。
@@ -0,0 +1,37 @@
1
+ # 脚本执行与依赖说明
2
+
3
+ 本文件说明已有操作的调用方式。阶段与门禁仍来自生命周期注册表,执行策略来自 `yss-product-lifecycle/references/orchestration-contract.yaml.execution_efficiency`,分发文件来自当前 manifest、Skill 依赖与 CLI 快照。这里不登记第二套脚本权威。
4
+
5
+ ## 使用固定入口
6
+
7
+ 先核对本地 Profile、CLI 版本、快照和入口的 `--help`。表中工具只有已经安装且适用于当前工作单元时才能使用;专职 Profile 不保证拥有综合模板全部命令。
8
+
9
+ | 操作 | 已有入口 | 写入与证据 |
10
+ |---|---|---|
11
+ | 规则与技能查询 | `scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency --check-skills --agent-runtime codex` | 只读;示例 runtime 按当前安装改为 codex/cursor/pi;预检成功不批准阶段 |
12
+ | 进度与恢复诊断 | `scripts/lifecycle-status --root <项目根> --checkpoint <根相对引用> --format json` | 只写 stdout;需要当前证据复验时显式 `--preflight` |
13
+ | 当前 Slice 准备 | `scripts/slice-contract prepare <Ticket> --input <细化.yaml> --output <新合同.yaml>` | 起草新 YAML,来源摘要和依赖闭包由准备器生成;不批准 |
14
+ | 当前 Slice 验证 | `scripts/slice-contract verify <合同.yaml> --root <项目根> --unit <工作单元>` | 校验当前来源;批准记录按当前合同参数传入 |
15
+ | 合同阅读 | `scripts/contract view <合同.yaml> --kind slice --profile task --unit <工作单元>` | 只读派生视图;需追溯时展开 `full`,不要重复整读后自行重建 |
16
+ | checkpoint 检查 | `scripts/verify-lifecycle-checkpoint <checkpoint>` | 核验显式资产;场景测试不替代项目校验 |
17
+ | 技能投影与锁 | `scripts/sync-skills --check`、`scripts/update-skill-lock --check` | 默认先检查;更新用各仓已有生成器,保留项目扩展 |
18
+ | 模板维护回归 | `scripts/verify-template-fast`、`scripts/verify-template-candidate --base <SHA>`、`scripts/verify-template` | 仅模板维护或显式回归任务;全量发布门禁保留 |
19
+ | 实例依赖与补装 | 当前 CLI 的 `doctor`、`skills ensure --plan` 或 `assets ensure --plan`(以该家族 help 为准) | plan 不写项目;审阅缺口、文件纳入原因与固定来源后按既有授权补装 |
20
+
21
+ 参数与退出码以当前工具输出为准。Shell 包装器按 shebang 直接执行,例如 `scripts/verify-template-fast`;不能一律给入口加 `node`。调用失败时保留命令、退出码、时间和日志,先分清参数错误、依赖缺失、合同阻断与实际验证失败。
22
+
23
+ ## 为什么同时有 JS、MJS 和 Python
24
+
25
+ Node 负责已有 CLI、资产编排和共享库;`.mjs` 是这里的模块文件,部分 CLI 的 `.js` 按包的模块约定执行。文件后缀不代表每个任务都需重新生成脚本。
26
+
27
+ 部分校验通过 `python3` 调用 JSON Schema 引擎,部分交接工具使用固定 Python 脚本处理归档。其消费者、Schema 与资源必须随当前依赖闭包完整提供。解释器可用不代表第三方包可用;例如 Schema 路径还依赖 `jsonschema` / `referencing`。按实际分发内容和 doctor 输出核对,不把专项依赖强加给所有项目。
28
+
29
+ 项目运行代码与治理工具分别验证:前端使用登记的 `pnpm` 命令,后端优先根 `./mvnw`。治理脚本通过不能代替业务构建、交互验收或项目批准。
30
+
31
+ ## 临时分析与诊断
32
+
33
+ 已有入口覆盖的机械操作直接复用;确实缺少能力时先补现有入口参数或固定适配器。范围清晰的一次性分析可以在工具会话或仓外新目录运行,记录输入摘要、来源身份、允许写范围和实际输出。重复出现且有多个消费者时再收敛为可复用工具,不按扩展名批量删除。
34
+
35
+ 诊断和测试的合成资产由固定 fixture builder 生成,绑定当前来源并在结束后清理。模板维护工具 `node .template-source/scripts/diagnose-python-schema.mjs --output <仓外新目录>` 对照未插桩和插桩结果;诊断日志保留摘要与阻断信号,不记录真实业务或批准正文,也不分发到产品实例。
36
+
37
+ 计时分别记录脚本执行、Agent 编排和人工等待;不可观察项标为未知。现有 batch/validation-phase 只在本次操作与完整绑定范围内复用,结束时复核漂移;恢复、交接、实现、合并与发布重新校验。shadow 的观察结果不自动取得裁剪资格。
@@ -19,6 +19,8 @@
19
19
 
20
20
  先运行所用包的 `--version` 和 `--help`;源码候选版本、npm 已发布版本和实例记录的模板快照是三个不同事实。
21
21
 
22
+ 执行过程中出现 JS/MJS 或 Python 时,按[脚本执行与依赖说明](../process/script-execution.md)核对其用途、已安装入口和解释器依赖;重复的机械操作应复用已有工具。
23
+
22
24
  | 能力 | `create-yss-spec` | 战略、后端、前端专职 CLI |
23
25
  |---|---|---|
24
26
  | init | 默认命令;写入新目录 | `init`;只接受不存在或空目录 |
@@ -18,7 +18,7 @@
18
18
  "revision": "c4d958f18cc947cb91cbe1bd48783fa4601cc18f"
19
19
  },
20
20
  "iloveZzz/yss-harness-design-agent": {
21
- "revision": "79e66e694a378d78f06c63399a494d0a69543ba3"
21
+ "revision": "8948ada59432ce2c4e1ef34999eaed45939bdf5e"
22
22
  },
23
23
  "ayghri/i-have-adhd": {
24
24
  "revision": "839872f9d1cd634fed642b4589ce7226199cc15f"
@@ -393,7 +393,7 @@
393
393
  "sourceType": "git-submodule",
394
394
  "skillPath": ".agents/skills/prototype-review/SKILL.md",
395
395
  "effectiveHash": "e1b3c28881d315870d40c90d2d0dcfa9a4bb6b080744257e2ca57ed98d146c41",
396
- "sourceRevision": "79e66e694a378d78f06c63399a494d0a69543ba3",
396
+ "sourceRevision": "8948ada59432ce2c4e1ef34999eaed45939bdf5e",
397
397
  "upstreamHash": "9c0b042760f7d741487e62eaccf55b5079a1991e5489286560e278c9642a09b0",
398
398
  "adaptationRef": ".template-source/agents/strategic-design-skills-integration.md",
399
399
  "targets": [
@@ -645,7 +645,7 @@
645
645
  "sourceType": "git-submodule",
646
646
  "skillPath": ".agents/skills/yss-design-system/SKILL.md",
647
647
  "effectiveHash": "b2d9ad48db30c4b5a6868c9b800f406f72da44ac538ce5f57ac6413d317dbba5",
648
- "sourceRevision": "79e66e694a378d78f06c63399a494d0a69543ba3",
648
+ "sourceRevision": "8948ada59432ce2c4e1ef34999eaed45939bdf5e",
649
649
  "upstreamHash": "3884a6b9e0a836c2c783bbe51d7737fee874662ea1964a7df545c2f1ababf4e3",
650
650
  "adaptationRef": ".template-source/agents/strategic-design-skills-integration.md",
651
651
  "targets": [
@@ -782,7 +782,7 @@
782
782
  "source": "project",
783
783
  "sourceType": "local",
784
784
  "skillPath": ".agents/skills/yss-implementation-contract-compiler/SKILL.md",
785
- "effectiveHash": "a61e98f9c0f927c2e07ec118cd5b36fb1cac7ddf1fd5f477c475d3462b2636a3",
785
+ "effectiveHash": "57de1e67195b86e5fec3ccf1724bd7ebdbbf5e2fb0aeb49dcec6716ae0051147",
786
786
  "targets": [
787
787
  ".agents/skills",
788
788
  ".codex/skills",
@@ -842,7 +842,7 @@
842
842
  "source": "project",
843
843
  "sourceType": "local",
844
844
  "skillPath": ".agents/skills/yss-product-lifecycle/SKILL.md",
845
- "effectiveHash": "8709c6002ac7fffa5ecb59c788362c6daaf956dcc451b2dc0462a6809b195bdd",
845
+ "effectiveHash": "a7d1fccd9301d2623c4a4d7b1d76bfaa2d8e4b4ac20e054a3c3c96111bcfd8c0",
846
846
  "targets": [
847
847
  ".agents/skills",
848
848
  ".codex/skills",
@@ -854,9 +854,9 @@
854
854
  "source": "iloveZzz/yss-harness-design-agent",
855
855
  "sourceType": "git-submodule",
856
856
  "skillPath": ".agents/skills/yss-prototype-stage/SKILL.md",
857
- "effectiveHash": "63b182da9538feb4a1884fee365247e4d25840952836451be5e2946c9c70f8d5",
858
- "sourceRevision": "79e66e694a378d78f06c63399a494d0a69543ba3",
859
- "upstreamHash": "0e82e8c0f6b5446dbe48aec8df092574ab895be303efe33d8fc8457bce98d02e",
857
+ "effectiveHash": "661ef1a3c5046d2ebc31f0840e512dd719a2fc33157360da7edc1dd72d49d4ff",
858
+ "sourceRevision": "8948ada59432ce2c4e1ef34999eaed45939bdf5e",
859
+ "upstreamHash": "9d1177a3f7f4737e08f084049ca3c0a6e8da0c5327da8370a87262a1b5db3b8e",
860
860
  "adaptationRef": ".template-source/agents/strategic-design-skills-integration.md",
861
861
  "targets": [
862
862
  ".agents/skills",
@@ -932,9 +932,9 @@
932
932
  "source": "iloveZzz/yss-harness-design-agent",
933
933
  "sourceType": "git-submodule",
934
934
  "skillPath": ".agents/skills/yss-stage-decision/SKILL.md",
935
- "effectiveHash": "2f31ae2d68a543fbedc065cf3947f4c2f88165648c27f870b349ed1c90f7c5f9",
936
- "sourceRevision": "79e66e694a378d78f06c63399a494d0a69543ba3",
937
- "upstreamHash": "77fa3075f90966821881998ff5fa9d674672bd2568e70b8d877402efeb360453",
935
+ "effectiveHash": "8e01754b56e53d6321e691598181974a9df0d97b8cff4ceec701e5644b2e3435",
936
+ "sourceRevision": "8948ada59432ce2c4e1ef34999eaed45939bdf5e",
937
+ "upstreamHash": "5a55a18e996920c5e5ec683b6dfa89d714bb0a3299632ecc75e0d4865b71d108",
938
938
  "adaptationRef": ".template-source/agents/strategic-design-skills-integration.md",
939
939
  "targets": [
940
940
  ".agents/skills",
@@ -3,8 +3,8 @@
3
3
  "templateName": "yss-spec-project-template",
4
4
  "templateSource": "github:iloveZzz/yss-spec-project-template",
5
5
  "templateRepository": "https://github.com/iloveZzz/yss-spec-project-template.git",
6
- "requestedRef": "20477b0020cfa152e1294ddb0f53b2e90a579152",
7
- "templateCommit": "20477b0020cfa152e1294ddb0f53b2e90a579152",
6
+ "requestedRef": "e2c16b4e8de991f8942bc6cfa43e784ae0e106ca",
7
+ "templateCommit": "e2c16b4e8de991f8942bc6cfa43e784ae0e106ca",
8
8
  "sourceState": "committed",
9
9
  "manifestHash": "544e8ae01c49ef451a784237b06772137876f8e8d6b5334094827e2ca2fe0f13",
10
10
  "encodedPaths": {
@@ -16,6 +16,6 @@
16
16
  ".gitignore": "__yss_dotfile__.gitignore",
17
17
  ".pi/skills/yss-frontend-scaffold-generator/assets/data-quality-v1/.gitignore": ".pi/skills/yss-frontend-scaffold-generator/assets/data-quality-v1/__yss_dotfile__.gitignore"
18
18
  },
19
- "snapshotHash": "fca5a020ae988019847c8504762c52aed9c26c9eb794d3f625b8073d0a4bc91c",
20
- "generatedAt": "2026-10-04T02:52:31.138Z"
19
+ "snapshotHash": "cda9599f290480b9f29f765f0c1ada3409acc1858a30d937a5e643a8d1c3a3ef",
20
+ "generatedAt": "2026-10-04T15:23:03.061Z"
21
21
  }