sillyspec 3.26.2 → 3.26.4

package/src/run/multi-repo-context.js

@@ -0,0 +1,206 @@
+/**
+ * MultiRepoContext — 跨仓 task 运行时多仓执行上下文（W1 task-01）。
+ *
+ * 设计依据：design §7.1（接口权威定义）+ 决策 D-005/D-006/D-007/D-013。
+ *
+ * 收口 execute 链路 7 个单仓假设点（applyWorktree / validateTaskReviews /
+ * runVerifyTestCheck / generateTaskReviewDrafts 等）——把"主仓=唯一仓库"假设
+ * 抽成 Map<repoKey, RepoEntry>，单仓 change 退化为 {main:{...}} 单值 map 零回归
+ * （GOAL-2），跨仓 change 实时反映各仓 HEAD（约束①）+ 配置错误 fail-closed（约束②）。
+ *
+ * 关键约束：
+ *   - 约束①（D-006）：跨仓仓无 meta.json，base/head 不读 meta。resolveHead 实时
+ *     `git -C <crossRepo> rev-parse HEAD`（不缓存，task 推进后过期）；resolveBase
+ *     用 taskBaseCommit（task 卡 base_commit 锡点，跨仓必传）。
+ *   - 约束②（D-007）：declaredRepos 有 key 不在 repoRegistry → throw；跨仓仓
+ *     `git -C <crossRepo> rev-parse HEAD` 失败 → throw。配置错误不降级，不沿用
+ *     主仓 verifyReviewGitEvidence 的 unavailable 降级（那是环境缺失容错；跨仓
+ *     不可用是用户 local.yaml 配错，性质不同，必须阻断）。
+ *   - D-013：execute 启动时构造一次，进程级缓存贯穿 execute/apply/verify（本模块
+ *     不持有进程级缓存——ctx 实例本身就是进程级单例，由 execute 入口持有）。
+ *
+ * 不涉及生命周期契约（design §7.5）：纯内存对象，不跨进程、不持久化、不入库。
+ */
+
+import { git, gitQuiet } from '../git-helper.js';
+
+/**
+ * @typedef {Object} RepoEntry
+ * @property {string} repoKey        - repo 标识（'main' 或 local.yaml repos: 的键名）
+ * @property {string} gitDir         - git 工作目录（rev-parse/diff/apply 的 cwd）
+ * @property {string} worktreePath   - 子代理工作目录（主仓=worktreePath 或 in-place-fallback 时=cwd；跨仓=跨仓仓根）
+ * @property {string} projectRoot    - apply 目标根（主仓=主仓根；跨仓=跨仓仓根，但跨仓 apply=no-op 不用）
+ * @property {boolean} isMain        - 是否主仓
+ * @property {function} resolveHead  - () => string，实时 git rev-parse HEAD（跨仓不缓存）
+ * @property {function} resolveBase  - (taskBaseCommit?) => string，base 锚点（主仓→meta.baseHash；跨仓→taskBaseCommit 必传）
+ */
+
+export class MultiRepoContext {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.cwd              - 主仓 cwd
+   * @param {string} opts.changeName       - 当前 change 名（读 worktreeManager.getMeta）
+   * @param {Object} [opts.platformOpts]   - 平台选项（specRoot 等，预留，本模块不消费）
+   * @param {string[]} opts.declaredRepos  - 所有 task 卡片声明的 repo: 值（含 'main'）
+   * @param {Map<string,string>} opts.repoRegistry - local.yaml repos: 段解析结果 Map<key, path>
+   * @param {Object} opts.worktreeManager  - WorktreeManager 实例（主仓 meta 读取；in-place-fallback 兜底 cwd）
+   * @throws {Error} 约束②: declaredRepos 中有 repoKey 不在 repoRegistry → 抛错列已注册 repo，阻断 execute
+   *                 约束②: 跨仓仓 git rev-parse 失败（路径不存在/非 git 仓）→ 抛错阻断 execute
+   */
+  constructor({ cwd, changeName, platformOpts, declaredRepos, repoRegistry, worktreeManager }) {
+    if (!cwd) throw new Error('MultiRepoContext: cwd 必传');
+    if (!Array.isArray(declaredRepos)) throw new Error('MultiRepoContext: declaredRepos 必传为数组');
+    if (!(repoRegistry instanceof Map)) throw new Error('MultiRepoContext: repoRegistry 必传为 Map<key,path>');
+    if (!worktreeManager || typeof worktreeManager.getMeta !== 'function') {
+      throw new Error('MultiRepoContext: worktreeManager 必传（需 getMeta 方法）');
+    }
+
+    this.cwd = cwd;
+    this.changeName = changeName;
+    this.platformOpts = platformOpts || {};
+    this.repoRegistry = repoRegistry;
+    this.worktreeManager = worktreeManager;
+
+    // dedupe + 保留声明顺序（同一 repo 多 task 声明只建一项）
+    const seen = new Set();
+    const orderedKeys = [];
+    for (const key of declaredRepos) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        orderedKeys.push(key);
+      }
+    }
+
+    // 约束② fail-closed 预检：declaredRepos ⊆ repoRegistry ∪ {'main'}
+    // main 隐式 = cwd，不要求注册；其余 key 必须在 repoRegistry 命中。
+    const unregistered = orderedKeys.filter(k => k !== 'main' && !repoRegistry.has(k));
+    if (unregistered.length > 0) {
+      const registered = ['main (隐式)', ...repoRegistry.keys()];
+      throw new Error(
+        `MultiRepoContext: 以下 repo 未在 local.yaml repos: 段注册：[${unregistered.join(', ')}]。` +
+        `当前已注册 repo：[${registered.join(', ')}]。` +
+        `请在 local.yaml repos: 段补注册后再启动 execute（约束② fail-closed，跨仓 apply 走错仓=数据所有权事故）。`
+      );
+    }
+
+    const map = new Map();
+    for (const repoKey of orderedKeys) {
+      map.set(repoKey, repoKey === 'main'
+        ? this._buildMainEntry()
+        : this._buildCrossRepoEntry(repoKey, repoRegistry.get(repoKey)));
+    }
+    this.map = map;
+  }
+
+  /**
+   * 主仓 RepoEntry：isMain=true，读 worktreeManager.getMeta 的 baseHash + worktreePath。
+   * in-place-fallback 模式（meta.mode==='in-place-fallback' 或 meta 缺失）worktreePath 兜底为 cwd。
+   * @returns {RepoEntry}
+   * @private
+   */
+  _buildMainEntry() {
+    const meta = this.changeName ? this.worktreeManager.getMeta(this.changeName) : null;
+    const isInPlace = !meta || meta.mode === 'in-place-fallback';
+    const worktreePath = isInPlace ? this.cwd : (meta.worktreePath || this.cwd);
+    const baseHash = meta?.baseHash || null;
+    const gitDir = worktreePath; // 主仓 git 操作 cwd = worktree（或 in-place 的 cwd）
+    const projectRoot = this.cwd;
+
+    return {
+      repoKey: 'main',
+      gitDir,
+      worktreePath,
+      projectRoot,
+      isMain: true,
+      // 主仓 HEAD：从 worktree/cwd 实时取（不缓存）。主仓单仓不变式下也可用 meta.baseHash 作 base，
+      // 但 HEAD 反映 worktree 当前态（子代理可能 commit 推进），故实时取与跨仓一致语义。
+      resolveHead: () => git(gitDir, ['rev-parse', 'HEAD']),
+      // 主仓 base：meta.baseHash（单仓不变式，CLI 创建 worktree 时锡点）。
+      // 跨仓 base 不走这里（resolveBase 必传 taskBaseCommit，由 _buildCrossRepoEntry 闭包消费）。
+      // 主仓忽略 taskBaseCommit 参数——主仓 base 永远锚 meta.baseHash，与单仓行为一致（零回归）。
+      resolveBase: (_taskBaseCommit) => {
+        if (!baseHash) {
+          throw new Error(
+            'MultiRepoContext: 主仓 meta.baseHash 缺失，无法解析 base。' +
+            '可能 worktree 未创建或 meta.json 损坏——请先 sillyspec worktree doctor 检查。'
+          );
+        }
+        return baseHash;
+      },
+    };
+  }
+
+  /**
+   * 跨仓 RepoEntry：isMain=false，gitDir=projectRoot=worktreePath=跨仓仓根。
+   * 构造时 `git -C <crossRepo> rev-parse HEAD` 必须 succeed（约束② fail-closed），
+   * 路径不存在/非 git 仓 → throw 阻断 execute。
+   * @param {string} repoKey
+   * @param {string} crossRepoPath - repoRegistry 解析出的跨仓仓绝对路径
+   * @returns {RepoEntry}
+   * @private
+   */
+  _buildCrossRepoEntry(repoKey, crossRepoPath) {
+    if (!crossRepoPath) {
+      throw new Error(
+        `MultiRepoContext: repo "${repoKey}" 在 local.yaml repos: 段注册但路径为空。` +
+        `请补全路径（约束② fail-closed）。`
+      );
+    }
+    // 约束②：跨仓 git 必须可达。失败 = 路径不存在 / 非 git 仓 / git 异常，一律阻断。
+    // 不沿用主仓 verifyReviewGitEvidence unavailable 降级（design §9 兼容策略表）。
+    let headVerify;
+    try {
+      headVerify = git(crossRepoPath, ['rev-parse', 'HEAD']);
+    } catch (e) {
+      throw new Error(
+        `MultiRepoContext: 跨仓 repo "${repoKey}" git 不可达（路径：${crossRepoPath}）。` +
+        `rev-parse HEAD 失败：${e.message}。` +
+        `请检查 local.yaml repos: 段路径是否正确、目录是否存在且为 git 仓（约束② fail-closed，配置错误不降级）。`
+      );
+    }
+    if (!headVerify) {
+      // git() 返回空串属异常态（无 commit 的空仓 rev-parse HEAD 会非零退出，已被 catch 兜底），
+      // 此处仅作防御性双保险，触发同样走 fail-closed。
+      throw new Error(
+        `MultiRepoContext: 跨仓 repo "${repoKey}"（${crossRepoPath}）rev-parse HEAD 返回空——` +
+        `疑似空 git 仓（无 commit）。跨仓 task 需仓库已有至少一个 commit（约束② fail-closed）。`
+      );
+    }
+
+    return {
+      repoKey,
+      gitDir: crossRepoPath,
+      worktreePath: crossRepoPath,
+      projectRoot: crossRepoPath,
+      isMain: false,
+      // 约束①：跨仓 HEAD 实时取，不缓存（task 推进后过期，每次 resolveHead 反映最新 HEAD）。
+      resolveHead: () => git(crossRepoPath, ['rev-parse', 'HEAD']),
+      // 约束①：跨仓 base = task 卡 base_commit 锡点（必传）。跨仓仓无 meta.json，
+      // 不读 meta；taskBaseCommit 由 task-02 DeclaredRepos 之外的 task 卡 frontmatter 提供。
+      resolveBase: (taskBaseCommit) => {
+        if (!taskBaseCommit) {
+          throw new Error(
+            `MultiRepoContext: 跨仓 repo "${repoKey}" resolveBase 必传 taskBaseCommit（task 卡 base_commit 锡点）。` +
+            `跨仓仓无 meta.json，base 只能由 task 卡片锡点提供（约束①）。`
+          );
+        }
+        return taskBaseCommit;
+      },
+    };
+  }
+
+  /** @returns {RepoEntry|null} */
+  resolve(repoKey) {
+    return this.map.get(repoKey) || null;
+  }
+
+  /** @returns {Map<string, RepoEntry>} */
+  get repos() {
+    return this.map;
+  }
+
+  /** @returns {boolean} 是否含跨仓 task（map.size>1，execute prompt 分叉用） */
+  hasCrossRepo() {
+    return this.map.size > 1;
+  }
+}

