@ifrankwang/openspec-agents 0.118.0

package/src/core/state.ts

@@ -0,0 +1,357 @@
+import path from "path"
+import { mkdirSync, rmSync, statSync, readFileSync, writeFileSync, existsSync, readdirSync, copyFileSync, cpSync } from "node:fs"
+import { readFile, writeFile } from "node:fs/promises"
+import type { OrchestrateState, TaskGroupState, Phase, IssueItem } from "./types.ts"
+import type { WorkItem, WorkItemPhase, Severity } from "./workflow/types.ts"
+import { createInitialWorkItem } from "./workflow/engine.ts"
+import { EXEMPT_REQUEST_KEY } from "./workflow/submit.ts"
+import { STATE_DIR_NAME, STATE_SUBDIR_NAME, LEGACY_STATE_DIR_NAME, LEGACY_STATE_SUBDIR_NAME } from "./constants.ts"
+import { DIMENSION_AGENT_MAP } from "./constants.ts"
+import { discoverRepoRoot } from "./git.ts"
+import { generateIsolationNamespace } from "./namespace.ts"
+
+const LOCK_POLL_INTERVAL_MS = 50
+const LOCK_META_FILENAME = "meta.json"
+const LOCK_STALE_THRESHOLD_MS = 10000
+
+function isWorktreePath(worktree: string): boolean {
+  const gitPath = path.join(worktree, ".git")
+  try {
+    return statSync(gitPath).isFile()
+  } catch {
+    return false
+  }
+}
+
+export function getStateDir(worktree: string): string {
+  return path.join(worktree, STATE_DIR_NAME, STATE_SUBDIR_NAME)
+}
+
+/** 旧布局 .opencode/.orchestrate_state（读取兼容与迁移源）。 */
+export function getLegacyStateDir(worktree: string): string {
+  return path.join(worktree, LEGACY_STATE_DIR_NAME, LEGACY_STATE_SUBDIR_NAME)
+}
+
+/** Worktree 内用于存储 changeId/taskGroupId 指针的上下文文件（相对于 worktree 根） */
+export const WORKTREE_CONTEXT_FILE = "openspec/states/context.json"
+/** 旧布局 worktree 上下文指针（读取兼容）。 */
+export const WORKTREE_CONTEXT_FILE_LEGACY = ".opencode/.orchestrate_state/context.json"
+
+/**
+ * 幂等迁移：旧 .opencode/.orchestrate_state/ 数据（主状态/exemptions/锁/context.json 指针）→
+ * openspec/states/。新目录已存在（含空目录）即视为已迁移，重复调用无副作用；
+ * 迁移只拷贝不删除旧文件，旧布局在迁移期间仍可读（双读兼容）。
+ */
+export function migrateLegacyStateDir(root: string): void {
+  const legacyDir = getLegacyStateDir(root)
+  if (!existsSync(legacyDir)) return
+  const newDir = getStateDir(root)
+  if (existsSync(newDir)) return
+  mkdirSync(newDir, { recursive: true })
+  for (const entry of readdirSync(legacyDir, { withFileTypes: true })) {
+    const src = path.join(legacyDir, entry.name)
+    const dst = path.join(newDir, entry.name)
+    try {
+      if (entry.isDirectory()) {
+        cpSync(src, dst, { recursive: true })
+      } else {
+        copyFileSync(src, dst)
+      }
+    } catch {
+      // 单文件迁移失败不阻塞整体迁移（其余条目继续）
+    }
+  }
+}
+
+/**
+ * 从 worktree 中读取上下文指针（changeId + taskGroupId）。
+ * 新布局 openspec/states/context.json 优先，旧 .opencode/.orchestrate_state/context.json 双读兼容。
+ * 文件不存在时返回 null。
+ */
+export async function readContextFromWorktree(worktreePath: string): Promise<{ changeId: string; taskGroupId: string } | null> {
+  const fp = path.join(worktreePath, WORKTREE_CONTEXT_FILE)
+  const fpLegacy = path.join(worktreePath, WORKTREE_CONTEXT_FILE_LEGACY)
+  for (const p of [fp, fpLegacy]) {
+    try {
+      const raw = await readFile(p, "utf-8")
+      return JSON.parse(raw) as { changeId: string; taskGroupId: string }
+    } catch {
+      // 该布局无指针，尝试下一个
+    }
+  }
+  return null
+}
+
+/**
+ * 向 worktree 写入上下文指针（changeId + taskGroupId）。
+ * 自动创建所需目录；首次写入新布局前把旧布局指针幂等迁移到新位置。
+ */
+export async function writeContextToWorktree(worktreePath: string, changeId: string, taskGroupId: string): Promise<void> {
+  const fp = path.join(worktreePath, WORKTREE_CONTEXT_FILE)
+  const fpLegacy = path.join(worktreePath, WORKTREE_CONTEXT_FILE_LEGACY)
+  if (!existsSync(fp) && existsSync(fpLegacy)) {
+    migrateLegacyStateDir(worktreePath)
+  }
+  const dir = path.dirname(fp)
+  mkdirSync(dir, { recursive: true })
+  await writeFile(fp, JSON.stringify({ changeId, taskGroupId }, null, 2))
+}
+
+export function getStatePath(worktree: string, changeId: string): string {
+  return path.join(getStateDir(worktree), `${changeId}.json`)
+}
+
+export async function readStateByWorktree(worktree: string, changeId?: string): Promise<OrchestrateState | null> {
+  if (isWorktreePath(worktree)) {
+    const ctx = await readContextFromWorktree(worktree)
+    if (!ctx) return null
+    const repoRoot = await discoverRepoRoot(worktree)
+    return readStateByChangeId(repoRoot, ctx.changeId)
+  }
+  if (changeId) {
+    return readStateByChangeId(worktree, changeId)
+  }
+  // 非 worktree 且未传 changeId：无可用编排上下文，与「无可用编排会话」语义一致，返回 null 兜底
+  return null
+}
+
+// ─── 旧格式读兼容迁移：taskGroups → workItems（单轨化后 taskGroups 不再持久化）───
+// 以下映射仅服务于旧格式状态文件升级为 workItems 的迁移入口，非双轨同步逻辑。
+// 升级后 taskGroups 字段不再写回，workItems 为唯一事实源。
+
+/** 旧 tg.status → WorkItem phase（迁移用） */
+function taskGroupStatusToPhase(status: Phase): WorkItemPhase {
+  switch (status) {
+    case "task_analysis": return "todo"
+    case "dev_impl": return "in_progress"
+    case "review": return "review"
+    case "completed": return "done"
+  }
+}
+
+/** 旧 tg.status → WorkItem currentStep（迁移用，各阶段入口 step） */
+function taskGroupStatusToStep(status: Phase): string | null {
+  switch (status) {
+    case "task_analysis": return "analyze"
+    case "dev_impl": return "implement"
+    case "review": return "verify_tool"
+    case "completed": return null
+  }
+}
+
+/** 旧 issue status → child phase（迁移用：verified→done、exempted→cancelled、submitted→review，其余→todo） */
+function issueStatusToChildPhase(status: IssueItem["status"]): WorkItemPhase {
+  switch (status) {
+    case "verified": return "done"
+    case "exempted": return "cancelled"
+    case "submitted": return "review"
+    default: return "todo"
+  }
+}
+
+/** 由旧 issue 归因（sourcePhase+dimension）反推真实报源审查 agent（迁移 metadata.source 用，兼 exempt_request.requestedBy 兜底）。 */
+function issueReporterAgent(issue: IssueItem): string {
+  if (issue.sourcePhase === "quality") return DIMENSION_AGENT_MAP[issue.dimension] ?? "openspec-reviewer-tool"
+  if (issue.sourcePhase === "task") return "openspec-reviewer-task"
+  return "openspec-reviewer-tool"
+}
+
+/** 由 issue 构造 issue 类型 WorkItem child。 */
+export function buildIssueWorkItem(issue: IssueItem): WorkItem {
+  const reporterAgent = issueReporterAgent(issue)
+  const child = createInitialWorkItem({
+    id: `issue:${issue.id}`,
+    source: reporterAgent,
+    externalId: issue.id,
+    type: "issue",
+    title: issue.description,
+    description: issue.description,
+    severity: issue.severity as Severity,
+  })
+  child.phase = issueStatusToChildPhase(issue.status)
+  // 迁移时写入真实报源 agent 到 metadata.source：新流报源层（tool/task/quality）由 source 反推，
+  // 无 source 的迁移 issue 无法归层/裁定（原 workflow/submit.ts 报错路径）。source_phase 保留透传作
+  // 历史兼容兜底（消费端仅认 source 反推，见 reviewLayerFromMetadata）。
+  child.metadata["source"] = reporterAgent
+  child.metadata["source_phase"] = issue.sourcePhase
+  child.metadata["dimension"] = issue.dimension
+  child.metadata["file"] = issue.file
+  child.metadata["line"] = issue.line
+  if (issue.status === "exemption_requested") {
+    // 迁移时保留豁免申请语义：exempt_request 标记使 sync 回写保持 exemption_requested，
+    // 避免 child 落 todo 后被覆写回 open 丢失豁免申请。
+    child.metadata[EXEMPT_REQUEST_KEY] = {
+      requestedBy: reporterAgent,
+      reason: issue.exemptReason,
+    }
+  }
+  return child
+}
+
+/** 由 taskGroup 构造 task 类型 WorkItem（含其 issue children 与 task 清单）。 */
+export function buildTaskWorkItemFromTaskGroup(tg: TaskGroupState): WorkItem {
+  const item = createInitialWorkItem({
+    id: `task:${tg.id}`,
+    source: "openspec",
+    externalId: tg.id,
+    type: "task",
+    title: tg.name,
+    description: tg.name,
+    labels: ["openspec-change"],
+  })
+  item.phase = taskGroupStatusToPhase(tg.status)
+  item.currentStep = taskGroupStatusToStep(tg.status)
+  item.metadata = { source: "openspec", tasks: JSON.parse(JSON.stringify(tg.tasks ?? [])) }
+  // 迁移透传 worktree 引用（worktree_path/branch_name/base_ref）：旧格式升级后 worktree 就绪判定与提交门禁须保持一致
+  if (tg.worktreePath) item.metadata["worktree_path"] = tg.worktreePath
+  if (tg.branchName) item.metadata["branch_name"] = tg.branchName
+  if (tg.baseRef) item.metadata["base_ref"] = tg.baseRef
+  item.children = tg.issues.map(buildIssueWorkItem)
+  return item
+}
+
+/**
+ * 从旧格式 taskGroups 批量构造 workItems（旧状态文件自动升级入口）。
+ * 单轨化后仅由 readStateByChangeId 在旧格式（有 taskGroups 无 workItems）时调用，
+ * 升级结果落盘后 taskGroups 字段不再写回。
+ */
+export function upgradeWorkItemsFromTaskGroups(groups: TaskGroupState[]): WorkItem[] {
+  return groups.map(buildTaskWorkItemFromTaskGroup)
+}
+
+interface LegacyState extends OrchestrateState {
+  taskGroups?: TaskGroupState[]
+}
+
+export async function readStateByChangeId(worktree: string, changeId: string): Promise<OrchestrateState | null> {
+  const fp = getStatePath(worktree, changeId)
+  const fpLegacy = path.join(getLegacyStateDir(worktree), `${changeId}.json`)
+  // 双读兼容：新布局 openspec/states/ 优先，旧 .opencode/.orchestrate_state/ 兜底（迁移前仍可读）
+  const readPath = existsSync(fp) ? fp : existsSync(fpLegacy) ? fpLegacy : null
+  let raw: unknown
+  try {
+    raw = readPath ? JSON.parse(await readFile(readPath, "utf-8")) : null
+  } catch {
+    raw = null
+  }
+  if (raw === null) return null
+  const legacy = raw as LegacyState
+  const sampleGroup = legacy.taskGroups?.[0]
+  if (sampleGroup && !("tasks" in sampleGroup)) {
+    throw new Error(
+      `状态文件 "${legacy.changeId}" 是旧版本格式，不兼容当前版本。请重新初始化编排会话（opx_orch_init）。`
+    )
+  }
+  if (!legacy.isolationNamespace) {
+    legacy.isolationNamespace = generateIsolationNamespace(legacy.changeId)
+  }
+  // 旧格式归一化：blocker 状态兼容 + task_analysis 自动推进（仅在迁移前生效）
+  for (const group of legacy.taskGroups || []) {
+    group.blockers ??= []
+    for (const blocker of group.blockers) {
+      if ((blocker.status as string) === "reported" || (blocker.status as string) === "ready_for_architect") {
+        blocker.status = "awaiting_user"
+      }
+    }
+    if (group.status === "task_analysis" && group.phases?.architect_review?.completed && !group.blockers.some((blocker) => blocker.status !== "resolved")) {
+      group.status = "dev_impl"
+    }
+  }
+
+  const needsUpgrade = !Array.isArray(legacy.workItems) || legacy.workItems.length === 0
+  // 单轨组装：仅保留 workItems 为唯一事实源，taskGroups 字段丢弃不再写回
+  const state: OrchestrateState = {
+    changeId: legacy.changeId,
+    isolationNamespace: legacy.isolationNamespace,
+    taskGroupId: legacy.taskGroupId,
+    baseBranch: legacy.baseBranch,
+    workItems: needsUpgrade
+      ? upgradeWorkItemsFromTaskGroups(legacy.taskGroups ?? [])
+      : (legacy.workItems as WorkItem[]),
+    createdAt: legacy.createdAt,
+    updatedAt: legacy.updatedAt,
+    unattended: legacy.unattended,
+  }
+  if (needsUpgrade) {
+    // 迁移产物一次性落盘固定单轨形态，避免每次读取都重建（首次写新目录前幂等迁移旧数据）
+    migrateLegacyStateDir(worktree)
+    mkdirSync(getStateDir(worktree), { recursive: true })
+    await writeFile(fp, JSON.stringify(state, null, 2))
+  }
+  return state
+}
+
+export async function resolveStateRoot(worktree: string): Promise<string> {
+  return isWorktreePath(worktree) ? await discoverRepoRoot(worktree) : worktree
+}
+
+export async function writeState(worktree: string, state: OrchestrateState): Promise<void> {
+  const target = await resolveStateRoot(worktree)
+  // 首次新目录写入前幂等迁移旧 .opencode 数据（主状态/exemptions/锁），重复迁移无副作用
+  migrateLegacyStateDir(target)
+  mkdirSync(getStateDir(target), { recursive: true })
+  state.updatedAt = new Date().toISOString()
+  await writeFile(getStatePath(target, state.changeId), JSON.stringify(state, null, 2))
+}
+
+export async function getLockPath(worktree: string, changeId: string): Promise<string> {
+  const root = await resolveStateRoot(worktree)
+  return path.join(getStateDir(root), `${changeId}.review.lock`)
+}
+
+function readLockMeta(lockPath: string): { pid: number; acquiredAt: number } | null {
+  try {
+    const meta = JSON.parse(readFileSync(path.join(lockPath, LOCK_META_FILENAME), "utf-8"))
+    if (meta && typeof meta.acquiredAt === "number") return meta
+    return null
+  } catch {
+    return null
+  }
+}
+
+export function acquireLock(lockPath: string, timeoutMs = 10000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const deadline = Date.now() + timeoutMs
+    const tryAcquire = () => {
+      try {
+        mkdirSync(lockPath)
+        try {
+          writeFileSync(
+            path.join(lockPath, LOCK_META_FILENAME),
+            JSON.stringify({ pid: process.pid, acquiredAt: Date.now() })
+          )
+        } catch (metaErr) {
+          rmSync(lockPath, { recursive: true, force: true })
+          reject(metaErr as Error)
+          return
+        }
+        resolve()
+      } catch (err: unknown) {
+        if ((err as { code?: string }).code !== "EEXIST") {
+          reject(err as Error)
+          return
+        }
+        const meta = readLockMeta(lockPath)
+        if (meta && Date.now() - meta.acquiredAt >= LOCK_STALE_THRESHOLD_MS) {
+          rmSync(lockPath, { recursive: true, force: true })
+          setTimeout(tryAcquire, LOCK_POLL_INTERVAL_MS)
+          return
+        }
+        if (Date.now() >= deadline) {
+          reject(new Error(`获取锁超时：${lockPath}（${timeoutMs}ms 内未获得锁）`))
+          return
+        }
+        setTimeout(tryAcquire, LOCK_POLL_INTERVAL_MS)
+      }
+    }
+    tryAcquire()
+  })
+}
+
+export function releaseLock(lockPath: string): void {
+  try {
+    rmSync(lockPath, { recursive: true, force: true })
+  } catch {
+    // 锁目录不存在时静默忽略
+  }
+}

