sillyspec 3.23.9 → 3.24.1

package/src/run.js

@@ -9,9 +9,28 @@ import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, read
 import { randomBytes, randomUUID } from 'crypto'
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
+import { fileURLToPath } from 'url'
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/**
+ * 解析 prompt 中的 {{include: <name>}} 占位符：读包内 templates/prompts/<name>.md 注入。
+ * 把 stage step prompt 里 self-contained 的大块（如 verify 探针）抽到外部模板，
+ * CLI 端组装时注入——agent 收到的仍是自包含 prompt 字符串，无需自己 Read。
+ * 单次替换（不递归）；模板缺失则保留占位符并 warn，便于发现配置错误。
+ */
+function resolvePromptIncludes(text) {
+  return text.replace(/\{\{include:\s*([\w.-]+)\s*\}\}/g, (match, name) => {
+    const tplPath = join(__dirname, '..', 'templates', 'prompts', `${name}.md`)
+    if (!existsSync(tplPath)) {
+      console.warn(`⚠️ prompt include 模板缺失: ${name} (期望: ${tplPath})`)
+      return match
+    }
+    return readFileSync(tplPath, 'utf8')
+  })
+}
 import { ProgressManager } from './progress.js'
 import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
-import { allocateQuicklogEntry, completeQuicklogEntry, findQuicklogEntry } from './quicklog.js'
+import { allocateQuicklogEntry, completeQuicklogEntry, findQuicklogEntry, validateQuickResult } from './quicklog.js'
 import { checkbox } from '@inquirer/prompts'
 
 /**
@@ -159,7 +178,7 @@ function resolveSpecDir(cwd, opts = {}) {
   return join(resolve(cwd), '.sillyspec')
 }
 import { stageRegistry, auxiliaryStages } from './stages/index.js'
-import { checkTransition, runValidators } from './stage-contract.js'
+import { checkTransition, runValidators, validateChangeExists } from './stage-contract.js'
 import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
 import { formatExecuteSummary } from './worktree-apply.js'
@@ -677,7 +696,8 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     console.log(`changeDir: ${changeDir}`)
   }
   console.log(`---\n`)
-  if (personas[stageName]) {
+  // persona 只在 stage 首步注入（step0）——角色设定一次即可，后续 step 重复注入纯属 token 浪费
+  if (personas[stageName] && stepIndex === 0) {
     console.log(personas[stageName])
     console.log('')
   }
@@ -690,7 +710,9 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     console.log(guardrails.trim())
     console.log('')
   }
-  let promptText = step.prompt
+  // 先解析 {{include: name}}（把外部模板片段拉进 prompt），再做下方占位符替换，
+  // 保证模板内容里的 {SPEC_ROOT}/<change-name> 等也能被替换
+  let promptText = resolvePromptIncludes(step.prompt)
   // 替换 prompt 中的占位符
   if (projectName && promptText.includes('<project>')) {
     promptText = promptText.replace(/<project>/g, projectName)
@@ -1567,6 +1589,18 @@ export async function runCommand(args, cwd, specDir = null) {
     process.exit(1)
   }
 
+  // --change 变更名存在性校验（治 cwd 漂移误匹配，缺陷 execute-in-place-windows-pitfalls 坑5）：
+  // 必须在 pm.read/initChange 之前——initChange 会为 --change 指定的新名字创建 changes/ 目录，
+  // 校验若在其后则目录已存在、永远通过。用原始 changeName（--change 参数），覆盖 plan/execute/
+  // verify/archive；quick-<8hex> sessionId 与 brainstorm 新建豁免（见 validateChangeExists）。
+  const changeMissing = validateChangeExists(specBase, stageName, changeName)
+  if (changeMissing) {
+    console.error(`❌ ${changeMissing.message}`)
+    console.error(`   可能 cwd 漂移——当前 cwd=${cwd}，命中的 spec=${specBase}。`)
+    console.error(`   若意图操作别的项目，请 cd 到对应项目根，或用 --spec-dir 指定正确的 spec 目录。`)
+    process.exit(1)
+  }
+
   let progress = await pm.read(cwd, changeName)
 
   if (!progress) {
@@ -3091,6 +3125,27 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         progress.lastQuickReview = review
       }
 
+      // 结果摘要结构校验（最后一步、isDone 且带了 --output 时）：--output 是 QUICKLOG「结果：」
+      // 归档的唯一来源，要求按 需求/根因/方案/结果 模板给全（见 stages/quick.js step3 prompt）。
+      // 确定性校验：只查必填字段是否齐全，不判内容质量。缺字段 → 本次不完成（回滚 step 状态 +
+      // exit 1），保留「进行中」条目，agent 补全 --output 后重跑 --done 即可，不丢进度。
+      // 仅 completeQuicklogEntry 会实际持久化时才校验；前两个 step 的 --done output 不入 QUICKLOG，不校验。
+      if (outputText) {
+        const resultCheck = validateQuickResult(outputText)
+        if (!resultCheck.ok) {
+          console.error(`\n❌ quick 结果摘要结构不完整：缺少字段 ${resultCheck.missing.join('、')}`)
+          console.error(`   --output 会写入 QUICKLOG「结果：」，请按模板补全再重跑 --done：`)
+          console.error(`     需求：用户/任务要什么`)
+          console.error(`     根因：为什么这样改（纯新增/样式则写「无，纯新增/纯样式」）`)
+          console.error(`     方案：怎么改的`)
+          console.error(`     结果：验证情况（测试数 / lint / typecheck / 部署状态）`)
+          steps[currentIdx].status = 'pending'
+          steps[currentIdx].completedAt = null
+          if (outputText) steps[currentIdx].output = null
+          process.exit(1)
+        }
+      }
+
       if (!qlId) {
         // 无 ql-ID（guard 缺失或 brownfield 无 quicklogId）：补分配后立即完成，不阻断。
         try {
@@ -3118,9 +3173,10 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         process.exit(1)
       }
       // 翻状态进行中→已完成 + 追加结果 + 勾选关联 tasks.md
+      // resultText 不再截断：结构化结果块（需求/根因/方案/结果）完整落盘，多行写成字段化块。
       try {
         await completeQuicklogEntry(specBase, gitUser, qlId, {
-          resultText: outputText ? outputText.slice(0, 500) : '',
+          resultText: outputText || '',
           linkedChanges,
         })
         console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)

package/src/stage-contract.js

@@ -33,6 +33,50 @@ function resolveChangeDir(cwd, changeName, specRoot = null) {
   return join(changesRoot, changeName)
 }
 
+/**
+ * --change 变更名存在性校验（治 cwd 漂移误匹配，缺陷 execute-in-place-windows-pitfalls 坑5）。
+ *
+ * 多项目 monorepo 下，cwd 在子项目目录会让 resolveSpecDir 命中子项目 spec，
+ * 此时 --change 传根项目变更名，旧逻辑（resolveChangeDir 纯拼路径）不报错而静默
+ * fallback 误启动子项目流程。本校验对「操作已有变更」的阶段强制 changes/<changeName>
+ * 存在，不存在则 fail-fast，把 cwd 漂移暴露给用户。
+ *
+ * 豁免：
+ *   - 非 plan/execute/verify/archive 阶段（scan/brainstorm/quick/explore 不校验：
+ *     brainstorm 可新建变更、quick 用 sessionId、scan/explore 无 change 语义）
+ *   - quick-<8hex> sessionId（quick 会话 changeName 是 sessionId，不在 changes/）
+ *
+ * @param {string} specBase - 规范根目录（.sillyspec 或平台 specRoot）
+ * @param {string} stageName - 阶段名
+ * @param {string} changeName - 变更名（--change 或 auto）
+ * @returns {{ changeName: string, specBase: string, message: string } | null} null=通过，对象=失败
+ */
+export function validateChangeExists(specBase, stageName, changeName) {
+  const STAGES_REQUIRE_EXISTING_CHANGE = new Set(['plan', 'execute', 'verify', 'archive'])
+  if (!changeName || !STAGES_REQUIRE_EXISTING_CHANGE.has(stageName)) return null
+  if (/^quick-[0-9a-f]{8}$/.test(changeName)) return null
+  if (existsSync(join(specBase, 'changes', changeName))) return null
+
+  // archive 特例：step4 --confirm 已把变更从 changes/<name>/ 移到 changes/archive/<date>-<name>/。
+  // step5（更新路线图/提交）--change <name> 不应因 changes/<name>/ 已移走而被前置校验误拦。
+  // 精确匹配归档目录名（YYYY-MM-DD-<changeName>），避免后缀子串误匹配（auth ≠ deep-auth）。
+  if (stageName === 'archive') {
+    const archiveRoot = join(specBase, 'changes', 'archive')
+    if (existsSync(archiveRoot)) {
+      const archived = readdirSync(archiveRoot).find(d => {
+        const m = d.match(/^\d{4}-\d{2}-\d{2}-(.+)$/)
+        return m && m[1] === changeName
+      })
+      if (archived) return null
+    }
+  }
+  return {
+    changeName,
+    specBase,
+    message: `变更 "${changeName}" 在当前 spec 下不存在：${join(specBase, 'changes', changeName)}`,
+  }
+}
+
 function collectIdsFromLine(line, re, ids) {
   for (const match of line.matchAll(re)) {
     ids.add(match[0].toUpperCase())