create-yss-spec 3.3.1 → 3.3.4

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\/plan\/IDEATION\.md\]\(\.\/docs\/plan\/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,26 @@ 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", []);
+}
+
+function refreshGeneratedProjectInstance(targetDir) {
+  runTemplateVerification(targetDir, "scripts/update-skill-lock", []);
 }
 
 module.exports = {
@@ -151,4 +146,6 @@ module.exports = {
   verifyGeneratedInstance,
   verifyGeneratedInit,
   verifyGeneratedAttach,
+  refreshGeneratedProjectInstance,
+  verifyGeneratedProjectInstance: verifyGeneratedAttach,
 };

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/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/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-implementation-contract-compiler/SKILL.md

@@ -39,7 +39,7 @@ description: Use when a YSS vertical slice is entering implementation, spans mul
 - Harness 内实现路径必须落在 `apps/backend/<project>/` 或 `apps/frontend/<project>/` 的具体项目目录；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径一律阻断。外部实现仓库使用其登记的真实项目根路径。`git-submodule` 使用 `implementation_path_policy: git-submodule-harness-apps`，空 gitlink、detached HEAD 或 `--force` 覆盖挂载点不得脚手架；`inspectWorkingTreeScope.writable` 必须为显式布尔值。
 - 当前用户、缓存、审计、Excel、分布式 ID、请求校验、错误映射、加解密或网关韧性命中时，必须按 `compiler-contract.yaml` 的 `impact_to_capabilities` 补齐入口 capability；不能只在 `boundaries.md` 中提及。仅复用已经验证的平台认证 / 授权能力不算 component impact，不自动增加权限专项 skill。
 - 业务行为使用 `behavior-tdd`；只有机械脚手架/生成物可用 `controlled-generation`，并记录例外和验证。
-- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取 `scaffold-architecture-decisions.yaml`，只接受已达到 `lifecycle-approved` 且 digest 当前的 DDD / Layered MVC 选择；前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只读兼容并可完成已批准生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `gate.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
+- 阶段 5 若命中交付面且无已有工程，按 Project Scaffold Contract schema v4 编译 `controlled-generation` 合同 draft。后端先读取 `scaffold-architecture-decisions.yaml`，只接受已达到 `lifecycle-approved` 且 digest 当前的 DDD / Layered MVC 选择；前端绑定标准模板精确 commit、应用标识、路由、OpenAPI 影响、目标路径和 `init_git` 决定。合同经生命周期批准并持久化后才能运行生成器。历史后端 schema v3 只读兼容并可完成已批准生成；前端只接受 v4。生成与验证完成、仓库登记并通过 `check.implementation-repositories-ready` 后，才编译 Ticket 与业务 Slice Contract。
 - 脚手架合同在编译阶段只能是 `draft` / `ready-for-lifecycle-review` / `blocked`；只有生命周期编排器可以把已持久化脚手架合同标记为 `approved`。脚手架合同只覆盖业务代码前的工程骨架工作单元；生成、基线校验和合同重编译完成后，它不能替代脚手架后的 Slice Implementation Contract。
 - 脚手架输出消费批准的脚手架合同；脚手架后的所有生成后端代码都必须绑定当前批准且版本当前的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 YSS Skill Execution Result。打印命令、`./mvnw validate` 单项通过或脚手架成功不能替代合同批准；生成范围从机械内容变成业务行为时触发完整重路由。
 - 专项结果中的越界路径、缺失证据、`drift`、`violation` 或 `new_impacts` 必须阻断或重路由。

package/template/.agents/skills/yss-mvc-data-analysis-project-initializer/scripts/generate_project.mjs

@@ -23,7 +23,7 @@ async function sharedTools(outputDir, contract) {
   }
   const staging = await mkdtemp(path.join(outputDir, ".skillUtils.staging-"));
   try {
-    for (const relative of [".agents/skills", ".codex/skills", ".claude/skills", ".cursor/skills", ".pi/skills", ".qoder/skills", ".trae/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
+    for (const relative of [".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills", "scripts", "docs/agents", "docs/process", "AGENTS.md", "skills-lock.json"]) {
       await mkdir(path.dirname(path.join(staging, relative)), { recursive: true });
       await cp(path.join(root, relative), path.join(staging, relative), { recursive: true });
     }

package/template/.agents/skills/yss-mvc-scaffold-generator/scripts/lib/runtime.mjs

@@ -11,8 +11,7 @@ export const HARNESS_ROOT = findHarnessRoot();
 export const SHARED_SKILLS_ROOT = path.join(HARNESS_ROOT, ".agents", "skills");
 export const SKILL_UTILS_NAME = "skillUtils";
 export const SKILL_UTILS_DIRECTORIES = [
-  ".agents/skills", ".claude/skills", ".codex/skills", ".cursor/skills",
-  ".pi/skills", ".qoder/skills", ".trae/skills"
+  ".agents/skills", ".codex/skills", ".cursor/skills", ".pi/skills"
 ];
 export const PROJECT_SCRIPT_FILES = [
   "check-agent-environment.mjs", "implementation-path-policy", "repository-mode", "repository-scope-policy",

package/template/.agents/skills/yss-mvc-scaffold-generator/scripts/lib/storage.mjs

@@ -57,7 +57,7 @@ async function populateSkillUtils(destination) {
   const publicSkills = path.join(HARNESS_ROOT, "yss-public-skills.json");
   if (!await exists(publicSkills)) fail(`技能工具包源文件不存在: ${publicSkills}`);
   await cp(publicSkills, path.join(destination, "yss-public-skills.json"));
-  await writeFile(path.join(destination, "skill-utils.yaml"), `schema_version: 1\nkind: yss-skill-utils\ntool_version: 1.0.0\ncompatibility: skill-utils-v1\nsource: ${path.basename(HARNESS_ROOT)}\ncanonical_root: .agents/skills\nprojection_roots:\n  - .codex/skills\n  - .claude/skills\n  - .cursor/skills\nexcluded_skills:\n  - yss-mvc-scaffold-generator\n`, "utf8");
+  await writeFile(path.join(destination, "skill-utils.yaml"), `schema_version: 1\nkind: yss-skill-utils\ntool_version: 1.0.0\ncompatibility: skill-utils-v1\nsource: ${path.basename(HARNESS_ROOT)}\ncanonical_root: .agents/skills\nprojection_roots:\n  - .codex/skills\n  - .cursor/skills\n  - .pi/skills\nexcluded_skills:\n  - yss-mvc-scaffold-generator\n`, "utf8");
 }
 
 export async function ensureSkillUtils(targetDir, { apply = true } = {}) {

package/template/.agents/skills/yss-mvc-scaffold-generator/scripts/verify_project.mjs

@@ -15,11 +15,11 @@ try {
   if (manifest.runtime_java !== "8" || manifest.project_version !== "2.0.0-SNAPSHOT" || manifest.persistence_profile !== "yss-mybatis-plus") throw new Error("Java 8/YSS MyBatis-Plus 技术基线不正确");
   const skillUtils = path.resolve(root, manifest.skill_utils_dir);
   await Promise.all(["skill-utils.yaml", "skills-lock.json", ".agents/skills/yss-product-lifecycle/SKILL.md", ".agents/skills/yss-implementation-contract-compiler/SKILL.md"].map((relative) => required(path.join(manifest.skill_utils_dir, relative))));
-  for (const projection of [".agents", ".claude", ".codex", ".cursor", ".pi", ".qoder", ".trae"]) {
+  for (const projection of [".agents", ".codex", ".cursor", ".pi"]) {
     const nestedGenerator = path.join(skillUtils, projection, "skills", "yss-mvc-scaffold-generator");
     if (await stat(nestedGenerator).then(() => true).catch(() => false)) throw new Error(`skillUtils 不应分发创建期生成器: ${projection}/skills/yss-mvc-scaffold-generator`);
   }
-  for (const forbidden of [".agents", ".claude", ".codex", ".cursor", ".pi", ".qoder", ".trae"]) if (await stat(path.join(root, forbidden)).then(() => true).catch(() => false)) throw new Error(`项目不应携带技能投影目录: ${forbidden}`);
+  for (const forbidden of [".agents", ".codex", ".cursor", ".pi"]) if (await stat(path.join(root, forbidden)).then(() => true).catch(() => false)) throw new Error(`项目不应携带技能投影目录: ${forbidden}`);
   if (JSON.stringify(manifest.modules) !== JSON.stringify(modules)) throw new Error("模块集合或顺序不正确");
   const backendRoot = path.join(root, manifest.backend_root || "");
   await Promise.all(["pom.xml", "mvnw", "mvnw.cmd", ...modules.map((item) => `${item}/pom.xml`)].map((relative) => required(path.join(manifest.backend_root || "", relative))));