package/src/core/task-children.ts

@@ -0,0 +1,59 @@
+import type { TaskItem, TaskStatus } from "./types.ts"
+import type { WorkItem, WorkItemPhase } from "./workflow/types.ts"
+
+/**
+ * 子任务（task child）共享投影助手。
+ *
+ * 子任务建模为 type==="task" 的 WorkItem 挂入主任务 item.children（metadata.tasks 已废弃），
+ * 走统一 phase 状态机：todo（open/rejected）→ review（submitted）→ done/cancelled（终态）。
+ * task child 的 id 为短数字（如 "1"、"2"），externalId 存 taskNumber（如 "1.1"）。
+ */
+
+/** 过滤 item.children 中 type==="task" 的子任务。 */
+export function taskChildrenOf(item: WorkItem): WorkItem[] {
+  return (item.children ?? []).filter((c) => c.type === "task")
+}
+
+/** 过滤 item.children 中 type==="issue" 的 issue child（task child 不参与 issue 渲染/归因）。 */
+export function issueChildrenOf(item: WorkItem): WorkItem[] {
+  return (item.children ?? []).filter((c) => c.type === "issue")
+}
+
+/** 按 id（数字字符串或 taskNumber）查 task child，未命中返回 null。 */
+export function taskChildById(item: WorkItem, id: string): WorkItem | null {
+  return (
+    item.children.find((c) => c.type === "task" && (c.id === id || c.externalId === id)) ?? null
+  )
+}
+
+/** 将 taskNumber（如 "1.1"）映射为数字 id（task child 的 externalId 存 taskNumber，id 存数字），未命中按原样返回。 */
+export function normalizeTaskChildIds(rawIds: string[], item: WorkItem): string[] {
+  const byNumber = new Map<string, string>()
+  for (const c of taskChildrenOf(item)) {
+    if (c.externalId !== undefined) byNumber.set(c.externalId, c.id)
+  }
+  return rawIds.map((id) => byNumber.get(id) ?? id)
+}
+
+/** task child phase → TaskStatus 反查（TaskItem 兼容投影）。 */
+function phaseToTaskStatus(phase: WorkItemPhase, hasRejectReason: boolean): TaskStatus {
+  switch (phase) {
+    case "review": return "submitted"
+    case "done":
+    case "cancelled": return "verified"
+    case "todo": return hasRejectReason ? "rejected" : "open"
+    default: return "open"
+  }
+}
+
+/** 从 task child 投影 TaskItem 兼容结构（status.ts 视图渲染与旧工具读侧使用）。 */
+export function taskListOf(item: WorkItem): TaskItem[] {
+  return taskChildrenOf(item).map((c) => ({
+    id: c.id,
+    specTrace: typeof c.metadata["specTrace"] === "string" ? c.metadata["specTrace"] : "",
+    title: c.title,
+    status: phaseToTaskStatus(c.phase, c.metadata["reject_reason"] !== undefined),
+    taskNumber: typeof c.externalId === "string" ? c.externalId : "",
+    rejectReason: typeof c.metadata["reject_reason"] === "string" ? c.metadata["reject_reason"] : null,
+  }))
+}

