create-yss-spec

用于初始化、接管已有项目并持续同步 yss-spec-project-template 研发管理资产的 npm CLI。

源码候选版本：3.5.0。当前固定模板身份、来源状态和摘要见 template.snapshot.json；CLI 运行时不会拉取模板仓库。npm create yss-spec@latest 获取的是实际已发布 npm 包，发布版本请以 npm view create-yss-spec version 为准，并用 create-yss-spec --version 核对当前执行版本。

本版模板能力

本版新增按阶段分发项目实例资产及 assets ensure 命令；旧实例沿用原有分发范围。CLI 在同一事务内刷新生成型 skills-lock.json 并运行项目实例校验，失败时恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。

快速开始

npm create yss-spec@latest
npx create-yss-spec@latest --help
npx create-yss-spec@latest --version

候选源码示例：

npx create-yss-spec@latest \
  --project-name "设备借用" \
  --business-domain "内部设备管理" \
  --target-dir ./equipment-project

四个现行家族与旧实例兼容

CLI 在规划和写入前检查模板家族身份，当前主路线识别：

• create-yss-spec / .yss-template.json
• create-yss-harness-design / .yss-harness-design.json
• create-yss-harness-backend / .yss-harness-backend.json
• create-yss-harness-frontend / .yss-harness-frontend.json

.template-spec/process/harness-profile.yaml 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，--force 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。

旧 create-yss-harness-dev / .yss-harness-dev.json 仍会被识别并拒绝跨家族接管；既有实例按原固定版本维护，不再作为新项目入口。战略、后端和前端分别使用专职 CLI，任何家族都不做跨家族原地迁移。

CLI 能力

• attach：接管已有未管理项目。
• sync：同步受管资产。
• sync --dry-run：传统文本预演。
• sync --plan：结构化文本计划。
• sync --json：Plan Schema v1。
• sync --prune：备份并清理仍等于旧受管基线的退出分发文件。
• diff / diff --json：只读差异。
• doctor / doctor --json：只读健康诊断。
• update / upgrade：只更新 CLI 程序，不同步实例资产。

npx create-yss-spec@latest attach \
  --target-dir . \
  --project-name "项目名称" \
  --business-domain "业务领域" \
  --dry-run

npx create-yss-spec@latest attach \
  --target-dir . \
  --project-name "项目名称" \
  --business-domain "业务领域" \
  --apply

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

同步安全规则：

• 默认只更新未被本地修改的受管文件。
• 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

npm package 根入口已经开放稳定 Node.js API：

const {
  API_VERSION,
  projectDoctor,
  projectDiff,
  templatePlan,
  templateApply,
  toErrorEnvelope,
} = require("create-yss-spec");

当前 API_VERSION = 1。

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 });

返回合同：

• projectDoctor() → Doctor Report v1
• projectDiff() / templatePlan() → Plan Schema v1
• templateApply() → Apply Result v1
• toErrorEnvelope(error) → Error Envelope v1

API 不解析 argv，也不负责 CLI 文本输出；CLI 与未来 MCP 复用同一 Planner / Policy / Security / Transaction 逻辑。

Policy 与 metadata baseline

当前五类 ownership：

• managed
• managed-customizable
• generated
• user-owned
• protected

Customization Policy v1：

• replace-with-force
• manual

Generator Policy v1 为 generated 资产记录稳定 generatorId + generatorVersion。

.yss-template.json 会持久化 ownership/customization/generator policy version/hash，以及每个 managed file 的 ownership、mergeStrategy、generatorId/generatorVersion。Doctor 会报告 policy missing/drift/matched。

模块化架构

历史约 72KB 的 src/cli.js 已退役为兼容桥接。当前执行模型：

CLI / Programmatic API
          ↓
Inspect → Desired State → Policy → Plan → Validate → Transaction → Verify → Metadata

核心机器合同：

• Plan Schema v1
• Error Envelope v1
• Doctor Report v1
• Apply Result v1
• Ownership Policy v1
• Customization Policy v1
• Generator Policy v1

使用未发布候选包

从本仓构建候选包时，先用明确来源重建模板快照，再打包：

YSS_SPEC_TEMPLATE_REPO=/absolute/path/to/yss-spec-project-template \
YSS_SPEC_TEMPLATE_REF=WORKTREE \
node scripts/sync-template.js

npm pack --ignore-scripts

WORKTREE 仅形成 implementation-ready 候选；固定交付必须改用完整 40 位提交。--ignore-scripts 仅用于已经显式重建并核对快照后的候选打包，不代表 npm 发布。

开发验证

npm run test:contracts
npm run test:unit
npm run test:integration
YSS_SPEC_TEMPLATE_REPO=/absolute/path/to/yss-spec-project-template YSS_SPEC_TEMPLATE_REF=WORKTREE npm test
npm pack --dry-run

设计与手册

• CLI v4 模块化
• Machine Contracts v1
• Ownership Policy v1
• Lifecycle Policies v1
• Programmatic API v1
• 完整中文使用手册

治理目录迁移

新实例将分发治理资产安装到 .template-spec/，项目规格产物放在 docs/。已有实例只有显式运行 sync --migrate-layout --plan 审阅后，才运行 sync --migrate-layout --apply；attach 同样支持该开关。迁移保留项目 tracker 配置，缺少可信摘要、旧文件被修改或目标路径冲突时阻断。普通 sync 不自动改变旧实例目录。

固定计划实例迁移

创建实例时默认安装 yss-harness-upgrade；已有实例执行 sync 时自动补齐该技能、已选择运行时的投影和升级协议，并更新技能锁与分发登记。sync --dry-run 只预览，不安装。补装保留原有技能、运行时和阶段选择。

migrate plan --target-dir <项目绝对路径> --output <项目外新计划.json> 生成项目只读计划；migrate apply --plan <计划> 执行固定候选并保存持久归档。计划后输入变化必须重新规划。需要旧布局迁移或安全退出分发清理时，规划阶段显式加入 --migrate-layout / --prune。

migrate status 查看状态；migrate recover 预览中断恢复，migrate rollback 预览最近一次成功迁移的整体回退，均需显式 --apply 才写入。后续修改、跨家族、未知基线及损坏归档阻断，禁止用 force 绕过。所有新接口支持 --json。

旧实例无需先 sync 安装技能：从当前固定版本包的 resources/upgrade-skill/SKILL.md 在项目外读取升级入口及相邻 protocol.md。默认归档保留于用户目录 .yss-harness/archives/；不自动清理。CLI 程序 update/upgrade 与实例迁移相互独立。