create-yss-spec 3.5.6 → 3.5.8

package/src/template/asset-runtime.js

@@ -27,6 +27,7 @@ const COMMON = {
     ".template-spec/process/document-writing.md",
     ".template-spec/process/contract-reading.md",
     ".template-spec/process/structured-assets.md",
+    ".template-spec/process/runtime-storage.md",
     ".template-spec/process/schemas/approval-record.schema.json",
     ".template-spec/process/schemas/review-bundle.schema.json",
     ".template-spec/process/templates/lifecycle-checkpoint-template.json",
@@ -53,6 +54,7 @@ const COMMON = {
     ".template-spec/process/templates/user-decision-template.yaml",
     ".template-spec/templates/local-parent-ticket-template.md",
     ".template-spec/templates/approval-record-template.yaml",
+    ".template-spec/templates/review-bundle-template.yaml",
     ".template-spec/templates/review-report-template.md",
     ".template-spec/user-guide/用户手册.md",
   ],
@@ -69,7 +71,9 @@ const COMMON = {
     "scripts/verify-approval-record",
     "scripts/query-lifecycle-context",
     "scripts/prepare-read-only-intake",
+    "scripts/prepare-review-package",
     "scripts/run-read-only-intake",
+    "scripts/runtime-store",
     "scripts/contract",
     "scripts/check-plan-stage-coverage",
     "scripts/stage-tracking",
@@ -139,7 +143,6 @@ const STAGES = Object.freeze({
       ".template-spec/process/delivery-preflight.md",
       ".template-spec/templates/release-note-template.md",
       ".template-spec/templates/retro-report-template.md",
-      ".template-spec/templates/review-bundle-template.yaml",
     ],
     scripts: ["scripts/preflight-delivery"],
     skills: [],

package/src/template/instance-runtime.js

@@ -8,6 +8,7 @@ const { treeHash } = require("../template-hash");
 const { targetPath, pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
 const { validateTemplateSnapshot } = require("../validation/snapshot");
 const { validateTemplateMetadata } = require("../validation/metadata");
+const { identityForPaths } = require("../content-identity");
 const { distributionForVariables, isIncludedInstancePath, selectedSkillLock, renderInstanceSkillSupplyChain, renderInstanceDesignSkillFile } = require("./distribution-runtime");
 const { ASSET_PROFILE, assetPaths } = require("./asset-runtime");
 const {
@@ -143,6 +144,7 @@ function readTargetIdentity(targetDir) {
 }
 
 function renderTemplateFile(relativePath, content, variables) {
+  const skillPreflight = "\n\n专项技能调用前，运行 `scripts/query-lifecycle-context --work-unit <当前工作单元> --check-skills`；多运行时用 `--agent-runtime`，已确认条件用 `--when`。未安装技能先核对结果中的补装计划，在既有任务授权内应用后重验；漂移、冲突和版本不匹配暂停当前调用，不自动覆盖或迁移。\n";
   const distribution = variables.distribution || distributionForVariables(variables, BUNDLED_TEMPLATE_ROOT);
   if (relativePath === "skills-lock.json") return selectedSkillLock(content, distribution);
   if (relativePath === "scripts/lib/skill-supply-chain.mjs" && distribution.mode === "selected") return renderInstanceSkillSupplyChain(content);
@@ -155,9 +157,9 @@ function renderTemplateFile(relativePath, content, variables) {
   }
   if (relativePath === ".template-spec/user-guide/用户手册.md" && distribution.mode === "selected") {
     if (distribution.assetProfile !== ASSET_PROFILE) {
-      return `# ${variables.projectName} 用户手册\n\n本仓是 \`project-instance\`，用于 ${variables.businessDomain} 的研发资产。先阅读根 [AGENTS.md](../../AGENTS.md)、[CONTEXT.md](../../CONTEXT.md) 与 [生命周期资产索引](../process/lifecycle-artifact-map.md)。\n\n阶段派发前，由 Agent 运行 \`create-yss-spec skills ensure <skill-id...> --plan\` 核对依赖，再运行 \`--apply\` 安装。旧实例继续沿用既有文件分发范围；增加平台使用 \`create-yss-spec skills runtime add <codex|cursor|pi> --plan/--apply\`。CLI 快照必须与实例记录的模板提交一致；升级 CLI 后先运行 \`create-yss-spec sync\`。\n\n项目校验运行 \`scripts/verify-project-instance\`。\n`;
+      return `# ${variables.projectName} 用户手册\n\n本仓是 \`project-instance\`，用于 ${variables.businessDomain} 的研发资产。先阅读根 [AGENTS.md](../../AGENTS.md)、[CONTEXT.md](../../CONTEXT.md) 与 [生命周期资产索引](../process/lifecycle-artifact-map.md)。\n\n阶段派发前，由 Agent 运行 \`create-yss-spec skills ensure <skill-id...> --plan\` 核对依赖，再运行 \`--apply\` 安装。旧实例继续沿用既有文件分发范围；增加平台使用 \`create-yss-spec skills runtime add <codex|cursor|pi> --plan/--apply\`。CLI 快照必须与实例记录的模板提交一致；版本不匹配时先核对匹配的 CLI 或 \`create-yss-spec sync --plan\`，不自动扩展同步范围。\n\n项目校验运行 \`scripts/verify-project-instance\`。\n` + skillPreflight;
     }
-    return `# ${variables.projectName} 用户手册\n\n本仓是 \`project-instance\`，用于 ${variables.businessDomain} 的研发资产。先阅读根 [AGENTS.md](../../AGENTS.md)、[CONTEXT.md](../../CONTEXT.md) 与 [生命周期资产索引](../process/lifecycle-artifact-map.md)。\n\n初始化安装分诊与 Plan 入口资产、三项入口 Skill 与所选 Agent 平台。进入后续阶段前，运行 \`create-yss-spec assets ensure <stage-id> --plan\` 核对文件，再运行 \`--apply\` 原子安装；专项 Skill 使用 \`create-yss-spec skills ensure <skill-id...> --plan/--apply\`，会补齐该 Skill 引用的实例文件。增加平台使用 \`create-yss-spec skills runtime add <codex|cursor|pi> --plan/--apply\`。CLI 快照必须与实例记录的模板提交一致；升级 CLI 后先运行 \`create-yss-spec sync\`。\n\n项目校验运行 \`scripts/verify-project-instance\`；实例 CI 应执行该命令和项目实际的构建、测试。\n`;
+    return `# ${variables.projectName} 用户手册\n\n本仓是 \`project-instance\`，用于 ${variables.businessDomain} 的研发资产。先阅读根 [AGENTS.md](../../AGENTS.md)、[CONTEXT.md](../../CONTEXT.md) 与 [生命周期资产索引](../process/lifecycle-artifact-map.md)。\n\n初始化安装分诊与 Plan 入口资产、入口 Skill 与所选 Agent 平台。进入后续阶段前，运行 \`create-yss-spec assets ensure <stage-id> --plan\` 核对文件，再运行 \`--apply\` 原子安装；专项 Skill 使用 \`create-yss-spec skills ensure <skill-id...> --plan/--apply\`，会补齐该 Skill 引用的实例文件。增加平台使用 \`create-yss-spec skills runtime add <codex|cursor|pi> --plan/--apply\`。CLI 快照必须与实例记录的模板提交一致；版本不匹配时先核对匹配的 CLI 或 \`create-yss-spec sync --plan\`，不自动扩展同步范围。\n\n项目校验运行 \`scripts/verify-project-instance\`；实例 CI 应执行该命令和项目实际的构建、测试。\n` + skillPreflight;
   }
   if (distribution.mode === "selected" && relativePath === ".template-spec/design/README.md") {
     return content.replace(/^.*design-system-sync\.yaml.*\n/m, "");
@@ -188,9 +190,9 @@ function renderTemplateFile(relativePath, content, variables) {
     const base = rendered.replace(/## 4\. \`template-source\` 模板维护路由[\s\S]*?(?=## 5\.)/, "")
       .replace(/\| 影响面、\`not-applicable\`、模板维护强度 \|[^\n]*\n/, "| 影响面与 `not-applicable` | `.template-spec/process/harness-process-tailoring.md` |\n");
     const guidance = distribution.assetProfile === ASSET_PROFILE
-      ? "## 按需阶段资产与 Skill\n\n进入后续生命周期阶段前，运行 `create-yss-spec assets ensure <stage-id> --plan` 查看完整依赖，核对后运行 `--apply`。专项任务根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。缺少阶段资产时先补装，不以缺文件推定门禁不适用。若 CLI 快照与实例模板提交不一致，先运行 `create-yss-spec sync`。\n"
-      : "## 按需 Skill\n\n此实例继续沿用原文件分发范围。阶段派发或专项任务开始前，根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。若 CLI 快照与实例模板提交不一致，先运行 `create-yss-spec sync`。\n";
-    return `${base}\n${guidance}`;
+      ? "## 按需阶段资产与 Skill\n\n进入后续生命周期阶段前，运行 `create-yss-spec assets ensure <stage-id> --plan` 查看完整依赖，核对后运行 `--apply`。专项任务根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。缺少阶段资产时先补装，不以缺文件推定门禁不适用。若 CLI 快照与实例模板提交不一致，先核对匹配的 CLI 或 `create-yss-spec sync --plan`；不自动扩展同步范围。\n"
+      : "## 按需 Skill\n\n此实例继续沿用原文件分发范围。阶段派发或专项任务开始前，根据 .template-spec/agents/yss-skill-registry.yaml 选定 Skill，运行 `create-yss-spec skills ensure <skill-id...> --plan`，核对后运行 `--apply`。若 CLI 快照与实例模板提交不一致，先核对匹配的 CLI 或 `create-yss-spec sync --plan`；不自动扩展同步范围。\n";
+    return `${base}\n${guidance}${skillPreflight}`;
   }
 
   if (relativePath === "README.md") {
@@ -428,11 +430,16 @@ function loadTemplateMetadata(targetDir) {
 
 function collectManagedFiles(desiredOperations) {
   const managedFiles = {};
-  for (const operation of desiredOperations) {
-    if (operation.relativePath === "README.md" || pathKind(operation.targetPath) !== "file") continue;
+  const files = desiredOperations.filter((operation) => operation.relativePath !== "README.md" && pathKind(operation.targetPath) === "file");
+  // One batched Git identity per repository, recorded alongside the legacy
+  // sha256 contentHash so older CLIs keep reading the same metadata.
+  const identities = identityForPaths(files.map((operation) => operation.targetPath));
+  for (const operation of files) {
+    const identity = identities.get(operation.targetPath);
     managedFiles[operation.relativePath] = {
       type: operation.type,
       contentHash: fileHash(operation.targetPath),
+      ...(identity ? { identity } : {}),
     };
   }
   return managedFiles;
@@ -483,13 +490,22 @@ function buildNextSyncMetadata(metadata, syncPlan, {
   delete nextManagedFiles["README.md"];
   for (const relativePath of syncPlan.alreadyMissing || []) delete nextManagedFiles[relativePath];
   for (const relativePath of syncPlan.pruned || []) delete nextManagedFiles[relativePath];
+  const desiredFiles = syncPlan.desiredOperations.filter((operation) => pathKind(operation.targetPath) === "file");
+  const identities = identityForPaths(desiredFiles.map((operation) => operation.targetPath));
   for (const operation of syncPlan.desiredOperations) {
     if (pathKind(operation.targetPath) !== "file") continue;
     const currentHash = currentHashes?.[operation.relativePath] ?? fileHash(operation.targetPath);
     if (currentHash === operation.desiredHash || operation.relativePath === "skills-lock.json") {
+      // Keep the recorded identity while the content hash is unchanged so a sync
+      // with nothing to do stays byte-identical (no churn, no needless backup).
+      const previousRecord = metadata.managedFiles?.[operation.relativePath];
+      const identity = previousRecord?.contentHash === currentHash && previousRecord.identity
+        ? previousRecord.identity
+        : identities.get(operation.targetPath);
       nextManagedFiles[operation.relativePath] = {
         type: operation.type,
         contentHash: currentHash,
+        ...(identity ? { identity } : {}),
       };
     }
   }

package/src/validation/metadata.js

@@ -100,6 +100,14 @@ function validateTemplateMetadata(metadata, {
         `模板元数据 managedFiles.${relativePath}.generatorVersion 必须是正整数`,
       );
     }
+    if (
+      record.identity !== undefined &&
+      !/^(git-sha1:[0-9a-f]{40}|git-sha256:[0-9a-f]{64}|sha256:[0-9a-f]{64})$/.test(record.identity)
+    ) {
+      throw new Error(
+        `模板元数据 managedFiles.${relativePath}.identity 非法`,
+      );
+    }
   }
 
   if (metadata.metadataSchemaVersion === currentSchemaVersion) {

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": "fbe4084276a8fe9a8f59e58481f2913133346eaf",
+  "source_revision": "79e66e694a378d78f06c63399a494d0a69543ba3",
   "adaptation_ref": ".template-source/agents/strategic-design-skills-integration.md",
   "skills": [
     {

package/template/.agents/skills/alibaba-java-code-style/SKILL.md

@@ -3,50 +3,44 @@ name: alibaba-java-code-style
 description: 应用阿里巴巴 Java 手册审查或实现 Java 代码；按当前项目框架与数据库基线选择适用规范。
 ---
 
-# Alibaba Java Code Style
+# 阿里巴巴 Java 规范
 
-This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into execution rules for Codex. Treat rules marked mandatory as review blockers unless the repository's own `AGENTS.md`, security constraints, or existing framework conventions explicitly require a different pattern.
+本 Skill 从用户提供的《阿里巴巴 Java 开发手册》1.4.0 提炼适用规范。`mandatory` 违规阻断审查，除非仓库 `AGENTS.md`、安全约束或现有框架约定明确要求不同模式；例外须有依据。`recommended` / `reference` 保留建议等级，不因进入下文检查提要变为强制规则。
 
-## Workflow
+## 工作流
 
-1. Identify the touched surface:
-   - Java source, naming, constants, OOP, collections, concurrency, control flow, comments: read `references/java-programming.md`.
-   - Exceptions, logging, unit tests, or security: read `references/reliability-test-security.md`.
-   - MySQL, ORM/MyBatis, Maven dependencies, layering, server/JVM settings, or design artifacts: read `references/database-engineering-design.md`.
-2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
-3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
-4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
-5. For auth, payment, encryption, SQL, migrations or public-library changes, check the current contract and actual authorization. Continue an already authorized repair with its required verification; produce a draft or `TODO-HUMAN-REVIEW` only for a real missing decision or approval, and identify that gap.
+1. 按影响面读取对应规范：Java 命名、常量、OOP、集合、并发、控制流和注释读 [Java 编程](references/java-programming.md)；异常、日志、测试或安全读 [可靠性与安全](references/reliability-test-security.md)；MySQL、ORM/MyBatis、Maven、分层、服务器/JVM 或设计资产读 [工程与数据库](references/database-engineering-design.md)。
+2. 先执行适用 mandatory，再按实际风险采用 recommended；审查报告保留规则等级。建议仅在产生真实风险或处于本次范围时报告。
+3. 实现优先复用工程框架与已有生成能力，不新增重复基础设施。
+4. 认证、付款、加密、SQL、迁移或公共库变更先核验当前合同及实际授权。已授权修复继续完成适用验证；仅真实缺决定或批准时形成草案 / `TODO-HUMAN-REVIEW`，并说明缺口。
 
-## Core Priorities
+## 适用原则
 
 - 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
-- Keep names readable, English, and consistent with Java layer conventions.
-- Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
-- Make logs useful without wasting CPU, disk, or alert budget.
-- Keep unit tests automatic, independent, repeatable, and close to public behavior.
-- Bind SQL parameters, define explicit ORM mappings, and never rely on string-concatenated SQL.
-- Preserve layering: web/controller code validates and adapts; service/manager code owns business orchestration; DAO/repository code owns persistence.
-
-## Review Checklist
-
-- Naming and formatting are consistent: camel case, constants, package names, braces, spacing, line length, UTF-8/Unix line endings.
-- POJO, DTO, DO, VO, Query, enum, interface, implementation, and test names follow the expected suffixes and boolean naming rules.
-- `equals`, `hashCode`, wrapper comparisons, `toString`, `serialVersionUID`, constructors, access modifiers, and getters/setters avoid known pitfalls.
-- Collection code avoids unsafe `subList`, `Arrays.asList`, raw `toArray`, foreach removal, null-unsafe maps, and invalid comparators.
-- Thread code uses named thread pools, avoids `Executors` factories in production code, and handles locking order, date formatting, and scheduled tasks safely.
-- Exceptions are handled at the right layer, logged once with context and stack, and never swallowed or used for normal control flow.
-- Tests use assertions, avoid external dependence, live under `src/test/java`, and cover boundaries, correct cases, design cases, and error cases.
-- Security-sensitive inputs are validated, authorized, escaped, CSRF-protected, rate-limited, and never concatenated into SQL.
-- MySQL DDL/SQL/ORM code uses explicit fields, mappings, indexes, timestamps, `#{}`
-  parameter binding, and avoids dangerous cascades, stored procedures, `select *`, and uncontrolled pagination.
-
-## Source
-
-Based on the user-provided PDF: `阿里巴巴 Java 开发手册` version 1.4.0, Alibaba Group technical team, update date 2018-05-20.
+- 名称使用清晰英文标识并遵循当前 Java 分层约定。
+- 核验 null、相等、包装类型比较、集合和并发的运行时边界，不能以编译通过代替行为正确。
+- 日志有诊断用途，并控制 CPU、磁盘和告警成本。
+- 单元测试自动、独立、可重复，围绕公开行为验证。
+- SQL 使用参数绑定与显式 ORM 映射，不依赖字符串拼接。
+- 按已登记架构保持职责：Web/controller 校验和适配，service/manager 编排业务，DAO/repository 持有持久化。
+
+## 检查提要
+
+- 命名与格式：camel case、常量、包名、括号、间距、行长、UTF-8/Unix 换行；类型后缀和 boolean 命名符合适用规范。
+- 对象语义：`equals/hashCode`、包装类型比较、`toString`、`serialVersionUID`、构造器、可见性和访问器。
+- 集合：`subList`、`Arrays.asList`、`toArray`、foreach 删除、null map 和 comparator 的边界。
+- 并发：命名线程池、生产 `Executors` 工厂限制、锁顺序、日期格式和定时任务。
+- 异常：正确分层、上下文与堆栈、避免重复日志、不吞异常、不用于普通控制流。
+- 测试：断言、外部依赖隔离、`src/test/java` 与边界/正确/设计/错误场景。
+- 安全：按真实输入与认证方式核验校验、授权、转义、CSRF、限流和 SQL 参数绑定，不能泛用某项检查豁免其他风险。
+- MySQL：仅适用存储核验显式字段、映射、索引、时间戳与 `#{}` 绑定，以及危险级联、存储过程、`select *` 和分页边界。
+
+## 来源
+
+用户提供的《阿里巴巴 Java 开发手册》1.4.0，阿里巴巴集团技术团队，更新于 2018-05-20；具体条款等级保留在对应 references 中。
 
 ## 阶段 7 执行结果
 
 - 消费当前合同版本、changed files 和 verification results，只审查合同允许范围。
-- 必须把 mandatory violation 返回为 `violation`，并提供文件/位置/规则证据；高风险项保留 `TODO-HUMAN-REVIEW`。
+- 适用 mandatory violation 返回 `violation`，附文件/位置/规则证据；高风险项仅在当前合同确有未满足人工决定或批准要求时保留 `TODO-HUMAN-REVIEW`。
 - 按统一 `YSS Skill Execution Result` 返回审查证据、偏离和新增安全/SQL/公共 API 影响，不得仅输出“符合规范”。

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

@@ -25,10 +25,10 @@ When the current repository contains `yss-project.yaml`, these rules override th
   node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json docs/architecture/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
 
   # template-source
-  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.archify.json .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
+  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.archify.json)" "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.html)" --quality showcase
   ```
 
-- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use `.template-source/evidence/maintenance/diagrams/<diagram-id>/`. The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
+- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use the current workspace's external `maintenance:diagrams/<diagram-id>/` (resolve with `scripts/maintenance-path`). The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
 - The safe wrapper rejects `--open`, non-HTML targets, symlink escapes, unrelated existing files, and stable source/output pairs outside those roots. Do not bypass it with the raw `deliver` or `preview` commands in a YSS repository.
 
 ## Fast authoring path

package/template/.agents/skills/archify/scripts/yss-safe-deliver.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const skillRoot = path.resolve(scriptDirectory, '..');
@@ -93,11 +93,12 @@ function assertReplaceableReceipt(receipt) {
   if (parsed?.yssArchifyReceipt !== true) fail(`拒绝覆盖非 YSS Archify receipt: ${receipt}`);
 }
 
-function stableContract(projectRoot, mode, input, output) {
+async function stableContract(projectRoot, mode, input, output) {
   const relativeBase = mode === 'project-instance'
     ? 'docs/architecture/diagrams'
-    : '.template-source/evidence/maintenance/diagrams';
-  const base = path.join(projectRoot, relativeBase);
+    : 'maintenance:diagrams';
+  const base = mode === 'project-instance' ? path.join(projectRoot, relativeBase)
+    : (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput(relativeBase, { root: projectRoot });
   const relativeOutput = path.relative(base, output);
   const segments = relativeOutput.split(path.sep);
   if (segments.length !== 2 || !diagramIdPattern.test(segments[0])) {
@@ -139,7 +140,10 @@ const temporaryBase = fs.realpathSync(os.tmpdir());
 // parent symlink resolves into the OS temporary directory. Otherwise the
 // temporary-delivery exception could be used to escape the stable output root.
 const requestedWithinProject = requestedProjectRoot !== null;
-const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output);
+const projectMode = projectRoot ? repositoryMode(projectRoot) : null;
+const templateDiagramBase = projectMode === 'template-source'
+  ? (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput('maintenance:diagrams', { root: projectRoot }) : null;
+const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output) && !(templateDiagramBase && isWithin(templateDiagramBase, output));
 let mode = null;
 let receipt;
 let allowedBase;
@@ -150,7 +154,7 @@ if (isTemporary) {
 } else {
   if (!projectRoot) fail('稳定交付必须从包含 yss-project.yaml 的仓库内运行');
   mode = repositoryMode(projectRoot);
-  const contract = stableContract(projectRoot, mode, input, output);
+  const contract = await stableContract(projectRoot, mode, input, output);
   allowedBase = contract.base;
   receipt = contract.receipt;
 }

package/template/.agents/skills/archify/test/yss-safe-deliver.test.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
+import { resolveMaintenanceOutput } from '../../../../scripts/lib/maintenance-storage.mjs';
 import { fileURLToPath } from 'node:url';
 
 const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -12,6 +13,12 @@ const example = path.join(skillRoot, 'examples', 'web-app.architecture.json');
 
 function repository(mode = 'project-instance') {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'yss-archify-safe-'));
+  if (mode === 'template-source') {
+    fs.mkdirSync(path.join(root, 'scripts/lib'), { recursive: true });
+    for (const name of ['maintenance-storage.mjs', 'runtime-store.mjs', 'repository-mode.mjs']) fs.copyFileSync(path.resolve(skillRoot, '../../../scripts/lib', name), path.join(root, 'scripts/lib', name));
+    fs.mkdirSync(path.join(root, 'scripts/vendor'), { recursive: true });
+    fs.copyFileSync(path.resolve(skillRoot, '../../../scripts/vendor/yaml.mjs'), path.join(root, 'scripts/vendor/yaml.mjs'));
+  }
   fs.writeFileSync(path.join(root, 'yss-project.yaml'), `schema_version: 1\nrepository_mode: ${mode}\n`);
   return root;
 }
@@ -104,9 +111,9 @@ test('delivers a paired project artifact and an auditable receipt', () => {
   assert.equal(receipt.archify.validation.warnings, 0);
 });
 
-test('uses the template-source evidence root for stable maintenance diagrams', () => {
+test('uses the external workspace maintenance root for stable diagrams', () => {
   const root = repository('template-source');
-  const directory = path.join(root, '.template-source', 'evidence', 'maintenance', 'diagrams', 'workflow-map');
+  const directory = resolveMaintenanceOutput('maintenance:diagrams/workflow-map', { root });
   fs.mkdirSync(directory, { recursive: true });
   const input = path.join(directory, 'workflow-map.archify.json');
   const output = path.join(directory, 'workflow-map.html');

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

@@ -3,7 +3,7 @@ name: code-review
 description: 审查分支、PR、固定候选或工作树改动，按仓库规范、Spec 及适用 UI 还原要求报告有证据的缺陷。
 ---
 
-Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
+Review a pinned candidate: all applicable axes initially, then affected conclusions and dependencies:
 
 - **Standards** — does the code conform to this repo's documented coding standards **and**, for YSS slices, the specialist check inputs compiled in [yss-review-standards.md](references/yss-review-standards.md)?
 - **Spec** — does the code faithfully implement the originating issue / spec?
@@ -11,13 +11,13 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 
 普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
-If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+角色表编译 `review_context` / `skill_source.review_skills`（只读）；见协作规则，不授予实现权限。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## 文档写作
 
-撰写审查报告时，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+撰写审查报告时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。作用域仅限当前产物，派发时传递条件及引用。
 
 ## Process
 
@@ -38,27 +38,35 @@ Look for the originating spec, in this order:
 
 Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `.template-spec/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
-For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
+Resolve backend roots from the registered project and Slice scope; exclude frontend, vendor, unrelated submodules and unregistered roots. Assess both `yss-repository` and `yss-mybatis` for every backend candidate, including impact, selected Profile and current component source index per the standards reference. Without persistence impact, record concrete `not-applicable` reasons for both.
 
-Every backend candidate must explicitly assess `yss-repository` and `yss-mybatis`. When the candidate changes persistence structure, Mapper/XML, SQL, pagination, batch operations, scanning/configuration or data-source behavior, read both skills and the selected Repository Profile; exact component claims also require a current `yss-mybatis` source index. When no persistence impact exists, record a concrete `not-applicable` reason for both instead of silently skipping them.
-
-Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`, remains a source. It does **not** replace YSS or Alibaba specialist inputs.
+Repo coding documents remain sources alongside mandatory YSS / Alibaba inputs.
 
 Standards 检查代码 diff 时读取 [Fowler smell baseline](references/smell-baseline.md)。仓库明确标准优先；smell 只作 judgement call，不升级为硬违规，机器已覆盖项不重复判断。
 
 ### 4. Complete each applicable review axis
 
-默认由当前独立 Reviewer 连续完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
+默认由独立 Reviewer 完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
 
 执行 Standards / Spec 轴时读取 [逐轴检查提纲](references/review-axis-checklists.md)；单 Reviewer 同样使用它。实际派发时传入相同候选、证据和完整 smell baseline；Spec 缺失按提纲明确报告。
 
-普通审查只复验修复影响的结论及其依赖；候选摘要变化后仍须重新绑定当前候选，不能沿用过期证据。未受影响项记录依据后复用。已明确采用下节历史候选/多轴合同的审查继续遵守其约定。
+首轮完整覆盖；修复后依差异、受影响结论 / 行为及依赖定向复验并绑定当前候选，未受影响项有依据地复用。摘要、UI 或 `new_impacts` 不触发全轴兜底，未知先调查。历史两轮同样适用；细则见 [finding 闭环](references/yss-review-standards.md)。
 
 ### 5. Aggregate
 
 仅任务包携带 `review_round`、明确采用历史冻结候选协议时，读取 [两轮收敛合同](references/legacy-convergence.md)。普通审查不因此新增候选冻结或额外审查者。
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+#### 报告与阻断
+
+按 `## Standards`、`## Spec` 分别呈现原报告或等义整理后的结论；UI 影响另列 `## UI fidelity`。专项表填写在 `.template-spec/templates/review-report-template.md` 的 Standards 证据中，不增加第四轴，也不合并或跨轴重排 findings。适用专项行空白、遗漏 `required_skills` 或 mandatory violation 未关闭时，结果为 `blocked`，不能写 `completed`。
+
+#### 修复后复审
+
+Reviewer 保持只读，将 `violation`、机器检查失败和适用行空白交回原合同路径的实施者。修复后比较差异、重新捕获候选，复审受影响结论与依赖，并明确重新绑定未受影响的证据；不在审查会话中写实现来关闭 finding。
+
+#### 合同失效与延期
+
+`drift`、`new_impacts` 或 `required_skills` 不匹配时，将合同标为 `stale` 并回到 实现合同编译器 调查受影响要求；停止使用旧合同实现，不默认全轴重审。`not-applicable` 只用于未触发影响。mandatory 门禁不能豁免；按原合同修复，或在原流程允许延期时提供完整 `seam-deferred` 记录。
 
 For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 

package/template/.agents/skills/code-review/references/candidate-capture.md

@@ -28,6 +28,6 @@ commit_list_command: <command>
 
 For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
 
-For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New template-maintenance captures use a previously nonexistent external `maintenance:candidates/<id>/` directory, resolved through the workspace maintenance storage, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. New template-maintenance captures reject explicit exclusions: the historical archive-path allowlist is retired, and maintenance material lives outside the repository. Historical schema v1 exclusion lists remain read-only compatible. Candidate manifest schema v2 uses `reference_base: bundle`, the workspace identity, and package-relative stream/diff references. The original candidate byte stream and digest remain unchanged; schema v1 remains read-only compatible. Project-instance and Slice candidates keep their registered repository scope and existing path permissions; the maintenance capture CLI does not grant external paths to them. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
 
 Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.

package/template/.agents/skills/code-review/references/legacy-convergence.md

@@ -2,4 +2,6 @@
 
 仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
 
-For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
+For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. First review covers all applicable checks. After Round 1 repairs, compare the old and new candidates, identify affected conclusions, behavior and dependencies, rereview only that scope, and bind every consumed conclusion to the new digest. Candidate byte changes invalidate the old candidate binding, not every underlying conclusion; reuse requires readable comparison evidence showing unchanged conditions, basis and dependencies. UI impact, `new_impacts` or unknown impact never selects all axes by default or as a fallback; investigate unknown impact before selecting the rereview scope.
+
+For this explicitly selected legacy contract, if Round 2 still has an open `violation`, `drift` or `new_impacts`, the existing evaluator returns `needs-human`; do not silently start Round 3 or rewrite historical states. This compatibility limit is not enabled for ordinary review. Return the unresolved findings and readable evidence to the orchestrator, which separates professional wait, repair / rerouting and missing real decisions, and continues independent authorized work. A new user request still requires a real missing decision or authorization and reviewable assets. No prior approval or report is rewritten.

package/template/.agents/skills/code-review/references/review-axis-checklists.md

@@ -2,6 +2,8 @@
 
 仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
 
+首轮完整覆盖每个适用轴。复审任务额外传入旧 / 新候选差异、受影响结论与行为、直接 / 传递依赖和待复验清单；下列提纲按该清单使用，未受影响结论保留比较证据并绑定当前候选。摘要变化、UI 或 `new_impacts` 不自动选择全部提纲；未知影响先调查。
+
 **Standards sub-agent prompt** — include:
 
 - The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.

package/template/.agents/skills/code-review/references/yss-review-standards.md

@@ -55,8 +55,10 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 
 | 类型 | 动作 |
 |---|---|
-| `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；任何修复使候选失效，必须重新捕获并重跑 Standards、Spec、UI fidelity（若命中）和 fresh verification |
-| `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 实现合同编译器 或更早生命周期阶段；禁止在旧合同上继续编码 |
+| `violation`、机器检查失败、适用行空白、`missing_evidence` | 实现者在**原合同允许路径**内修复；比较差异及受影响结论、行为和依赖，重新捕获并定向复审 / 验证，未受影响项有依据地复用并绑定当前候选 |
+| `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，先调查实际变化及依赖，再回 实现合同编译器 或更早生命周期阶段更新受影响合同；禁止在旧合同上继续编码，不默认全轴复审 |
+
+首轮仍完整覆盖全部适用 Standards、Spec 和条件 UI fidelity。候选摘要变化、UI 影响或未知影响不构成全轴复审的默认或兜底；未知项先调查并阻断其依赖结论。复用证据必须可读，确认原检查条件、依据与依赖未变；当前完成结果重新绑定候选、合同和实际验证，不修改历史报告。
 
 `not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。
 

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

@@ -1,94 +1,52 @@
 ---
 name: competitive-intelligence
-description: Use when researching competitors, market positioning, pricing, feature gaps, customer sentiment, or category trends before Plan, Spec, product strategy, or roadmap decisions.
+description: "执行竞品、市场定位、定价、功能差距与用户口碑调研；复用现有模板输出竞品功能矩阵和深度分析报告，向 Plan、Spec 与产品策略提供证据。"
 ---
 
 # Competitive Intelligence
 
-Source requested for this project: `anthropics/knowledge-work-plugins`, `sales/skills/competitive-intelligence`.
+本项目请求的上游来源：`anthropics/knowledge-work-plugins`，`sales/skills/competitive-intelligence`。保留 YSS 适配；上游更新不能直接覆盖当前合同。
 
-Use this skill when competitive or market facts are needed to shape product Plan, Spec scope, positioning, differentiation, pricing assumptions, or roadmap tradeoffs.
+竞品或市场事实影响 Plan、Spec 范围、定位、差异化、定价假设或路线取舍时使用本技能。`yss-research` 是统一入口和研究证据包所有者，本技能负责专项采集、比较与分析并回传引用结果。直接调用本技能时也按 `yss-research` 的 profile、模式和证据合同组织结果。
 
-## Core Rules
+文档输出按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；只作用于当前产物。正文用简体中文，产品名、来源 URL、API 与 metadata 保持原样。
 
-- Browse or verify current public sources before making factual claims about competitors, pricing, features, market position, funding, partnerships, product releases, or customer sentiment.
-- Separate facts, evidence, and inference. Do not present strategy guesses as verified competitor intent.
-- Prefer primary or near-primary sources: official product pages, docs, pricing pages, changelogs, release notes, filings, case studies, status pages, marketplace listings, reputable analyst reports, and dated customer reviews.
-- Record dates for time-sensitive claims. Pricing, packaging, roadmap, customer logos, and feature availability can change quickly.
-- Persistent project outputs should use Chinese body text by default. Keep competitor names, product names, URLs, API names, and quoted identifiers unchanged.
-- Do not bypass paywalls, scrape private systems, or use confidential information. Public evidence only unless the user explicitly provides internal material.
+## 模式与产物
 
-## Workflow
+读取 `.agents/skills/yss-research/references/competitive-analysis.md`，遵守以下输出选择：
 
-1. Define the intelligence question:
-   - Which product decision will this inform?
-   - Which competitors or substitute workflows are in scope?
-   - Which markets, user segments, regions, editions, or use cases matter?
-   - What must be decided after the research?
-2. Build an evidence plan:
-   - Official sources for product capabilities and pricing.
-   - Documentation and changelogs for depth and recency.
-   - Reviews, community posts, app marketplaces, and job posts for adoption and pain signals.
-   - Analyst, media, or public filings for market context when relevant.
-3. Capture evidence with source links and dates:
-   - Feature / capability evidence.
-   - Pricing / packaging evidence.
-   - UX / onboarding evidence.
-   - Integration / ecosystem evidence.
-   - Customer segment and positioning evidence.
-   - Complaints, workarounds, or unmet needs.
-4. Synthesize:
-   - Competitor positioning.
-   - Table-stakes capabilities.
-   - Differentiators and defensibility.
-   - Gaps and underserved jobs-to-be-done.
-   - Risks if we copy the competitor too closely.
-   - Product opportunities for Spec or roadmap.
-5. Hand off to lifecycle assets:
-   - Update Plan findings in `docs/.scratch/<feature>/plan/`.
-   - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
-   - Return stable user, pain, MVP, non-goal and success criteria to the current lifecycle/strategic owner for its native Plan and Spec work units. Compatibility entries remain explicit-user-only.
-   - Record uncertain claims as assumptions, not requirements.
+| 请求 | 模式 | 默认输出 |
+|---|---|---|
+| 普通竞品探索 | `quick` | 聊天简报＋精简功能矩阵，标明未审计 |
+| 深度、严格、可复现或可审计研究 | `evidence-audited` | 完整矩阵＋深度报告＋研究双文件 |
+| 明确只要矩阵或报告 | 按研究深度与用途确定 | 只输出指定阅读材料；审计模式保留研究双文件 |
+| 正式生命周期批准输入 | `evidence-audited` | 指定阅读材料＋可绑定证据包 |
 
-## Output Shape
+不因选择单一产物而降级审计，也不把普通探索自动升级。竞品策略使用 `strategy-evidence`；技术能力、框架和协议事实按 `technical-evidence` 的一手来源要求审计。
 
-For a quick brief:
+完整矩阵使用 `.template-spec/plan/templates/competitive-matrix-template.md`，报告使用 `.template-spec/plan/templates/competitive-analysis-template.md`。审计模式在同一目录保留 `<slug>-research-brief.md`、`<slug>-evidence.yaml` 和选定的 `<slug>-competitive-matrix.md` / `<slug>-competitive-analysis.md`。报告是附属阅读材料，不替代研究简报。
 
-```markdown
-## 竞品情报简报
+## 执行
 
-### 研究问题
-- <本次情报要支持的产品决策>
+1. 明确研究要支持的决定、竞品 / 替代方案、用户、能力边界、地区、版本 / 套餐、截至日期和问题；优先消费用户提供或已登记材料，记录排除与访问失败。
+2. 核验当前公开资料：产品与定价页、官方文档、更新日志、第一方案例、备案 / 披露和可追溯数据。口碑、采用与痛点可用带日期的评论、社区、市场记录和可检查方法的行业报告，保留来源类别、抽样及独立性限制。
+3. 将事实、来源、观察和 Claim 回传统一证据台账，采集功能、定价 / 套餐、流程、集成、目标用户、定位、投诉与变通方案，寻找反向信号。
+4. 审计模式在 `competitive_analysis` 中登记比较范围、竞品、能力和每个竞品 × 能力结果；矩阵及报告消费同一组结果。`supported / partial / absent / unknown` 分开表达，未查到资料写未知；部分支持须写限制，明确不支持须有适用范围内的已审计依据。
+5. 审计模式从结构化结果渲染功能比较区，区外补充定位、流程、优势、风险、机会及 MVP 建议；`quick` 在聊天中综合简报与精简矩阵。结论引用 Claim / 来源，推断标明依据；来源冲突时保留冲突和置信度，不猜竞品意图。
+6. 审计模式执行研究包校验并交回 `yss-research`；`quick` 回传未审计结果。交接保留事实及审计状态、反向信号、缺口与补证计划、候选术语、产品机会、MVP / 非目标及成功标准建议、下游所有者。由接收者核验后用于其原生工作单元。
 
-### 范围
-- 竞品 / 替代方案：<list>
-- 用户 / 市场：<scope>
-- 时间范围：<date>
+审计模式从仓库根运行渲染与校验：
 
-### 关键结论
-- <fact or inference, clearly labeled>
-
-### 证据表
-| 结论 | 证据 | 来源 | 日期 | 置信度 |
-|---|---|---|---|---|
-
-### 竞品矩阵
-| 维度 | 竞品 A | 竞品 B | 我们的机会 |
-|---|---|---|---|
-
-### Spec 输入
-- 用户 / 痛点：
-- MVP 建议：
-- 非目标范围：
-- 验收或验证建议：
-
-### 风险与待验证假设
-- <assumption>
+```bash
+node .agents/skills/yss-research/scripts/render-competitive-outputs.mjs <slug>-evidence.yaml
+node .agents/skills/yss-research/scripts/validate-research-package.mjs <slug>-research-brief.md <slug>-evidence.yaml
 ```
 
-## Guardrails
+## 分析边界
 
-- Do not treat competitive parity as a product requirement. Convert evidence into user value, MVP boundaries, and testable acceptance criteria.
-- Do not copy competitor UX, text, proprietary workflows, screenshots, or private materials into project artifacts.
-- If sources conflict, show both and mark confidence rather than forcing a false conclusion.
-- If current web access is unavailable, state the limitation and produce only a research plan or hypothesis list.
+- 比较结论记录产品、版本、套餐、地区与日期；未知范围明确写 `unknown`，不能默认为所有版本适用。
+- 默认不生成数字排名。用户明确要求评分时先确认量表、维度 / 权重和依据；未知记不评分，不能计低分或零分。
+- 功能对齐是证据信号，产品机会与优先级属于建议，不直接成为需求。候选术语回交 `domain-modeling`，Plan / Spec 由对应所有者更新；不写 `CONTEXT.md`、Spec、批准或 Ticket 状态。
+- 使用公开证据或用户明确提供的内部材料；不绕过付费墙或访问私有系统，不将竞品专有内容、文本、截图或工作流直接复制到项目产物。
+- 当前来源访问不可用时说明边界，仅根据可访问的固定资料作限定结论，或返回研究计划与假设；不声称已核验当前竞品事实。
+- 结构校验只证明格式、引用和跨文件一致性，来源是否支持结论与推断是否合理仍需研究审核。