package/src/core/tasks-md.ts

@@ -0,0 +1,89 @@
+import path from "path"
+import { readFile } from "node:fs/promises"
+
+export interface ParsedTask {
+  title: string
+  specTrace: string
+  taskNumber: string
+}
+
+export function parseSpecTrace(line: string): string {
+  const m = line.match(/\[spec:([^\]]+)\]/)
+  return m ? m[1].trim() : ""
+}
+
+export async function parseTasksMdForGroup(
+  worktree: string,
+  changeId: string,
+  taskGroupId: string
+): Promise<ParsedTask[]> {
+  const tasksPath = path.join(worktree, "openspec", "changes", changeId, "tasks.md")
+  const tasks: ParsedTask[] = []
+  try {
+    const content = await readFile(tasksPath, "utf-8")
+    const lines = content.split("\n")
+    let currentGroup: string | null = null
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const groupMatch = line.match(/^##\s+(\d+)\./)
+      if (groupMatch) {
+        if (currentGroup === taskGroupId) break
+        currentGroup = groupMatch[1]
+        continue
+      }
+      if (currentGroup !== taskGroupId) continue
+      const taskMatch = line.match(/^-\s+\[[\sx]\]\s+(.+)/)
+      if (taskMatch) {
+        const body = taskMatch[1]
+        const taskNumberMatch = body.match(/^(\d+(?:\.\d+)+)\s+/)
+        const taskNumber = taskNumberMatch ? taskNumberMatch[1] : ""
+        const cleaned = (taskNumberMatch ? body.slice(taskNumberMatch[0].length) : body)
+          .replace(/\s*\[spec:[^\]]+\]\s*$/, "")
+          .trim()
+        const specTrace = parseSpecTrace(body)
+        tasks.push({ title: cleaned, specTrace, taskNumber })
+      }
+    }
+  } catch {
+  }
+  return tasks
+}
+
+export function extractRelevantSpecsFromTasks(tasks: ParsedTask[]): string[] {
+  const set = new Set<string>()
+  for (const t of tasks) {
+    if (!t.specTrace) continue
+    const parts = t.specTrace.split("#")[0]
+    if (parts) set.add(parts)
+  }
+  return Array.from(set)
+}
+
+export async function parseAllTaskGroupsFromMd(
+  worktree: string,
+  changeId: string
+): Promise<{ id: string; name: string; taskCount: number }[]> {
+  const tasksPath = path.join(worktree, "openspec", "changes", changeId, "tasks.md")
+  const groups: { id: string; name: string; taskCount: number }[] = []
+  try {
+    const content = await readFile(tasksPath, "utf-8")
+    const lines = content.split("\n")
+    let currentGroup: { id: string; name: string } | null = null
+    let currentTaskCount = 0
+    for (const line of lines) {
+      const groupMatch = line.match(/^##\s+(\d+)\./)
+      if (groupMatch) {
+        if (currentGroup) groups.push({ ...currentGroup, taskCount: currentTaskCount })
+        currentGroup = { id: groupMatch[1], name: line.replace(/^##\s+\d+\.\s*/, "").trim() }
+        currentTaskCount = 0
+        continue
+      }
+      if (currentGroup) {
+        if (/^-\s+\[[\sx]\]\s+/.test(line)) currentTaskCount++
+      }
+    }
+    if (currentGroup) groups.push({ ...currentGroup, taskCount: currentTaskCount })
+  } catch {
+  }
+  return groups
+}

package/src/core/tools/gate.ts

@@ -0,0 +1,165 @@
+/**
+ * 质量门必做清单（must_do）覆盖度门禁与降级理由（skip_reason）结构化解析。
+ *
+ * 语义：skill 在 frontmatter 声明机器可读的 must_do 必做清单后，review 提交（verify_tool）的
+ * validation_steps 必须逐项覆盖（completed=true，或 completed=false 且 skip_reason 为合法结构化
+ * JSON）。未声明 must_do 的 skill 与解析不到质量门 skill 的 step 优雅跳过（不误伤非质量门 step）。
+ * giveup 决策复用同一套未覆盖项推导，要求对未覆盖必做项补充结构化降级理由（checkpoint_skip_reasons），
+ * 杜绝「放弃审查 → 直接推进收尾」的无痕绕过通道。
+ *
+ * skip_reason 结构化格式（JSON 字符串）：
+ *   {"item":"<对应必做项>","category":"<降级类别>","adjudication":"user_response|unattended_auto|env_unavailable","note":"<说明>"}
+ * adjudication 裁定方式枚举：user_response=用户答复、unattended_auto=无人值守自动降级、
+ * env_unavailable=环境不可用（note 须记录尝试）。
+ */
+import {
+  scanSkillTags,
+  resolveSkillsForCapabilities,
+  getSkillMustDo,
+  type SkillTagIndex,
+} from "../../skills/resolve.ts"
+
+/** 裁定方式枚举：用户答复 / 无人值守自动降级 / 环境不可用（须附尝试记录）。 */
+export const SKIP_REASON_ADJUDICATIONS = ["user_response", "unattended_auto", "env_unavailable"] as const
+export type SkipAdjudication = (typeof SKIP_REASON_ADJUDICATIONS)[number]
+
+/**
+ * 结构化降级声明的标准格式（skip_reason / checkpoint_skip_reasons 共用）。
+ * 全链路（schema 描述 / 视图指引 / 错误提示）以本常量保证术语与格式一致。
+ */
+export const SKIP_REASON_FORMAT =
+  '{"item":"<对应必做项>","category":"<降级类别>","adjudication":"user_response|unattended_auto|env_unavailable","note":"<说明>"}'
+
+/** 结构化降级声明：item 对应必做项，category 为降级类别，adjudication 为裁定方式。 */
+export interface SkipReasonData {
+  item: string
+  category: string
+  adjudication: string
+  note?: string
+}
+
+/**
+ * 测试注入：覆盖门禁使用的 skill 索引。
+ * 存量测试基建（tests/helpers.ts setupWorkspace）默认注入空索引以豁免门禁（解析不到质量门 skill），
+ * 新增门禁用例显式注入构造索引或真实索引（scanSkillTags()）验证。null=无注入，走真实文件扫描。
+ */
+let overrideIndex: SkillTagIndex | null = null
+export function __setMustDoIndex(index: SkillTagIndex | null): void {
+  overrideIndex = index
+}
+
+/** 空 skill 索引：任何 capability 都解析不到 skill（门禁豁免用）。 */
+export const EMPTY_MUST_DO_INDEX: SkillTagIndex = {
+  tagMap: new Map(),
+  skillTags: new Map(),
+  skillMustDo: new Map(),
+}
+
+function currentIndex(): SkillTagIndex {
+  return overrideIndex ?? scanSkillTags()
+}
+
+/** 判断对象是否为合法结构化降级声明（item/category/adjudication 三要素齐全）。 */
+export function isValidSkipData(data: unknown): data is SkipReasonData {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) return false
+  const d = data as Record<string, unknown>
+  if (typeof d.item !== "string" || d.item.trim().length === 0) return false
+  if (typeof d.category !== "string" || d.category.trim().length === 0) return false
+  if (
+    typeof d.adjudication !== "string" ||
+    !(SKIP_REASON_ADJUDICATIONS as readonly string[]).includes(d.adjudication)
+  ) return false
+  return true
+}
+
+/** 解析结构化 skip_reason 文本（JSON 字符串）；格式不合法返回错误说明。 */
+export function parseSkipReason(
+  reason: string,
+): { ok: true; data: SkipReasonData } | { ok: false; error: string } {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(reason)
+  } catch {
+    return {
+      ok: false,
+      error:
+        `skip_reason 必须为结构化 JSON 字符串：${SKIP_REASON_FORMAT}。当前值无法解析为 JSON：${reason}`,
+    }
+  }
+  if (!isValidSkipData(parsed)) {
+    return {
+      ok: false,
+      error:
+        `skip_reason 结构化字段缺失或不合法：必须包含非空 item（对应必做项）、category（降级类别）、` +
+        `adjudication（裁定方式，取值 ${SKIP_REASON_ADJUDICATIONS.join(" / ")}）。当前值：${reason}`,
+    }
+  }
+  return { ok: true, data: parsed }
+}
+
+/** validation_steps 的 step 名称归一化：按冒号/括号/空白切出首段，与 must_do 枚举比对。 */
+function stepToken(name: string): string {
+  return name.trim().split(/[:：（(]/)[0].trim()
+}
+
+/** 按 capability_tags 解析出所有命中 skill 声明 must_do 的合并集合（去重、保持声明顺序）。 */
+export function resolveMustDoForCaps(caps: string[] | undefined, index?: SkillTagIndex): string[] {
+  const idx = index ?? currentIndex()
+  const { skillNames } = resolveSkillsForCapabilities(caps, idx)
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const name of skillNames) {
+    for (const item of getSkillMustDo(name, idx) ?? []) {
+      if (seen.has(item)) continue
+      seen.add(item)
+      out.push(item)
+    }
+  }
+  return out
+}
+
+/** 返回 validation_steps 未覆盖的必做项（step 名称首段命中即视为覆盖；无必做清单返回空数组）。 */
+export function uncoveredMustDo(
+  caps: string[] | undefined,
+  validationSteps: Array<{ step: string; completed: boolean; skip_reason?: string }> | undefined,
+  index?: SkillTagIndex,
+): string[] {
+  const must = resolveMustDoForCaps(caps, index)
+  if (must.length === 0) return []
+  const steps = validationSteps ?? []
+  // 全量豁免声明：无代码/配置变更直提、或经审查确认仅注释/文档性变更免全量时，
+  // review 以一条 step 名首段为该 token 的条目声明整体豁免必做清单（completed=false +
+  // 合法结构化 skip_reason，说明判定依据）；其余场景仍逐项申报。
+  if (steps.some((s) => stepToken(s.step) === NO_CHANGE_TOKEN)) return []
+  const covered = new Set<string>()
+  for (const s of steps) {
+    const token = stepToken(s.step)
+    if (must.includes(token)) covered.add(token)
+  }
+  return must.filter((m) => !covered.has(m))
+}
+
+/**
+ * 全量豁免声明 token：step 名首段为该 token 的 validation_steps 条目声明本轮整体豁免必做清单。
+ * 与 task.yaml verify_tool 无变更直提 / 注释性变更免全量分支对应（避免免全量直提被门禁误伤）。
+ */
+export const NO_CHANGE_TOKEN = "no_change"
+
+/**
+ * 校验 validation_steps 中每条未完成项必须携带合法结构化 skip_reason（升级既有「非空即可」校验）。
+ * 不合法即抛错（中文，指明步骤与原因）。
+ */
+export function assertStructuredSkipReasons(
+  validationSteps: Array<{ step: string; completed: boolean; skip_reason?: string }>,
+): void {
+  for (const s of validationSteps) {
+    if (s.completed) continue
+    if (!s.skip_reason) {
+      throw new Error(`验证步骤 "${s.step}" 标记为未完成但未提供跳过原因（skip_reason）。`)
+    }
+    const parsed = parseSkipReason(s.skip_reason)
+    if (!parsed.ok) {
+      throw new Error(`验证步骤 "${s.step}" 的 skip_reason 格式不合法：${parsed.error}`)
+    }
+  }
+}