create-yss-spec 3.3.1 → 3.3.4

package/README.md

@@ -2,11 +2,11 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-源码候选版本：`3.3.0`。当前固定模板为 `yss-spec-project-template@e9410b9d451393c0d8f642e5f89b3776abb6b8c2`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准。
+源码候选版本：`3.3.4`。当前固定模板为 `yss-spec-project-template@46b29114de53cf4d8d92123006b211d7b3a5a142`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准。
 
 ## 本版模板能力
 
-生命周期新增阶段 5 实现仓库准备聚合门禁，只有仓库身份、架构选择与 Project Scaffold Contract 闭合后才进入可实现切片；DDD、Layered MVC 与 Frontend 脚手架统一消费 v4 合同。`yss-product-lifecycle` 同时改为按注册表和编排合同查询所需上下文的薄路由，初始化和同步会分发对应 Skill、Schema 与校验工具。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
+本版修复生成型 Skill 锁在 `init`、`attach`、`sync` 最终校验前未自动重建的问题。CLI 会在同一事务内刷新 `skills-lock.json`，再运行项目实例校验；刷新或校验失败仍恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
 
 ## 快速开始
 
@@ -46,6 +46,7 @@ CLI 在规划和写入前检查模板家族身份，当前识别：
 - `sync --dry-run`：传统文本预演。
 - `sync --plan`：结构化文本计划。
 - `sync --json`：Plan Schema v1。
+- `sync --prune`：备份并清理仍等于旧受管基线的退出分发文件。
 - `diff / diff --json`：只读差异。
 - `doctor / doctor --json`：只读健康诊断。
 - `update / upgrade`：只更新 CLI 程序，不同步实例资产。
@@ -65,6 +66,8 @@ npx create-yss-spec@latest attach \
 
 npx create-yss-spec@latest sync --target-dir . --dry-run
 npx create-yss-spec@latest sync --target-dir .
+npx create-yss-spec@latest sync --target-dir . --plan --prune
+npx create-yss-spec@latest sync --target-dir . --prune
 ```
 
 同步安全规则：
@@ -73,7 +76,9 @@ npx create-yss-spec@latest sync --target-dir .
 - `replace-with-force` 冲突只有显式 `--force` 才覆盖。
 - `manual` 冲突即使 `--force` 也不会覆盖。
 - `user-owned` / `protected`、gitlink/submodule/detached HEAD、路径越界和中间 symlink 均不可被 force 绕过。
-- 模板删除项只报告，不自动删除。
+- README 仅在初始化时生成，随后由项目维护；attach、sync 和 doctor 均不创建、覆盖或校验。
+- `.gitignore` 只更新 `create-yss-spec managed rules` 标记区，标记外内容原样保留；损坏标记不可被 `--force` 绕过。
+- 模板删除项默认只报告；`--prune` 只清理仍等于可信旧 baseline 的模板所有文件。
 - 校验失败通过 FileTransaction 回滚，并保留必要备份。
 
 ## Programmatic API v1
@@ -97,6 +102,7 @@ const {
 const plan = templatePlan({ targetDir: "/path/to/project" });
 const report = projectDoctor({ targetDir: "/path/to/project" });
 const result = templateApply({ targetDir: "/path/to/project", force: true });
+const pruned = templateApply({ targetDir: "/path/to/project", prune: true });
 ```
 
 返回合同：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.3.1",
+  "version": "3.3.4",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/src/api/_sync-service.js