package/src/run/prompt.js

@@ -23,6 +23,7 @@ import { stageRegistry } from '../stages/index.js'
 import { resolvePromptIncludes, resolveRuntimeRoot, safeGit, WAIT_MARKER_RE } from './shared.js'
 import { renderStageContract } from '../stage-contract-spec.js'
 import { parseModuleMapSimple } from '../modules.js'
+import { REVIEW_SCHEMA_VERSION } from '../task-review.js'
 
 /**
  * 从 _module-map.yaml 读取模块上下文索引
@@ -218,6 +219,11 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   promptText = promptText.replace(/<now-datetime>/g, nowDatetime)
   promptText = promptText.replace(/<now-timestamp>/g, nowTimestamp)
   promptText = promptText.replace(/<now-date>/g, nowDate)
+  // 替换 {REVIEW_SCHEMA_VERSION} 占位符（task review 示例模板用，值=CLI 当前 REVIEW_SCHEMA_VERSION 常量，
+  // 避免 agent 照抄 design 目标版本与 CLI 写侧常量漂移；与 stage review 契约 renderReviewJsonContract 动态注入同源）
+  if (promptText.includes('{REVIEW_SCHEMA_VERSION}')) {
+    promptText = promptText.replace(/\{REVIEW_SCHEMA_VERSION\}/g, String(REVIEW_SCHEMA_VERSION))
+  }
   // 替换 <change-name> 占位符
   if (changeName && promptText.includes('<change-name>')) {
     promptText = promptText.replace(/<change-name>/g, changeName)

package/src/run/shared.js

@@ -70,6 +70,8 @@ export function assertSafeChangeName(name, label = '变更名') {
 import { buildExecuteSteps } from '../stages/execute.js'
 import { buildPlanSteps } from '../stages/plan.js'
 import { stageRegistry } from '../stages/index.js'
+import { parseRepo, parseRepoRegistry } from '../stages/plan-postcheck.js'
+import { MultiRepoContext } from './multi-repo-context.js'
 
 /**
  * 解析 prompt 中的 {{include: <name>}} 占位符：读包内 templates/prompts/<name>.md 注入。
@@ -689,6 +691,158 @@ export function formatWaitOptions(raw) {
 }
 
 
+/**
+ * 进程级 MultiRepoContext 缓存（D-013 G2：execute 启动构造一次，贯穿 execute/apply/verify 不重建）。
+ *
+ * key = `${cwd} ${changeName}`（cwd 隔离防多仓并发串扰；changeName 隔离防同进程多 change 切换串扰）。
+ * 跨 CLI 命令（execute vs apply vs verify 各是独立进程）各自构造——design §7.2 G2 明确 apply/verify
+ * 「复用 execute 实例，**或**从 review.json.repo + local.yaml repos 反推」，进程级缓存指同一 CLI 命令内复用。
+ *
+ * 失效语义：ctx 是纯内存对象（task-01 不持久化），进程结束自动释放。无需手动清理。
+ * 缓存命中场景：execute 单次 --done 内 getStageSteps（派发）+ completeStageGates（gate）+ 阶段完成
+ * 收尾多次取同一 ctx；apply/verify 同理。fail-closed 抛错不缓存（下次重试重新构造）。
+ */
+const _multiRepoCtxCache = new Map()
+
+/**
+ * 读 local.yaml 原始文本（best-effort，不存在/读失败返 ''）。
+ * 与 sync.js readLocalYamlRaw 同风格，但本模块不引 sync.js（避免循环依赖 + sync.js 非 export）。
+ * local.yaml 路径 = `<cwd>/.sillyspec/local.yaml`（与 sync.js/config-schema.js 一致）。
+ * @param {string} cwd
+ * @returns {string}
+ */
+function readLocalYamlRaw(cwd) {
+  const p = join(cwd, '.sillyspec', 'local.yaml')
+  if (!existsSync(p)) return ''
+  try {
+    return readFileSync(p, 'utf8')
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * 从 plan.md 内容聚合所有 task 卡片声明的 repo:（去重，含 'main' 隐式）。
+ *
+ * design §5.4 execute 启动段 + §7.2：扫 plan.md 所有 task 卡片 frontmatter，用 parseRepo 解析
+ * repo: 字段（缺省='main'），去重后返回数组。'main' 永远隐式在列（主仓 task 不写 repo: 也算主仓）。
+ *
+ * 聚合策略：plan.md 由 plan 阶段生成，task 卡片 frontmatter 形如 `---\nrepo: sillyspec\n...\n---`
+ * （与 task-NN.md 同源）。本函数全局匹配所有 frontmatter 块（`/^---\n([\s\S]*?)\n---/mg`），
+ * 每块重新拼成完整 frontmatter 喂 parseRepo（parseRepo 内部 `^---\n...\n---` 锚开头）。
+ *
+ * @param {string} planContent
+ * @returns {string[]} 去重后的 repo 数组（至少含 'main'）
+ */
+export function aggregateDeclaredRepos(planContent) {
+  const seen = new Set(['main']) // main 永远隐式
+  if (!planContent) return ['main']
+  // 全局匹配所有 frontmatter 块（m 标志让 ^ 匹配每行行首，但此处 ^--- 要求行首 ---，
+  // 配合 [\s\S]*? 非贪婪到下一个 ---）。每块重新拼完整 frontmatter 喂 parseRepo。
+  const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---/gm
+  let match
+  while ((match = fmRegex.exec(planContent)) !== null) {
+    const fmBody = match[1]
+    // 重新拼成 parseRepo 期望的完整 frontmatter（---\n<body>\n---）
+    const repo = parseRepo(`---\n${fmBody}\n---`)
+    if (repo && !seen.has(repo)) seen.add(repo)
+  }
+  return Array.from(seen)
+}
+
+/**
+ * 构造或取进程级 MultiRepoContext 单例（D-013 G2）。
+ *
+ * design §5.4 execute 启动段 + §7.2 G2 + 决策 D-001/D-013：
+ *   - 读 local.yaml repos: 段（parseRepoRegistry）→ repoRegistry Map（main 隐式不注册）
+ *   - 扫 plan.md 所有 task 卡片 repo:（aggregateDeclaredRepos）→ declaredRepos（含 'main'）
+ *   - 构造 MultiRepoContext（约束② fail-closed：未注册 repo / 跨仓 git 不可用抛错阻断）
+ *   - 按 `${cwd} ${changeName}` 缓存，同进程同 change 复用
+ *
+ * **单仓退化**（design §7.2 「main 隐式为 cwd 不用注册」）：local.yaml 无 repos: 段 + 单仓 change
+ * （declaredRepos=['main']）→ repoRegistry=空 Map，MultiRepoContext 退化为 {main:{...}} 单值 map，
+ * hasCrossRepo()=false，所有 ctx 透传点缺省行为零回归（task-01/04/05/06/07/08 各模块 ctx=null 等价）。
+ *
+ * **跨仓 fail-closed**（约束② D-007）：declaredRepos 含 local.yaml 未注册的 repo key，或跨仓仓
+ * git rev-parse 失败 → MultiRepoContext 构造抛错，本函数**不缓存**该错误，原样上抛阻断 execute 启动。
+ *
+ * 缓存语义：命中返回已构造实例；未命中且构造成功则缓存后返回；构造失败不缓存（下次重试重新构造）。
+ *
+ * @param {Object} opts
+ * @param {string} opts.cwd - 主仓 cwd
+ * @param {string} opts.changeName - 当前 change 名
+ * @param {Object} [opts.platformOpts] - 平台选项（specRoot 等，透传给 MultiRepoContext 预留）
+ * @param {boolean} [opts.noCache=false] - 跳过缓存（测试 / 显式重建场景）
+ * @returns {MultiRepoContext|null} changeName/cwd 缺失或无 plan.md 时返回 null（单仓退化，调用方按 ctx=null 处理）
+ * @throws {Error} MultiRepoContext 构造 fail-closed（约束②未注册/跨仓git不可用）
+ */
+export async function getOrCreateMultiRepoContext({ cwd, changeName, platformOpts = {}, noCache = false } = {}) {
+  if (!cwd || !changeName) return null
+  const cacheKey = `${cwd} ${changeName}`
+  if (!noCache && _multiRepoCtxCache.has(cacheKey)) {
+    return _multiRepoCtxCache.get(cacheKey)
+  }
+
+  // 读 plan.md（execute 启动入口的 change 目录），无 plan.md → 无法聚合 declaredRepos → 退化 null
+  const specDir = platformOpts?.specRoot || resolveSpecDir(cwd)
+  const planFile = join(specDir, 'changes', changeName, 'plan.md')
+  let planContent = ''
+  if (existsSync(planFile)) {
+    try {
+      planContent = readFileSync(planFile, 'utf8')
+    } catch {
+      planContent = ''
+    }
+  }
+  if (!planContent) {
+    // 无 plan.md（plan 未完成 / brainstorm 阶段 / quick 等场景）→ 无 task 卡片可扫，
+    // 不构造 ctx（返 null 退化单仓）。跨仓 task 必须 plan.md 落地后才进 execute，此处安全。
+    return null
+  }
+
+  // 聚合 declaredRepos（扫 plan.md task 卡片 repo:）+ 读 local.yaml repos: 段
+  const declaredRepos = aggregateDeclaredRepos(planContent)
+  const repoRegistry = parseRepoRegistry(readLocalYamlRaw(cwd))
+
+  // 构造 WorktreeManager（主仓 meta 读取；与 getStageSteps 同源范式）
+  let worktreeManager
+  try {
+    const { WorktreeManager } = await import('../worktree.js')
+    worktreeManager = new WorktreeManager({ cwd })
+  } catch {
+    // WorktreeManager 不可用 → 退化为最小桩（in-place-fallback 兜底 cwd）
+    worktreeManager = { getMeta: () => null }
+  }
+
+  const ctx = new MultiRepoContext({
+    cwd,
+    changeName,
+    platformOpts,
+    declaredRepos,
+    repoRegistry,
+    worktreeManager,
+  })
+
+  if (!noCache) {
+    _multiRepoCtxCache.set(cacheKey, ctx)
+  }
+  return ctx
+}
+
+/**
+ * 清除进程级 MultiRepoContext 缓存（测试隔离用）。生产代码不需手动清。
+ * @param {string} [cwd]
+ * @param {string} [changeName]
+ */
+export function _clearMultiRepoCtxCache(cwd, changeName) {
+  if (cwd && changeName) {
+    _multiRepoCtxCache.delete(`${cwd} ${changeName}`)
+  } else {
+    _multiRepoCtxCache.clear()
+  }
+}
+
+
 /**
  * 获取阶段的步骤定义（execute 需要动态构建）
  */
@@ -697,14 +851,15 @@ export async function getStageSteps(stageName, cwd, progress, specDir = null) {
     const changeDir = resolveChangeDir(cwd, progress, specDir)
     let planFile = null
     let worktreePath = null
+    let changeName = null
     if (changeDir) {
       const p = join(changeDir, 'plan.md')
       if (existsSync(p)) planFile = p
+      changeName = basename(changeDir)
       // 自动检测 worktree 路径，注入 Wave prompt 的 workdir 指令
       // 修复：之前未传 worktreePath 给 buildExecuteSteps，导致 Wave prompt 缺失工作目录指令，
       // 子代理可能把文件写到主工作区而非 worktree 内，破坏隔离。
       try {
-        const changeName = basename(changeDir)
         const { WorktreeManager } = await import('../worktree.js')
         const wm = new WorktreeManager({ cwd })
         const meta = wm.getMeta(changeName)
@@ -715,7 +870,20 @@ export async function getStageSteps(stageName, cwd, progress, specDir = null) {
         // 无 worktree meta 不阻断——可能是首次启动或 in-place 模式
       }
     }
-    return buildExecuteSteps(planFile, { worktreePath })
+    // W3 task-09：execute 启动入口构造 MultiRepoContext 单例（D-013 G2），贯穿 execute/apply/verify。
+    // 单仓 change（无 repo: / 无 local.yaml repos 段）→ ctx=null 退化单仓零回归（task-08 buildExecuteSteps 缺省 null）。
+    // 跨仓 change 缺注册 / 跨仓 git 不可用 → getOrCreateMultiRepoContext 抛错阻断 execute 启动（约束②）。
+    let ctx = null
+    if (changeName) {
+      try {
+        ctx = await getOrCreateMultiRepoContext({ cwd, changeName, platformOpts: specDir ? { specRoot: specDir } : {} })
+      } catch (e) {
+        // fail-closed 阻断：execute 启动期 ctx 构造失败（未注册 repo / 跨仓 git 不可用），
+        // 抛错让上层 runCommand 把错误返回给 Agent（不降级单仓跑——跨仓 apply 走错仓=数据所有权事故）。
+        throw new Error(`execute 启动失败：跨仓 MultiRepoContext 构造失败（${e.message}）`)
+      }
+    }
+    return buildExecuteSteps(planFile, { worktreePath, ctx })
   }
   if (stageName === 'plan') {
     const changeDir = resolveChangeDir(cwd, progress, specDir)

package/src/stage-review.js

@@ -426,6 +426,7 @@ export function printStageReviewResult(result, context = {}) {
       console.error(`   - ${err}`)
     }
     console.error(`\n   提示：tier=independent 要求独立审查子代理产出 review.json，补全后重新 --done`)
+    console.error(`   可用 sillyspec register-stage-review --change <名> --stage ${stage} [--from <已有review.json>] 一步生成 run 目录 + review.json 骨架（docHash 自动算）+ 写 marker + 自检，省掉手动建目录/写 marker`)
   }
 
   if (result.warnings.length > 0) {

package/src/stages/brainstorm.js

@@ -329,6 +329,8 @@ design.md 第一行标题必须用中文：# 设计文档（Design）— <变更
    - 长期术语只在 archive/scan 时再提升到 \`{SPEC_ROOT}/docs/<project>/glossary.md\`
 4. 格式自检（只查章节齐全；语义一致性/可行性/YAGNI 不在本步查，交给下一步 Design Grill 独立审查）：
    - design.md 含全部必填章节（背景/设计目标/非目标/总体方案/文件变更清单/接口定义/风险登记）
+   - design.md 头部 YAML frontmatter 字段齐全（author/created_at/scale 等）——step8 完成契约硬要求，审查前就补齐避免后续 docHash 漂移
+   - design.md 含「自审」字面命中章节（自审 / Self-Review / Self-review）——step8 完成契约 brainstorm.design.self-review 硬要求，写在本步自审段即可
    - 如存在 decisions.md，design.md 是否引用所有当前版本 D-xxx@vN
    - 涉及 session/lease/agent_run/daemon/lifecycle 等关键词时，是否含「生命周期契约表」
 5. 缺章节 → 补齐后重检；章节齐全 → 进入下一步（Design Grill 做语义层交叉审查）
@@ -476,10 +478,10 @@ created_at: <now-datetime>
 
 ### proposal.md 格式要求
 \`\`\`markdown
----
-author: <git-user>
-created_at: <now-datetime>
----
+---
+author: <git-user>
+created_at: <now-datetime>
+---
 # 提案书（Proposal）
 
 ## 动机
@@ -503,10 +505,10 @@ created_at: <now-datetime>
 
 ### requirements.md 格式要求
 \`\`\`markdown
----
-author: <git-user>
-created_at: <now-datetime>
----
+---
+author: <git-user>
+created_at: <now-datetime>
+---
 # 需求规格（Requirements）
 
 ## 角色
@@ -535,18 +537,18 @@ Then 期望结果
 | D-001@v1 | FR-01 | ... |
 \`\`\`
 
-### tasks.md 格式要求（scale=large 时生成骨架，plan 阶段展开）
-\`\`\`markdown
----
-author: <git-user>
-created_at: <now-datetime>
----
-# 任务清单（Tasks）
-
-- [ ] task-01: <任务名>
-- [ ] task-02: <任务名>
-\`\`\`
-
+### tasks.md 格式要求（scale=large 时生成骨架，plan 阶段展开）
+\`\`\`markdown
+---
+author: <git-user>
+created_at: <now-datetime>
+---
+# 任务清单（Tasks）
+
+- [ ] task-01: <任务名>
+- [ ] task-02: <任务名>
+\`\`\`
+
 ### decisions.md 格式要求（仅在有 Grill/重大决策时生成）
 \`\`\`markdown
 # 决策记录（Decisions）