create-yss-spec 3.3.0 → 3.3.3

package/src/template/instance-runtime.js

@@ -8,6 +8,11 @@ const { treeHash } = require("../template-hash");
 const { targetPath, pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
 const { validateTemplateSnapshot } = require("../validation/snapshot");
 const { validateTemplateMetadata } = require("../validation/metadata");
+const {
+  extractManagedGitignoreBlock,
+  mergeManagedGitignoreBlock,
+  markerState,
+} = require("./gitignore-section");
 const {
   parseRepositoryIdentity,
   convertTemplateSourceToInstance,
@@ -159,22 +164,11 @@ function renderTemplateFile(relativePath, content, variables) {
   }
 
   if (relativePath === "README.md") {
-    const renderedContent = content
-      .replace(/^# YSS Spec Project Template/m, `# ${variables.projectName}`)
-      .replace(
-        /^> Matt Pocock Engineering Skills/m,
-        `> 默认 Issue Tracker：${variables.issueTracker}\n>\n> Matt Pocock Engineering Skills`,
-      );
-
-    if (!variables.includeExampleDocs) {
-      return renderedContent.replace(
-        /^\| \[docs\/discovery\/IDEATION\.md\]\(\.\/docs\/discovery\/IDEATION\.md\) \|.*\r?\n/m,
-        "",
-      );
-    }
-    return renderedContent;
+    return `# ${variables.projectName}\n\n本仓库用于管理 ${variables.businessDomain} 的研发资产。\n\n- 默认 Issue Tracker：${variables.issueTracker}\n- 协作入口：[AGENTS.md](./AGENTS.md)\n- 业务词汇：[CONTEXT.md](./CONTEXT.md)\n- 用户指南：[docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md)\n`;
   }
 
+  if (relativePath === ".gitignore") return extractManagedGitignoreBlock(content);
+
   return content;
 }
 
@@ -273,9 +267,46 @@ function buildDesiredManagedOperations(targetDir, variables, mode = "managed") {
     .map((operation) => buildDesiredManagedFile(operation, variables));
 }
 
+function adaptGitignoreOperation(
+  operation,
+  targetDir,
+  { attach = false, legacyBaselineHash = null } = {},
+) {
+  if (operation.relativePath !== ".gitignore") return operation;
+  const kind = pathKind(operation.targetPath);
+  if (kind === "missing") return operation;
+  if (kind !== "file") return { ...operation, unsafeReason: `.gitignore 路径类型为 ${kind}` };
+  const currentContent = fs.readFileSync(operation.targetPath, "utf8");
+  const state = markerState(currentContent);
+  if (state.kind === "invalid") {
+    return { ...operation, unsafeReason: ".gitignore managed rules 标记无效" };
+  }
+  const legacyBaselineMatch =
+    state.kind === "absent" &&
+    typeof legacyBaselineHash === "string" &&
+    sha256(currentContent) === legacyBaselineHash;
+  const desiredContent = legacyBaselineMatch
+    ? operation.desiredContent
+    : mergeManagedGitignoreBlock(currentContent, operation.desiredContent);
+  return {
+    ...operation,
+    desiredContent,
+    desiredHash: sha256(desiredContent),
+    safeSectionMerge: state.kind === "valid" || attach || legacyBaselineMatch,
+    legacyBaselineConversion: legacyBaselineMatch,
+  };
+}
+
 function buildSyncDesiredOperations(targetDir, metadata, identity) {
   const variables = buildSyncVariables(metadata);
-  return buildDesiredManagedOperations(targetDir, variables, "init").map((operation) => {
+  return buildDesiredManagedOperations(targetDir, variables, "init")
+    .filter((operation) => operation.relativePath !== "README.md")
+    .map((operation) =>
+      adaptGitignoreOperation(operation, targetDir, {
+        legacyBaselineHash: metadata.managedFiles?.[".gitignore"]?.contentHash || null,
+      }),
+    )
+    .map((operation) => {
     if (
       operation.relativePath !== "yss-project.yaml" ||
       identity.state !== "valid" ||
@@ -296,7 +327,10 @@ function buildSyncDesiredOperations(targetDir, metadata, identity) {
 }
 
 function buildAttachDesiredOperations(targetDir, variables, identity) {
-  return buildDesiredManagedOperations(targetDir, variables, "managed").map((operation) => {
+  return buildDesiredManagedOperations(targetDir, variables, "managed")
+    .filter((operation) => operation.relativePath !== "README.md")
+    .map((operation) => adaptGitignoreOperation(operation, targetDir, { attach: true }))
+    .map((operation) => {
     if (operation.relativePath !== "yss-project.yaml" || identity.state === "missing") {
       return operation;
     }
@@ -351,7 +385,7 @@ function loadTemplateMetadata(targetDir) {
 function collectManagedFiles(desiredOperations) {
   const managedFiles = {};
   for (const operation of desiredOperations) {
-    if (pathKind(operation.targetPath) !== "file") continue;
+    if (operation.relativePath === "README.md" || pathKind(operation.targetPath) !== "file") continue;
     managedFiles[operation.relativePath] = {
       type: operation.type,
       contentHash: fileHash(operation.targetPath),
@@ -394,9 +428,9 @@ function writeTemplateMetadata(targetDir, metadata, transaction = null) {
 
 function buildNextSyncMetadata(metadata, syncPlan) {
   const nextManagedFiles = { ...(metadata.managedFiles || {}) };
-  for (const relativePath of syncPlan.removed) {
-    delete nextManagedFiles[relativePath];
-  }
+  delete nextManagedFiles["README.md"];
+  for (const relativePath of syncPlan.alreadyMissing || []) delete nextManagedFiles[relativePath];
+  for (const relativePath of syncPlan.pruned || []) delete nextManagedFiles[relativePath];
   for (const operation of syncPlan.desiredOperations) {
     if (pathKind(operation.targetPath) !== "file") continue;
     const currentHash = fileHash(operation.targetPath);
@@ -432,8 +466,7 @@ function verifyGeneratedSyncInstance(targetDir) {
   }
 
   const agentsContent = fs.readFileSync(targetPath(targetDir, "AGENTS.md"), "utf8");
-  const readmeContent = fs.readFileSync(targetPath(targetDir, "README.md"), "utf8");
-  if (agentsContent.includes("[填写]") || readmeContent.includes("[填写]")) {
+  if (agentsContent.includes("[填写]")) {
     throw new Error("初始化结果仍包含模板占位信息");
   }
 }

package/src/template/migration-runtime.js

@@ -17,12 +17,9 @@ const {
 
 const AGENT_SKILL_ROOTS = [
   ".agents/skills",
-  ".claude/skills",
   ".codex/skills",
   ".cursor/skills",
   ".pi/skills",
-  ".qoder/skills",
-  ".trae/skills",
 ];
 
 const LEGACY_SKILL_MAPPINGS = [

package/src/template/plan-schema.js

@@ -22,6 +22,11 @@ function normalizePlan(plan) {
     blocked: Boolean(plan.blocked),
     stats: plan.stats && typeof plan.stats === "object" ? plan.stats : {},
     migration: plan.migration || null,
+    ...(Array.isArray(plan.prunable) ? { prunable: plan.prunable } : {}),
+    ...(Array.isArray(plan.pruned) ? { pruned: plan.pruned } : {}),
+    ...(Array.isArray(plan.retainedRemoved)
+      ? { retainedRemoved: plan.retainedRemoved }
+      : {}),
   };
 }
 

package/src/template/prune-planner.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const { isTemplateManagedOwnership } = require("./ownership-policy");
+const { resolveTemplateOwnership } = require("./ownership-runtime");
+
+function classifyRemovedFiles({
+  removed,
+  managedFiles,
+  getPathKind,
+  getFileHash,
+  getCurrentOwnership = resolveTemplateOwnership,
+  getUnmanagedReason = () => null,
+}) {
+  const prunable = [];
+  const retainedRemoved = [];
+  const alreadyMissing = [];
+  for (const relativePath of removed) {
+    const record = managedFiles[relativePath];
+    const kind = getPathKind(relativePath);
+    if (kind === "missing") {
+      alreadyMissing.push(relativePath);
+      continue;
+    }
+    if (kind !== "file") {
+      retainedRemoved.push({ path: relativePath, reason: `路径类型为 ${kind}` });
+      continue;
+    }
+    if (!record?.contentHash) {
+      retainedRemoved.push({ path: relativePath, reason: "缺少可信受管基线" });
+      continue;
+    }
+    const recordedOwnership = record.ownership || getCurrentOwnership(relativePath);
+    const currentOwnership = getCurrentOwnership(relativePath);
+    if (
+      !isTemplateManagedOwnership(recordedOwnership) ||
+      !isTemplateManagedOwnership(currentOwnership)
+    ) {
+      retainedRemoved.push({ path: relativePath, reason: "文件不属于模板所有权" });
+      continue;
+    }
+    const unmanagedReason = getUnmanagedReason(relativePath);
+    if (unmanagedReason) {
+      retainedRemoved.push({ path: relativePath, reason: unmanagedReason });
+      continue;
+    }
+    if (getFileHash(relativePath) !== record.contentHash) {
+      retainedRemoved.push({ path: relativePath, reason: "文件已被项目修改" });
+      continue;
+    }
+    prunable.push(relativePath);
+  }
+  return { prunable, retainedRemoved, alreadyMissing };
+}
+
+module.exports = { classifyRemovedFiles };

package/src/template/sync-planner.js

@@ -49,6 +49,11 @@ function classifySyncOperations({
 
     const currentHash = getFileHash(operation);
 
+    if (operation.safeSectionMerge && currentHash !== operation.desiredHash) {
+      updated.push(operation);
+      continue;
+    }
+
     if (operation.identityConversion && currentHash === operation.identitySourceHash) {
       updated.push(operation);
       continue;

package/src/template/verification-runtime.js

@@ -92,7 +92,7 @@ function runTemplateVerificationWithGit(targetDir, scriptPath, args = []) {
   }
 }
 
-function verifyGeneratedInstance(targetDir, { checkForbiddenPaths = false } = {}) {
+function verifyGeneratedInstance(targetDir, { checkForbiddenPaths = false, checkReadme = false } = {}) {
   if (checkForbiddenPaths) {
     const forbiddenPaths = [
       ...INSTANCE_FORBIDDEN_PATHS,
@@ -116,31 +116,22 @@ function verifyGeneratedInstance(targetDir, { checkForbiddenPaths = false } = {}
   }
 
   const agentsContent = fs.readFileSync(targetPath(targetDir, "AGENTS.md"), "utf8");
-  const readmeContent = fs.readFileSync(targetPath(targetDir, "README.md"), "utf8");
+  const readmeContent = checkReadme
+    ? fs.readFileSync(targetPath(targetDir, "README.md"), "utf8")
+    : "";
   if (agentsContent.includes("[填写]") || readmeContent.includes("[填写]")) {
     throw new Error("初始化结果仍包含模板占位信息");
   }
 }
 
 function verifyGeneratedInit(targetDir) {
-  verifyGeneratedInstance(targetDir, { checkForbiddenPaths: true });
+  verifyGeneratedInstance(targetDir, { checkForbiddenPaths: true, checkReadme: true });
+  runTemplateVerification(targetDir, "scripts/verify-project-instance", []);
 }
 
 function verifyGeneratedAttach(targetDir) {
-  runTemplateVerification(targetDir, "scripts/sync-skills");
-  runTemplateVerification(targetDir, "scripts/update-skill-lock");
-  // Attach validates the generated project instance, not the template source
-  // release candidate. The release profile intentionally runs source-governance
-  // checks (including external tooling such as ripgrep) that are inappropriate
-  // as a runtime dependency for end-user projects. Use the fast profile with a
-  // known routed instance path so required files, repository identity and
-  // read-only Git invariants are still checked without escalating to release.
-  runTemplateVerificationWithGit(targetDir, "scripts/run-template-verification", [
-    "--profile",
-    "fast",
-    "--changed-file",
-    "README.md",
-  ]);
+  verifyGeneratedInstance(targetDir);
+  runTemplateVerification(targetDir, "scripts/verify-project-instance", []);
 }
 
 module.exports = {
@@ -151,4 +142,5 @@ module.exports = {
   verifyGeneratedInstance,
   verifyGeneratedInit,
   verifyGeneratedAttach,
+  verifyGeneratedProjectInstance: verifyGeneratedAttach,
 };

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,7 +3,7 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "8a67e0f5a56aa5085d18c2b42bb540c8f36c2fab",
+  "source_revision": "3a358684c5684ada433dca4fd97ee187050ca6d8",
   "adaptation_ref": "docs/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -34,7 +34,7 @@
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "1eadf230f0e17bf6d209c1df1249acef3520ab29c26a80c476a2a557a224c10a"
+      "upstream_hash": "2ec63f66aaf799d693cec0f0b5d71b8c4917e4e2822e0ddd519bc9b711fa3c95"
     }
   ]
 }

package/template/.agents/skills/.yss-skills-manifest.json

@@ -40,7 +40,6 @@
     "components_version": "1.5.18",
     "server_name": "yss-ui",
     "project_configs": [
-      { "path": ".mcp.json", "container": "mcpServers" },
       { "path": ".agents/mcp_config.json", "container": "mcpServers" },
       { "path": ".cursor/mcp.json", "container": "mcpServers" },
       { "path": ".vscode/mcp.json", "container": "servers" }

package/template/.agents/skills/competitive-intelligence/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: competitive-intelligence
-description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Discovery, Spec, product strategy, or roadmap decisions.
+description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Plan, Spec, product strategy, or roadmap decisions.
 ---
 
 # Competitive Intelligence
 
 Source requested for this project: `anthropics/knowledge-work-plugins`, `sales/skills/competitive-intelligence`.
 
-Use this skill when competitive or market facts are needed to shape product Discovery, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
+Use this skill when competitive or market facts are needed to shape product Plan, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
 
 ## Core Rules
 
@@ -45,8 +45,8 @@ Use this skill when competitive or market facts are needed to shape product Disc
    - Risks if we copy the competitor too closely.
    - Product opportunities for Spec or roadmap.
 5. Hand off to lifecycle assets:
-   - Update Discovery findings in `docs/.scratch/<feature>/discovery/`.
-   - Create or update a competitor matrix in `docs/.scratch/<feature>/discovery/reports/`.
+   - Update Plan findings in `docs/.scratch/<feature>/plan/`.
+   - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
    - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
    - Record uncertain claims as assumptions, not requirements.
 

package/template/.agents/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -45,7 +45,7 @@ context_schema_version: 1
 
 ## 内容边界
 
-- 只写已经确认、稳定且未来资产需要复用的业务语言。候选、猜测和未决术语保留在 Discovery、业务边界与规则设计或 `context_delta`。
+- 只写已经确认、稳定且未来资产需要复用的业务语言。候选、猜测和未决术语保留在 Plan、业务边界与规则设计或 `context_delta`。
 - 定义保持一到两句，说明概念是什么；不要写类全名、表名、接口路径、实现步骤或计划。
 - 禁用别名使用 `避免：别名一、别名二`；需要补充说明时追加 `；备注：...`。
 - 术语稳定时立即回写。工作单元完成、门禁批准或阶段转换前仍须执行 context reconciliation。

package/template/.agents/skills/grill-with-docs/SKILL.md

@@ -11,7 +11,7 @@ Call the Skill tool with `grilling`, then call it separately with `domain-modeli
 1. Read `yss-project.yaml` and the root glossary before the first round, then run `scripts/verify-context-contract --root . --json`. Missing or lowercase root files, nested `CONTEXT.md`, `CONTEXT-MAP.md`, unsupported schema, absolute/cross-repository references, and Markdown pseudo-anchors are `blocked` or `migration-required`.
 2. Separate discoverable facts from user decisions; investigate facts instead of asking the user.
 3. Ask the entire current decision frontier, with a recommendation for every question, then wait.
-4. Keep candidate or disputed terms in the Discovery decision frontier. Only after confirmation, use `domain-modeling` to record true stable glossary entries in the repository root's single, case-sensitive `CONTEXT.md`; business rows use the five-column format and `<ContextId>/<EnglishIdentifier>` identity. Non-`Global` Context IDs must come from the approved business responsibility areas in the business-boundary asset.
+4. Keep candidate or disputed terms in the Plan decision frontier. Only after confirmation, use `domain-modeling` to record true stable glossary entries in the repository root's single, case-sensitive `CONTEXT.md`; business rows use the five-column format and `<ContextId>/<EnglishIdentifier>` identity. Non-`Global` Context IDs must come from the approved business responsibility areas in the business-boundary asset.
 5. Create an ADR only when the decision is hard to reverse, surprising without context, and a real trade-off.
 6. Persist factual research/validation records in the repository's existing review or research convention.
 7. For `project-instance`, before requesting approval or returning a next work unit, generate and validate `context_reconciliation` with a readable ref, `document_digest`, `referenced_terms_digest`, and `term_refs`. Unresolved candidates, scope conflicts, aliases, or digest drift are `blocked`; reconciliation does not create another gate. For `template-source`, do not add fictional business terms and return a reasoned `not-applicable` after validating the template contract.

package/template/.agents/skills/maintaining-skills/SKILL.md

@@ -17,7 +17,7 @@ Create skills that add useful, non-obvious guidance without constraining unrelat
 6. Follow the repository's declared maintenance and review policy. If none exists, run structural validation plus focused checks of the behavior or invariant changed. Use independent forward testing only when complexity or risk makes it meaningful; do not require a failing baseline for every ordinary edit.
 7. After changes, validate frontmatter, naming, references, scripts, projections, locks, and affected callers. Retire obsolete names and resources unless the repository explicitly requires compatibility.
 8. When a repository declares staged template verification, default the implementation loop to its fast impact profile and stop at `implementation-ready`. Promote explicitly to `review-ready`; do not create frozen candidates, review packages, or release evidence during ordinary iteration. Unknown paths and changes to the verification framework itself must fail safe to the full profile.
-9. For L3 template maintenance, record maintainer self-check plus fresh verification and do not create a frozen candidate or formal independent review during ordinary iteration. Before release, run the repository's full `scripts/verify-template` gate once; historical formal-review records remain read-only compatible.
+9. For template maintenance, let the repository intensity policy determine verification evidence. Independent review is opt-in, never implied by an intensity level; record maintainer self-check and the required fresh verification without creating a frozen candidate during ordinary iteration. Before release, run the repository's full `scripts/verify-template` gate once; historical formal-review records remain read-only compatible.
 
 ## Boundaries
 

package/template/.agents/skills/prototype-review/SKILL.md

@@ -5,7 +5,7 @@ description: Use when independently reviewing low-fidelity UI, interaction specs
 
 # Prototype Review
 
-Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `gate.prototype-reviewed` decision.
+Use this skill as the independent low-fidelity review in `yss-prototype-stage`. The review is fail-closed: if the design cannot drive calibrated requirements, API, frontend acceptance, and slices, send it back to product design. `yss-product-lifecycle` alone records the resulting `check.prototype-reviewed` decision.
 
 ## Trigger Boundary
 
@@ -17,7 +17,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` or prototype link.
 - State matrix, preferably based on `docs/design/templates/state-matrix-template.md`.
 - Existing OpenAPI Draft only if the review is checking alignment; do not require OpenAPI before product design.
-- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending schema v3 record, but档位构建与浏览器验证属于后续 `gate.prototype-verified`。
+- `docs/.scratch/<feature>/verification/prototype-evidence.yaml` may be created as a pending schema v3 record, but档位构建与浏览器验证属于后续 `check.prototype-verified`。
 
 ## Review Gates
 
@@ -66,7 +66,7 @@ Run this independent gate only when UI changes affect a primary user flow, navig
 - <component states, data dependencies, profile triggers, frontend acceptance notes>
 
 ### Lifecycle Evidence
-- <persistent review path; blockers; `gate.prototype-reviewed` candidate result>
+- <persistent review path; blockers; `check.prototype-reviewed` candidate result>
 
 ### Next Action
 - <yss-prototype-stage / return to product design>

package/template/.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -21,7 +21,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 Look at the current repo to understand its starting state. Read whatever exists; don't assume:
 
 - `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
-- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
+- Root `AGENTS.md` — does it exist, and is there already an `## Agent skills` section?
 - The case-sensitive `CONTEXT.md` at the Git repository root; also detect lowercase, nested, or duplicate context files as migration problems
 - `docs/adr/` and any `src/*/docs/adr/` directories
 - `docs/agents/` — does this skill's prior output already exist?
@@ -72,7 +72,7 @@ If the root `CONTEXT.md` is missing, initialize it with `context_schema_version:
 
 Show the user a draft of:
 
-- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The `## Agent skills` block to add to `AGENTS.md`
 - The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
 
 Let them edit before writing.
@@ -81,11 +81,8 @@ Let them edit before writing.
 
 **Pick the file to edit:**
 
-- If `CLAUDE.md` exists, edit it.
-- Else if `AGENTS.md` exists, edit it.
-- If neither exists, ask the user which one to create — don't pick for them.
-
-Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
+- If `AGENTS.md` exists, edit it.
+- If it is missing, ask before creating it.
 
 If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
 

package/template/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -31,7 +31,7 @@ When `yss-product-lifecycle` is active, the same `docs/.scratch/<feature-slug>/`
 ```text
 docs/.scratch/<feature-slug>/
 ├── map.md
-├── discovery/
+├── plan/
 ├── spec.md
 ├── spec-delta/
 ├── parent-ticket.md

package/template/.agents/skills/triage/AGENT-BRIEF.md

@@ -1,6 +1,6 @@
 # Writing Agent Briefs
 
-An agent brief is a structured comment posted on a GitHub issue or PR when it moves to `ready-for-agent`. It is the authoritative specification that an AFK agent will work from. The original body and discussion are context — the agent brief is the contract.
+在 YSS 中，简报是回交生命周期的取证与工作建议，不是正式 Spec 或 Slice Implementation Contract，也不授予 `ready-for-agent`。正式实现必须引用生命周期批准且当前的切片合同；发布评论另需明确授权。
 
 The brief states **what the agent should do**, which stretches to both surfaces: for an issue, that's building the change from nothing; for a PR, it's what's left to do *to the existing diff* — finish it, close gaps, address review points. Same principles either way; the PR example below shows the difference.
 
@@ -12,7 +12,7 @@ The issue may sit in `ready-for-agent` for days or weeks. The codebase will chan
 
 - **Do** describe interfaces, types, and behavioral contracts
 - **Do** name specific types, function signatures, or config shapes that the agent should look for or modify
-- **Don't** reference file paths — they go stale
+- 必须保留当前证据路径、版本和批准合同引用；恢复时检查新鲜度，不把旧路径当作当前事实。
 - **Don't** reference line numbers
 - **Don't** assume the current implementation structure will remain the same
 

package/template/.agents/skills/triage/SKILL.md

@@ -6,7 +6,9 @@ disable-model-invocation: true
 
 # Triage
 
-Move issues on the project issue tracker through a small state machine of triage roles.
+显式处理项目 tracker 中的 Issue / 外部 PR。普通对话由 `yss-product-lifecycle` 分诊；本技能不作为自动路由入口。
+
+在 YSS 仓库中先回交生命周期核对仓库身份、请求范围和当前状态；问题理解及补充信息使用 `orchestration-contract.yaml.request_triage`（位于生命周期技能的 `references/`）。本技能负责取证和建议，不创建正式生命周期资产、不批准合同、不直接改变 Ticket 状态。状态变更回交生命周期核验；远端评论、关闭或其他外部动作另检查明确授权。模板源不生成产品 Ticket。
 
 If this repo treats external pull requests as a request surface (see the issue-tracker config), triage covers them too: **a PR is an issue with attached code** — same roles, same states, same machine, with a few deltas marked "for a PR" below. Resolve a bare `#42` to an issue or PR per the tracker config.
 
@@ -21,28 +23,22 @@ Every comment or issue posted to the issue tracker during triage **must** start
 - [AGENT-BRIEF.md](AGENT-BRIEF.md) — how to write durable agent briefs
 - [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — how the `.out-of-scope/` knowledge base works
 
-## Roles
+## Categories and states
 
-Two **category** roles:
+Two categories:
 
 - `bug` — something is broken
 - `enhancement` — new feature or improvement
 
-Five **state** roles:
+五态语义由 `docs/agents/triage-labels.md` 定义：
 
 - `needs-triage` — maintainer needs to evaluate
 - `needs-info` — waiting on reporter for more information
-- `ready-for-agent` — fully specified, ready for an AFK agent
-- `ready-for-human` — needs human implementation
+- `ready-for-agent` — 仅限生命周期确认合同已批准且当前、适用门禁通过的垂直切片。
+- `ready-for-human` — 资产仍需指定数字人或生物人会签，不代表可实现或可合并。
 - `wontfix` — will not be actioned
 
-For a PR, the same states read against the attached code: `ready-for-agent` means a brief is attached and an agent should take the next step on the diff; `ready-for-human` means it's ready for a human to merge.
-
-Every triaged issue should carry exactly one category role and one state role. If state roles conflict, flag it and ask the maintainer before doing anything else.
-
-These are canonical role names. The actual label strings used in the issue tracker may differ. The mapping should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.
-
-State transitions: an unlabeled issue normally goes to `needs-triage` first; from there it moves to `needs-info`, `ready-for-agent`, `ready-for-human`, or `wontfix`. `needs-info` returns to `needs-triage` once the reporter replies. The maintainer can override at any time — flag transitions that look unusual and ask before proceeding.
+PR 附有代码也不能凭简报直接成为 `ready-for-agent`，或凭 `ready-for-human` 推断可合并。读取已配置 tracker 的真实状态；冲突回交生命周期处理。配置缺失按生命周期 setup readiness 处理，不从 Git remote 推断平台。
 
 ## Invocation
 
@@ -67,27 +63,19 @@ Show counts and a one-line summary per item. Let the maintainer pick.
 
 ## Triage a specific issue or PR
 
-1. **Gather context.** Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) **redundancy** — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection** — read `.out-of-scope/*.md` and surface any that resembles this request.
+1. **Gather context.** Read the full issue or PR (body, comments, labels, author, dates; for a PR, the diff too). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) **redundancy** — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, verify that it satisfies this user scenario before recommending already-implemented `wontfix` (step 5). (b) **prior rejection** — read `.out-of-scope/*.md` and surface any that resembles this request.
 
-2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the request — including whether it's already implemented. Wait for direction.
+2. **Recommend.** 给出类别、状态建议及证据依据；在已有授权内继续取证，只有影响下一动作的缺口才追问，不为每一步重复索要确认。
 
 3. **Verify the claim.** Before any grilling, check that the claim holds up. For a bug, reproduce it from the reporter's steps. For a PR, confirm the diff does what it claims — check it out, run the relevant tests or commands. Report what happened: confirmed (with code path), failed, or insufficient detail (a strong `needs-info` signal). A confirmed verification makes a much stronger agent brief.
 
-4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land.
+4. **Grill (if needed).** If the request needs fleshing out, call the Skill tool twice, for "grilling" and "domain-modeling", and grill it into shape a round of questions at a time, sharpening domain terms; return proposed terminology and ADR changes to the lifecycle orchestrator before formal writes.
 
-5. **Apply the outcome:**
-   - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
-   - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
-   - `needs-info` — post triage notes (template below).
-   - `wontfix` — close, with the comment depending on *why*:
-     - **Already implemented** — the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones).
-     - **Rejected (bug)** — polite explanation, then close.
-     - **Rejected (enhancement)** — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
-   - `needs-triage` — apply the role. Optional comment if there's partial progress.
+5. **Return the outcome.** 返回类别与状态建议、已验证事实、未决项、证据、逐目标下一动作，以及 [AGENT-BRIEF.md](AGENT-BRIEF.md) 格式的简报草案。`needs-info` 只询问真正缺少的信息；`wontfix` 必须区分已实现与拒绝，已有实现还需确认符合用户场景，不能仅因存在同名功能就关闭。拒绝 enhancement 时可提出 `.out-of-scope/` 更新建议；正式写入与 tracker 动作交由生命周期按范围和授权执行。
 
-## Quick state override
+## State change requests
 
-If the maintainer says "move #42 to ready-for-agent", trust them and apply the role directly. Confirm what you're about to do (role changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent brief.
+用户明确要求把 #42 改为 `ready-for-agent` 时，把该请求交给生命周期复算就绪条件；简报、口头要求和 PR diff 均不能代替当前批准合同与门禁证据。缺失时说明具体阻塞，不直接改标签。其他状态也按 tracker 权威规则核验后执行，不重新定义五态。
 
 ## Needs-info template
 

package/template/.agents/skills/yss-antd-design/references/evidence.md

@@ -25,11 +25,11 @@ JSON 输出存为相邻文件，证据清单只引用路径。不要把整份 `l
 
 `antd lint` 只对可解析的 React/TSX 源码有规则命中。HTML 原型会出现空 issues（假绿）或 `skippedFiles` / `parse-error` / `partial: true`。
 
-CLI JSON 只能证明查询事实，不能单独证明原型消费了目标版本或完成了 Vue/YSS 映射。`gate.prototype-verified` 还必须通过 schema v3 档位证据、Design QA、浏览器和无障碍验证。
+CLI JSON 只能证明查询事实，不能单独证明原型消费了目标版本或完成了 Vue/YSS 映射。`check.prototype-verified` 还必须通过 schema v3 档位证据、Design QA、浏览器和无障碍验证。
 
 | 产物 | `lint_applicable` | 做法 |
 |---|---|---|
 | 静态 HTML / H1 | `not-applicable` | 不创建 AntD 段；由 H1 合同验证 HTML |
 | React/TSX 原型源 | `true` | 对变更文件跑 `antd lint --format json`，保存输出；无 issue 才把 `lint_passed` 设为 `true` |
 
-浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `gate.prototype-verified` 通过。
+浏览器验证仍由 `yss-prototype-stage` 采集，不在本技能宣布 `check.prototype-verified` 通过。

package/template/.agents/skills/yss-antdv-next-design/SKILL.md

@@ -43,6 +43,6 @@ node .agents/skills/yss-antdv-next-design/scripts/collect-antdv-next-facts.mjs \
 - 禁止 `npx skills add antdv-next/cli`、`npx skills add antdv-next/skills`，也不得把官方 Skill 复制进任何 Agent root。
 - 禁止把 MCP 对话、`llms-full.txt`、CLI 自报的未解析版本或静态 `design.md` 当作 exact component API 证据。
 - 禁止让上游 `design.md` 覆盖项目 `DESIGN.md`、`docs/design/design.md` 或项目 Token；manifest 必须直接记录根 `DESIGN.md` path 与 digest。
-- 禁止把原型事实包当作生产兼容性、可复用代码、`gate.prototype-verified` 或组件库迁移完成证据。
+- 禁止把原型事实包当作生产兼容性、可复用代码、`check.prototype-verified` 或组件库迁移完成证据。
 
 事实包合同见 `references/fact-pack.md`，阶段及生产边界见 `references/boundaries.md`。

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -3,7 +3,7 @@
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
-import { spawn } from "node:child_process";
+import { runCommand } from "../../../../scripts/lib/command-runner.mjs";
 import { assertArchitectureAgreement } from "../../../../scripts/lib/backend-architecture.mjs";
 import { assertLocalDatabaseProfile, scaffoldArchitectureIdentity } from "../../../../scripts/lib/scaffold-local-database.mjs";
 
@@ -37,7 +37,7 @@ function classifyFailure(phase, outcome) {
   if (phase === "package") return "packaging";
   return "maven-execution";
 }
-function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.length; index += 1) { let token = argv[index]; if (token === "--help" || token === "-h") { result.help = true; continue; } const equals = token.indexOf("="); let value; if (equals !== -1) { value = token.slice(equals + 1); token = token.slice(0, equals); } if (!["--project-root", "--evidence-dir"].includes(token)) throw new Error(`不支持的参数: ${token}`); if (value === undefined) value = argv[++index]; if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`); result[token === "--project-root" ? "projectRoot" : "evidenceDir"] = path.resolve(value); } if (result.help) return result; if (!result.projectRoot || !result.evidenceDir) throw new Error("必须提供 --project-root 和 --evidence-dir"); return result; }
+function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.length; index += 1) { let token = argv[index]; if (token === "--help" || token === "-h") { result.help = true; continue; } const equals = token.indexOf("="); let value; if (equals !== -1) { value = token.slice(equals + 1); token = token.slice(0, equals); } if (!["--project-root", "--evidence-dir", "--timeout-ms"].includes(token)) throw new Error(`不支持的参数: ${token}`); if (value === undefined) value = argv[++index]; if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`); if (token === "--timeout-ms") result.timeoutMs = Number(value); else result[token === "--project-root" ? "projectRoot" : "evidenceDir"] = path.resolve(value); } if (result.help) return result; if (!result.projectRoot || !result.evidenceDir) throw new Error("必须提供 --project-root 和 --evidence-dir"); return result; }
 function validateManifest(manifest) {
   if (![2, 3, 4].includes(manifest.schema_version)) throw new Error(`unsupported: scaffold Manifest schema_version=${manifest.schema_version}；只读兼容 v2，并验证当前 v3/v4`);
   const required = ["schema_version", "contract_id", "contract_version", "scaffold_request_id", "contract_digest", "profiles", "ownership", "readiness", "generation_policy", "completion_level", "approval_ref", "approver", "lifecycle_approval_ref", "compiler_draft_ref", "persisted_ref", "contract_file_ref", "current_version", "allowed_write_paths", "expected_evidence_files", "verification_commands", "generation_mode"];
@@ -57,8 +57,7 @@ function validateManifest(manifest) {
   if (manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
   if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
 }
-function execute(wrapper, phase, cwd, environment) { return new Promise((resolve) => { const child = spawn(wrapper, [phase], { cwd, env: environment, stdio: ["ignore", "pipe", "pipe"] }); let stdout = "", stderr = ""; child.stdout.on("data", (chunk) => { stdout += chunk; }); child.stderr.on("data", (chunk) => { stderr += chunk; }); child.on("error", (error) => resolve({ exitCode: 127, stdout: "", stderr: String(error) })); child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr })); }); }
-export async function run(projectRoot, evidenceDir, environment = process.env) {
+export async function run(projectRoot, evidenceDir, environment = process.env, { timeoutMs = 0, signal } = {}) {
   const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
   if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
   if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
@@ -91,7 +90,8 @@ export async function run(projectRoot, evidenceDir, environment = process.env) {
     const stderrPath = path.join(evidenceDir, `mvnw-${phase}.stderr.log`);
     const startedAt = isoNow();
     const started = process.hrtime.bigint();
-    const outcome = await execute(wrapper, phase, projectRoot, environment);
+    const execution = await runCommand(wrapper, [phase], { cwd: projectRoot, env: environment, timeoutMs, signal, stdoutFile: stdoutPath, stderrFile: stderrPath, secrets: [environment.MAVEN_REPO_USERNAME, environment.MAVEN_REPO_PASSWORD], progress: true });
+    const outcome = { ...execution, exitCode: execution.status };
     const durationMs = Number(process.hrtime.bigint() - started) / 1e6;
     await writeText(stdoutPath, redactSecrets(outcome.stdout, environment));
     await writeText(stderrPath, redactSecrets(outcome.stderr, environment));
@@ -99,7 +99,7 @@ export async function run(projectRoot, evidenceDir, environment = process.env) {
       command: `./mvnw ${phase}`,
       phase,
       exit_code: outcome.exitCode,
-      failure_category: classifyFailure(phase, outcome),
+      failure_category: outcome.termination || classifyFailure(phase, outcome),
       duration_ms: Number(durationMs.toFixed(3)),
       started_at: startedAt,
       executed_at: isoNow(),
@@ -120,5 +120,5 @@ export async function run(projectRoot, evidenceDir, environment = process.env) {
     commands
   };
 }
-async function main() { let args; try { args = parseArgs(process.argv.slice(2)); if (args.help) { console.log("运行 YSS 脚手架真实验证命令\n用法: node scripts/run_scaffold_verification.mjs --project-root <dir> --evidence-dir <dir>"); return 0; } const reportPath = path.join(args.evidenceDir, "scaffold-verification.json"); try { const report = await run(args.projectRoot, args.evidenceDir); await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); console.log(`${report.status}: ${reportPath}`); return report.status === "passed" ? 0 : 1; } catch (error) { const report = { verification_mode: "controlled-generation", project_root: args.projectRoot, generated_at: isoNow(), status: "failed", failure_category: "verification-preflight", error: error.message, commands: [] }; await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } } catch (error) { process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } }
+async function main() { let args; try { args = parseArgs(process.argv.slice(2)); if (args.help) { console.log("运行 YSS 脚手架真实验证命令\n用法: node scripts/run_scaffold_verification.mjs --project-root <dir> --evidence-dir <dir>"); return 0; } const reportPath = path.join(args.evidenceDir, "scaffold-verification.json"); try { const report = await run(args.projectRoot, args.evidenceDir, process.env, { timeoutMs: args.timeoutMs ?? 0 }); await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); console.log(`${report.status}: ${reportPath}`); return report.status === "passed" ? 0 : 1; } catch (error) { const report = { verification_mode: "controlled-generation", project_root: args.projectRoot, generated_at: isoNow(), status: "failed", failure_category: "verification-preflight", error: error.message, commands: [] }; await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } } catch (error) { process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } }
 if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exitCode = await main();