@@ -3,7 +3,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
-const { pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
+const { pathKind, targetPath, normalizeRelativePath } = require("../filesystem/path-utils");
 const { applyManagedOperation, applyMigrationOperations } = require("../filesystem/apply-plan");
 const { runInTransaction } = require("../filesystem/transaction-runner");
 const { assertBundledFamily, assertTargetFamily } = require("../family-runtime");
@@ -11,8 +11,13 @@ const { gitDirtyWarning } = require("../git/worktree");
 const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
 const { buildSyncPlanFromRuntime } = require("../template/sync-planner-runtime");
 const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const { classifyRemovedFiles } = require("../template/prune-planner");
 const { decorateMetadataOwnership } = require("../template/ownership-metadata");
 const { decorateMetadataLifecycle } = require("../template/lifecycle-metadata");
+const {
+  refreshGeneratedProjectInstance,
+  verifyGeneratedProjectInstance,
+} = require("../template/verification-runtime");
 const {
   PACKAGE_ROOT,
   PACKAGE_MANIFEST,
@@ -94,12 +99,37 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     warning,
     toVersion: PACKAGE_MANIFEST.version,
     getUnmanagedReason: (operation) =>
-      unmanagedPathReason(resolvedTargetDir, operation.relativePath, {
+      operation.unsafeReason || unmanagedPathReason(resolvedTargetDir, operation.relativePath, {
         packageRoot: PACKAGE_ROOT,
       }),
     getPathKind: (operation) => pathKind(operation.targetPath),
     getFileHash: (operation) => fileHash(operation.targetPath),
   });
+  const removedPlan = classifyRemovedFiles({
+    removed: syncPlan.removed.filter((relativePath) => relativePath !== "README.md"),
+    managedFiles: metadata.managedFiles || {},
+    getPathKind: (relativePath) => pathKind(targetPath(resolvedTargetDir, relativePath)),
+    getFileHash: (relativePath) => fileHash(targetPath(resolvedTargetDir, relativePath)),
+    getUnmanagedReason: (relativePath) =>
+      unmanagedPathReason(resolvedTargetDir, relativePath, { packageRoot: PACKAGE_ROOT }),
+  });
+  const readmeOwnershipTransferred = syncPlan.removed.includes("README.md");
+  syncPlan.removed = syncPlan.removed.filter((relativePath) => relativePath !== "README.md");
+  syncPlan.readmeOwnershipTransferred = readmeOwnershipTransferred;
+  Object.assign(syncPlan, removedPlan);
+  plan.changes = plan.changes.map((change) =>
+    change.path === "README.md"
+      ? { ...change, action: "ownership-transfer" }
+      : change.action === "remove-report" && removedPlan.prunable.includes(change.path)
+      ? { ...change, action: "prunable" }
+      : change,
+  );
+  if (readmeOwnershipTransferred) plan.stats.removed -= 1;
+  plan.stats.prunable = removedPlan.prunable.length;
+  plan.stats.retainedRemoved = removedPlan.retainedRemoved.length;
+  plan.prunable = [...removedPlan.prunable];
+  plan.pruned = [];
+  plan.retainedRemoved = [...removedPlan.retainedRemoved];
 
   return {
     targetDir: resolvedTargetDir,
@@ -128,7 +158,7 @@ function assertSyncApplicable(context) {
   }
 }
 
-function applySyncContext(context, { force = false } = {}) {
+function applySyncContext(context, { force = false, prune = false } = {}) {
   assertSyncApplicable(context);
   const { targetDir, metadata, migrationPlan, syncPlan } = context;
   const managedToApply = [
@@ -136,6 +166,7 @@ function applySyncContext(context, { force = false } = {}) {
     ...syncPlan.added,
     ...(force ? syncPlan.forceableConflicts : []),
   ];
+  syncPlan.pruned = prune ? [...syncPlan.prunable] : [];
 
   const { backupPath } = runInTransaction({
     targetDir,
@@ -143,6 +174,8 @@ function applySyncContext(context, { force = false } = {}) {
     affectedPaths: [
       ...affectedPathsForManagedOperations(managedToApply),
       ...affectedPathsForMigration(migrationPlan),
+      ...syncPlan.pruned,
+      "skills-lock.json",
       TEMPLATE_METADATA_FILENAME,
     ],
     execute: (transaction) => {
@@ -150,7 +183,12 @@ function applySyncContext(context, { force = false } = {}) {
         applyManagedOperation(operation, transaction);
       }
       applyMigrationOperations(migrationPlan, transaction);
+      for (const relativePath of syncPlan.pruned) {
+        transaction.remove(targetPath(targetDir, relativePath));
+      }
       verifyGeneratedSyncInstance(targetDir);
+      refreshGeneratedProjectInstance(targetDir);
+      verifyGeneratedProjectInstance(targetDir);
       const nextMetadata = decorateMetadataLifecycle(
         decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan)),
       );
@@ -170,6 +208,7 @@ function applySyncContext(context, { force = false } = {}) {
       skipped: syncPlan.skipped.length,
       removed: syncPlan.removed.length,
       forceApplied: force ? syncPlan.forceableConflicts.length : 0,
+      pruned: syncPlan.pruned.length,
     },
     skipped: syncPlan.skipped.map((operation) => ({
       path: operation.relativePath,
@@ -178,6 +217,10 @@ function applySyncContext(context, { force = false } = {}) {
       mergeStrategy: operation.mergeStrategy || null,
     })),
     removed: [...syncPlan.removed],
+    prunable: [...syncPlan.prunable],
+    pruned: [...syncPlan.pruned],
+    retainedRemoved: [...syncPlan.retainedRemoved],
+    ownershipTransferred: syncPlan.readmeOwnershipTransferred ? ["README.md"] : [],
   };
 }
 

package/src/api/template-apply.js

@@ -4,7 +4,10 @@ const { buildSyncContext, applySyncContext } = require("./_sync-service");
 
 function templateApply(options = {}) {
   const context = buildSyncContext(options);
-  return applySyncContext(context, { force: Boolean(options.force) });
+  return applySyncContext(context, {
+    force: Boolean(options.force),
+    prune: Boolean(options.prune),
+  });
 }
 
 module.exports = { templateApply };

package/src/cli/args.js

@@ -36,6 +36,8 @@ function parseArgs(argv = []) {
       options.apply = true;
     } else if (current === "--force") {
       options.force = true;
+    } else if (current === "--prune") {
+      options.prune = true;
     } else if (current === "--git-init") {
       options.gitInit = true;
     } else if (current === "--include-example-docs") {

package/src/cli/help.js

@@ -32,6 +32,7 @@ OPTIONS
   --force                            init：允许清空非空目录后重新生成
                                      attach / sync：覆盖受管冲突文件；unsafe 路径始终阻断
                                      update：即使已是最新时仍重新安装；npx / 源码目录仍不覆盖
+  --prune                            sync：备份并删除与旧受管基线一致的退出分发文件
   --git-init                         初始化完成后执行 git init
   --include-example-docs             显式保留示例文档（默认开启）
   --no-example-docs                  不生成示例文档
@@ -68,6 +69,8 @@ EXAMPLES
   $ npx create-yss-spec@latest doctor
   $ npx create-yss-spec@latest doctor --json
   $ npx create-yss-spec@latest sync --target-dir . --force
+  $ npx create-yss-spec@latest sync --plan --prune
+  $ npx create-yss-spec@latest sync --prune
   $ npx create-yss-spec update
   $ npx create-yss-spec update --dry-run
   $ npx create-yss-spec upgrade

package/src/cli/index.js

@@ -24,14 +24,12 @@ instanceRuntime.writeTemplateMetadata = function writePolicyAwareTemplateMetadat
   return writeTemplateMetadataBase(targetDir, lifecycleAware, transaction);
 };
 
-const { projectDoctor } = require("../api/project-doctor");
 const { runAttach } = require("../commands/attach");
 const { runDiff } = require("../commands/diff");
-const { renderDoctorText } = require("../commands/doctor");
+const { runDoctor } = require("../commands/doctor");
 const { runInit } = require("../commands/init");
 const { runSync } = require("../commands/sync");
 const { runUpdateCommand } = require("../commands/update");
-const { parseArgs } = require("./args");
 const { printHelp, printVersion } = require("./help");
 const { resolveCommand } = require("./router");
 
@@ -61,14 +59,7 @@ async function runCli(argv = []) {
     return runSync(route.args);
   }
   if (route.command === "doctor") {
-    const options = parseArgs(route.args);
-    const report = projectDoctor({ targetDir: options.targetDir || "." });
-    if (options.json) {
-      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    } else {
-      process.stdout.write(renderDoctorText(report));
-    }
-    return report;
+    return runDoctor(route.args);
   }
   if (route.command === "diff") {
     return runDiff(route.args);

package/src/commands/attach.js

@@ -23,7 +23,10 @@ const {
   buildMetadata,
   writeTemplateMetadata,
 } = require("../template/instance-runtime");
-const { verifyGeneratedAttach } = require("../template/verification-runtime");
+const {
+  refreshGeneratedProjectInstance,
+  verifyGeneratedAttach,
+} = require("../template/verification-runtime");
 
 function assertRequiredOptions(options) {
   if (!options.projectName) {
@@ -155,6 +158,7 @@ function affectedPathsForMigration(migrationPlan) {
 
 function runAttach(argv = []) {
   const options = parseArgs(argv);
+  if (options.prune) throw new Error("--prune 仅适用于 sync");
   assertRequiredOptions(options);
 
   if (options.dryRun && options.apply) {
@@ -192,7 +196,7 @@ function runAttach(argv = []) {
     migration: migrationPlan,
     warning,
     getUnmanagedReason: (operation) =>
-      unmanagedPathReason(targetDir, operation.relativePath, {
+      operation.unsafeReason || unmanagedPathReason(targetDir, operation.relativePath, {
         packageRoot: PACKAGE_ROOT,
       }),
     getPathKind: (operation) => pathKind(operation.targetPath),
@@ -242,6 +246,7 @@ function runAttach(argv = []) {
     affectedPaths: [
       ...affectedPathsForManagedOperations(managedToApply),
       ...affectedPathsForMigration(migrationPlan),
+      "skills-lock.json",
       TEMPLATE_METADATA_FILENAME,
     ],
     execute: (transaction) => {
@@ -249,6 +254,7 @@ function runAttach(argv = []) {
         applyManagedOperation(operation, transaction);
       }
       applyMigrationOperations(migrationPlan, transaction);
+      refreshGeneratedProjectInstance(targetDir);
       verifyGeneratedAttach(targetDir);
       writeTemplateMetadata(
         targetDir,

package/src/commands/diff.js

@@ -7,6 +7,7 @@ const { projectDiff } = require("../api/project-diff");
 
 function runDiff(argv = []) {
   const options = parseArgs(argv);
+  if (options.prune) throw new Error("--prune 仅适用于 sync");
   const plan = projectDiff({
     targetDir: options.targetDir || ".",
     force: Boolean(options.force),

package/src/commands/doctor.js

@@ -37,7 +37,7 @@ const VERIFIERS = [
   },
   {
     name: "verifier-template",
-    path: "scripts/verify-template",
+    path: "scripts/verify-project-instance",
     args: [],
     requiresGit: true,
   },
@@ -75,6 +75,7 @@ function checkManagedBaseline(report, targetDir, metadata) {
   };
 
   for (const [relativePath, record] of Object.entries(managedFiles)) {
+    if (relativePath === "README.md") continue;
     stats.total += 1;
     if (
       !record ||
@@ -392,6 +393,7 @@ function renderDoctorText(report) {
 
 function runDoctor(argv = []) {
   const options = parseArgs(argv);
+  if (options.prune) throw new Error("--prune 仅适用于 sync");
   const targetDir = normalizeTargetDir(options.targetDir);
   const report = buildDoctorReport(targetDir);
 

package/src/commands/init.js

@@ -27,6 +27,7 @@ const {
 } = require("../template/ownership-runtime");
 const {
   initializeGitRepository,
+  refreshGeneratedProjectInstance,
   verifyGeneratedInit,
 } = require("../template/verification-runtime");
 
@@ -117,6 +118,7 @@ function parentDirectoryOperations(desiredOperations, targetDir) {
 
 async function runInit(argv = []) {
   const options = parseArgs(argv);
+  if (options.prune) throw new Error("--prune 仅适用于 sync");
   if (options.help) {
     printHelp(PACKAGE_MANIFEST.version);
     return;
@@ -135,7 +137,11 @@ async function runInit(argv = []) {
   assertTargetFamily(targetDir);
   const targetState = inspectTargetDir(targetDir, promptedOptions.force);
   const desiredOperations = applyOwnershipToOperations(
-    buildDesiredManagedOperations(targetDir, promptedOptions, "init"),
+    buildDesiredManagedOperations(targetDir, promptedOptions, "init").map((operation) =>
+      operation.relativePath === "README.md"
+        ? { ...operation, ownership: "generated" }
+        : operation,
+    ),
   );
   assertWritableTemplateOperations(desiredOperations);
   const directoryOperations = parentDirectoryOperations(desiredOperations, targetDir);
@@ -157,12 +163,14 @@ async function runInit(argv = []) {
     operation: "init",
     affectedPaths: [
       ...desiredOperations.map((operation) => operation.relativePath),
+      "skills-lock.json",
       TEMPLATE_METADATA_FILENAME,
     ],
     execute: (transaction) => {
       for (const operation of desiredOperations) {
         applyManagedOperation(operation, transaction);
       }
+      refreshGeneratedProjectInstance(targetDir);
       verifyGeneratedInit(targetDir);
       writeTemplateMetadata(
         targetDir,

package/src/commands/sync.js

@@ -69,7 +69,11 @@ function printSyncDryRun(context) {
     (operation) => `unsafe: ${operation.relativePath} (${operation.reason})`,
   );
   printLimitedOperations(
-    syncPlan.removed,
+    syncPlan.prunable || [],
+    (relativePath) => `prunable: ${relativePath}`,
+  );
+  printLimitedOperations(
+    (syncPlan.retainedRemoved || []).map((item) => item.path),
     (relativePath) => `remove-report: ${relativePath}`,
   );
   console.log(`unchanged: ${syncPlan.unchanged.length}`);
@@ -106,7 +110,10 @@ function runSync(argv = []) {
     printMigrationPlan(context.migrationPlan);
   }
 
-  const result = applySyncContext(context, { force: Boolean(options.force) });
+  const result = applySyncContext(context, {
+    force: Boolean(options.force),
+    prune: Boolean(options.prune),
+  });
 
   console.log("同步完成");
   console.log(
@@ -116,6 +123,7 @@ function runSync(argv = []) {
   console.log(`新增文件：${result.stats.added}`);
   console.log(`跳过文件：${result.stats.skipped}`);
   console.log(`删除差异：${result.stats.removed}`);
+  console.log(`安全清理：${result.stats.pruned}`);
 
   if (result.skipped.length > 0) {
     console.log("本地已修改，已跳过：");
@@ -123,12 +131,18 @@ function runSync(argv = []) {
       console.log(`- ${item.path}: ${item.reason}`);
     }
   }
-  if (result.removed.length > 0) {
+  const pruned = new Set(result.pruned || []);
+  const pendingRemoved = result.removed.filter((relativePath) => !pruned.has(relativePath));
+  if (pendingRemoved.length > 0) {
     console.log("模板已移除但未自动删除：");
-    for (const relativePath of result.removed) {
+    for (const relativePath of pendingRemoved) {
       console.log(`- ${relativePath}`);
     }
   }
+  if (result.retainedRemoved.length > 0) {
+    console.log("退出分发面但已保留：");
+    for (const item of result.retainedRemoved) console.log(`- ${item.path}: ${item.reason}`);
+  }
   if (result.backupPath) {
     console.log(`备份目录：${result.backupPath}`);
     console.log(`清理命令：rm -rf ${shellQuote(result.backupPath)}`);

package/src/contracts/apply-result-v1.json

@@ -20,7 +20,8 @@
         "added": { "type": "integer", "minimum": 0 },
         "skipped": { "type": "integer", "minimum": 0 },
         "removed": { "type": "integer", "minimum": 0 },
-        "forceApplied": { "type": "integer", "minimum": 0 }
+        "forceApplied": { "type": "integer", "minimum": 0 },
+        "pruned": { "type": "integer", "minimum": 0 }
       }
     },
     "skipped": {
@@ -40,6 +41,30 @@
     "removed": {
       "type": "array",
       "items": { "type": "string", "minLength": 1 }
+    },
+    "prunable": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "pruned": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "retainedRemoved": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "reason"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "ownershipTransferred": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
     }
   }
 }

package/src/contracts/plan-schema-v1.json

@@ -110,6 +110,26 @@
     "migration": {
       "type": ["object", "null"],
       "additionalProperties": true
+    },
+    "prunable": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "pruned": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "retainedRemoved": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "reason"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
     }
   }
 }

package/src/template/attach-planner.js

@@ -44,6 +44,8 @@ function classifyAttachOperations({
     const currentHash = getFileHash(operation);
     if (currentHash === operation.desiredHash) {
       matched.push(operation);
+    } else if (operation.safeSectionMerge) {
+      identity.push(operation);
     } else if (operation.identityConversion) {
       identity.push(operation);
     } else {

package/src/template/gitignore-section.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const START = "# >>> create-yss-spec managed rules";
+const END = "# <<< create-yss-spec managed rules";
+
+function markerState(content) {
+  const starts = [...String(content).matchAll(new RegExp(`^${START}$`, "gm"))];
+  const ends = [...String(content).matchAll(new RegExp(`^${END}$`, "gm"))];
+  if (starts.length === 0 && ends.length === 0) return { kind: "absent" };
+  if (starts.length !== 1 || ends.length !== 1 || starts[0].index >= ends[0].index) {
+    return { kind: "invalid" };
+  }
+  const endOffset = ends[0].index + END.length;
+  return {
+    kind: "valid",
+    start: starts[0].index,
+    end: content[endOffset] === "\r" && content[endOffset + 1] === "\n"
+      ? endOffset + 2
+      : content[endOffset] === "\n" ? endOffset + 1 : endOffset,
+  };
+}
+
+function extractManagedGitignoreBlock(content) {
+  const state = markerState(content);
+  if (state.kind !== "valid") {
+    throw new Error("模板 .gitignore managed rules 标记无效");
+  }
+  const block = content.slice(state.start, state.end);
+  return block.endsWith("\n") ? block : `${block}\n`;
+}
+
+function mergeManagedGitignoreBlock(currentContent, managedBlock) {
+  const block = extractManagedGitignoreBlock(managedBlock);
+  const current = String(currentContent);
+  const state = markerState(current);
+  if (state.kind === "invalid") throw new Error(".gitignore managed rules 标记无效");
+  if (state.kind === "valid") {
+    return `${current.slice(0, state.start)}${block}${current.slice(state.end)}`;
+  }
+  if (!current) return block;
+  return `${current.replace(/\s*$/, "")}\n\n${block}`;
+}
+
+module.exports = {
+  START,
+  END,
+  markerState,
+  extractManagedGitignoreBlock,
+  mergeManagedGitignoreBlock,
+};