deuk-agent-flow 5.0.2 → 5.0.4

package/scripts/cli-ticket-commands.ts

@@ -423,6 +423,56 @@ export function buildTicketCreateGuide(opts: CliOpts = {}) {
   });
 }
 
+// 티켓의 tags/summary에서 작업 도메인을 뽑아 역할 프롬프트에 주입할 한 줄 지시로 변환.
+// 매칭 규칙은 작게 시작해 확장한다(설계 §4.2). 매칭 없으면 빈 문자열(역할 기본 문안만).
+const DOMAIN_FOCUS_RULES: Array<{ keys: string[]; focus: string }> = [
+  { keys: ["codegen", "idl", "generate", "생성물"], focus: "[DOMAIN_FOCUS: codegen] 코드 생성물 관련. 생성물(generated/·idl)을 직접 수정하지 말고 소스→재생성 경로로만. 빌드타임 타입 확정을 런타임 registry/convention 우회로 대체 금지." },
+  { keys: ["refactor", "리팩터", "리팩토링"], focus: "[DOMAIN_FOCUS: refactor] 리팩터. 동작 보존이 최우선 — 변경 전후 동치성을 검증으로 보이고, 스코프를 최소·국소로 유지." },
+  { keys: ["ui", "webview", "widget", "css", "레이아웃", "디자인"], focus: "[DOMAIN_FOCUS: ui/design] UI/디자인 산출물. 일관성·정보위계·재사용·접근성을 1급 기준으로. \"동작하니 됐다\" 금지." },
+  { keys: ["bug", "fix", "버그", "수정"], focus: "[DOMAIN_FOCUS: bugfix] 버그 수정. 근본 원인을 먼저 특정하고, 재현 → 수정 → 회귀 방지 순서. 증상만 가리는 땜질 금지." },
+];
+
+function deriveDomainFocus(entry): string {
+  if (!entry) return "";
+  const tags = Array.isArray(entry.tags) ? entry.tags.map(t => String(t).toLowerCase()) : [];
+  const hay = `${tags.join(" ")} ${String(entry.summary || "")} ${String(entry.title || "")}`.toLowerCase();
+  for (const rule of DOMAIN_FOCUS_RULES) {
+    if (rule.keys.some(k => hay.includes(k))) return rule.focus;
+  }
+  return "";
+}
+
+// 워크스페이스별 기술 스택/관습 프로필 SSOT: <workspace>/.deuk-agent/workspace-profile.md.
+// 있으면 역할 프롬프트에 주입, 없으면 빈 문자열(역할 기본 문안만).
+function readWorkspaceProfile(cwd, workspace, platform = null): string {
+  // 워크스페이스 프로필 SSOT = PROJECT_RULE.md (홈 스토어, reconcile이 보존하는 알려진 파일).
+  // 별도 파일을 만들지 않는다 — 설계상 PROJECT_RULE.md가 워크스페이스 규칙+내부기준문서
+  // 포인터를 겸한다.
+  //
+  // 중복 회피: non-claude 플랫폼은 surface가 이미 `## Project Rules`로 PROJECT_RULE.md
+  // 전문을 보여주므로(readProjectRuleSurface) 여기선 프로필을 다시 싣지 않는다. claude는
+  // `## Project Rules`를 스킵(CLAUDE.md 중복 방지)하므로 ROLE_CONTEXT가 프로필을 담당한다.
+  const detectedPlatform = platform || detectCurrentPlatform();
+  if (detectedPlatform !== "claude") return "";
+  if (!cwd) return "";
+  try {
+    const p = makePath(resolveHomeTicketDirForWorkspace(cwd), "PROJECT_RULE.md");
+    if (existsSync(p)) {
+      const raw = stripLeadingFrontMatter(readFileSync(p, "utf8")).trim();
+      if (raw) return `[WORKSPACE_PROFILE: ${workspace || "local"}]\n${raw}`;
+    }
+  } catch { /* ignore */ }
+  return "";
+}
+
+// 역할 동적 컨텍스트 블록. 도메인/프로필 중 있는 것만 모아 한 섹션으로 낸다.
+// 둘 다 없으면 빈 문자열(템플릿에서 빈 줄로 흡수).
+function buildRoleContextBlock(domainFocus, workspaceProfile): string {
+  const parts = [domainFocus, workspaceProfile].map(s => String(s || "").trim()).filter(Boolean);
+  if (parts.length === 0) return "";
+  return `## Role Context (이번 작업 동적 컨텍스트)\n\n현재 페이즈 역할 레이어에 다음을 함께 적용한다:\n\n${parts.join("\n\n")}`;
+}
+
 export function buildTicketRulesGuide(opts: CliOpts = {}) {
   const surface = String(opts.ruleSurface || "ticket").trim() || "ticket";
   if (surface === "ticket") {
@@ -430,12 +480,14 @@ export function buildTicketRulesGuide(opts: CliOpts = {}) {
     // 없으면 진입 영역 rules. 스킬은 이 영역에 바인딩된 것만 노출(노드별 도구 바인딩).
     let activePolicyRole = null;
     let area = "rules";
+    let activeEntry = null;
     try {
       const index = readTicketIndexJson(opts.cwd);
       const activeId = index?.activeTicketId || null;
       if (activeId) {
         const entry = (index?.entries || []).find(e => e.id === activeId);
         if (entry) {
+          activeEntry = entry;
           const runtimeState = resolveTicketWorkflowRuntimeState(entry, entry.status);
           activePolicyRole = runtimeState?.state?.policyRole ?? "analysis";
           area = runtimeState?.name || `phase${entry.phase || 1}`;
@@ -445,6 +497,11 @@ export function buildTicketRulesGuide(opts: CliOpts = {}) {
 
     const guardrailsOpts = { ...opts, activePolicyRole };
 
+    // 역할 동적 컨텍스트: 티켓 APC/도메인 + 워크스페이스 프로필. 네이티브 플랫폼(claude)은
+    // 스킬 본문을 정적 파일로 깔아 본문 치환이 안 통하므로, 동적 컨텍스트는 rules surface의
+    // 별도 인라인 블록(ROLE_CONTEXT)으로 항상 출력한다(NEXT_ACTION과 동일 방식).
+    const roleContext = buildRoleContextBlock(deriveDomainFocus(activeEntry), readWorkspaceProfile(opts.cwd, opts.workspace, opts.platform));
+
     // #685: PROJECT_MEMORY 제거(.md가 state SSOT). PROJECT_RULES는 도메인 케이스만.
     // #694: TICKET_WORKFLOW 표 덤프 제거 — 워크플로 노드/전이는 XState 머신(SSOT)이고
     // 표를 매번 쏟는 건 노이즈다. 스킬은 현재 area 바인딩분만 노출.
@@ -453,6 +510,7 @@ export function buildTicketRulesGuide(opts: CliOpts = {}) {
       PROJECT_RULES: readProjectRuleSurface(opts.cwd, opts.platform),
       PROJECT_GUARDRAILS: readProjectPolicySurface(opts.cwd, { ...guardrailsOpts, platform: opts.platform }),
       AGENT_SKILLS: getActiveSkillsSurface(opts.cwd, opts.platform, area),
+      ROLE_CONTEXT: roleContext,
       NEXT_ACTION: buildNextActionBlock(opts)
     });
   }

package/scripts/cli-ticket-docmeta.ts

@@ -0,0 +1,103 @@
+import YAML from "yaml";
+
+export function splitTicketDocMetaSection(content = "") {
+  const src = String(content || "");
+  const lines = src.split(/\r?\n/);
+  const start = lines.findIndex(line => /^##\s+DocMeta\s*$/i.test(line.trim()));
+  if (start === -1) {
+    return { body: src, docmetaRaw: "", docmeta: null };
+  }
+
+  const body = lines.slice(0, start).join("\n").trimEnd();
+  const docmetaSection = lines.slice(start).join("\n").trim();
+  const fence = docmetaSection.match(/```(?:ya?ml)?\s*\n([\s\S]*?)\n```/i);
+  const docmetaRaw = fence ? fence[1].trim() : "";
+  let docmeta = null;
+  if (docmetaRaw) {
+    try {
+      docmeta = YAML.parse(docmetaRaw) || null;
+    } catch {
+      docmeta = null;
+    }
+  }
+  return { body, docmetaRaw, docmeta };
+}
+
+export function buildDocMetaFrontmatterSummary(docmeta = null) {
+  if (!docmeta || typeof docmeta !== "object") return {};
+  const errors = Array.isArray(docmeta.validation?.errors)
+    ? docmeta.validation.errors.map(value => String(value)).filter(Boolean)
+    : [];
+  return Object.fromEntries(Object.entries({
+    docmetaStatus: docmeta.output_status || undefined,
+    docmetaTarget: docmeta.target_state || docmeta.targetState || undefined,
+    docmetaValidation: docmeta.validation?.status || undefined,
+    docmetaErrors: errors.length ? errors : undefined
+  }).filter(([, value]) => value !== undefined && value !== ""));
+}
+
+export function clearDocMetaFrontmatterSummary(meta: Record<string, any> = {}) {
+  const next = { ...meta };
+  delete next.docmeta;
+  delete next.docmetaStatus;
+  delete next.docmetaTarget;
+  delete next.docmetaValidation;
+  delete next.docmetaErrors;
+  return next;
+}
+
+export function appendTicketDocMetaSection(content = "", docmeta = null) {
+  const body = splitTicketDocMetaSection(content).body.trimEnd();
+  if (!docmeta || typeof docmeta !== "object") return `${body}\n`;
+  const yamlStr = YAML.stringify(docmeta).trim();
+  return `${body}\n\n## DocMeta\n\n\`\`\`yaml\n${yamlStr}\n\`\`\`\n`;
+}
+
+export function buildTransitionValidationDocMeta(input: Record<string, any> = {}) {
+  const {
+    ticketId = "",
+    phase = 1,
+    status = "open",
+    currentState = `phase${phase || 1}`,
+    targetState = "",
+    requiredSlots = [],
+    slotValues = {},
+    slotSourceMap = {}
+  } = input;
+  const slots = Object.fromEntries(requiredSlots.map(slot => [slot, Boolean(slotValues[slot])]));
+  const filteredSlotSourceMap = Object.fromEntries(
+    requiredSlots.map(slot => [slot, slotSourceMap[slot] || { source: "unknown" }])
+  );
+  const errors = Object.entries(slots)
+    .filter(([, passed]) => !passed)
+    .map(([slot]) => slot);
+  return {
+    document_type: "ticket_validation",
+    document_subtype: "ticket_workflow_transition_gate",
+    contract_version: "documeta-0.1",
+    ticket_id: ticketId,
+    state: {
+      name: currentState,
+      phase,
+      status: String(status || "open")
+    },
+    target_state: targetState,
+    source_contract: {
+      required_slots: requiredSlots,
+      metadata_fields: ["ticket_id", "workspace_id", "phase", "status", "target_state", "source_path"]
+    },
+    slots,
+    slot_source_map: filteredSlotSourceMap,
+    validation: {
+      status: errors.length === 0 ? "PASS" : "NEEDS_FIX",
+      errors
+    },
+    output_status: errors.length === 0 ? "transition_allowed" : "transition_blocked",
+    adapter_contracts: {
+      cli: {
+        action: targetState === "phase2" ? "ticket move" : "ticket workflow transition",
+        stop_if_output_status: "transition_blocked"
+      }
+    }
+  };
+}

package/scripts/cli-ticket-document.ts

@@ -0,0 +1,153 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "fs";
+import { basename } from "path";
+import {
+  DEUK_ROOT_DIR,
+  computeTicketPath,
+  detectConsumerTicketDir,
+  normalizeTicketGroup,
+  parseFrontMatter,
+  stringifyFrontMatter,
+  writeFileLF,
+  makePath
+ , CliOpts } from "./cli-utils.js";
+import { appendTicketDocMetaSection, splitTicketDocMetaSection } from "./cli-ticket-docmeta.js";
+import { normalizeMarkdownContent } from "./lint-md.js";
+
+export function resolveTicketPath(cwd, relPath) {
+  // #080: stale entries (old INDEX/claim/frontmatter) may still carry the legacy
+  // `.deuk-agent/tickets/` prefix from in-workspace storage. The base passed here is
+  // the ticket root itself post-#622, so strip the prefix instead of nesting.
+  let rel = String(relPath || "");
+  const legacyPrefix = `${DEUK_ROOT_DIR}/tickets/`;
+  if (rel.startsWith(legacyPrefix)) rel = rel.slice(legacyPrefix.length);
+  return makePath(cwd, rel);
+}
+
+export function resolveTicketEntryPath(cwd, entry) {
+  return resolveTicketPath(cwd, entry?.path || "");
+}
+
+export function resolveTicketEntryOrComputedPath(cwd, entry) {
+  if (entry?.path) {
+    const fallbackPath = resolveTicketPath(cwd, entry.path);
+    if (existsSync(fallbackPath)) {
+      return fallbackPath;
+    }
+  }
+
+  const computedPath = resolveTicketPath(cwd, computeTicketPath(entry));
+  if (existsSync(computedPath)) {
+    return computedPath;
+  }
+
+  const ticketDir = detectConsumerTicketDir(cwd);
+  if (!ticketDir) {
+    return computedPath;
+  }
+
+  const fileName = entry?.fileName
+    ? String(entry.fileName)
+    : basename(entry?.path || computeTicketPath(entry));
+
+  if (!fileName) {
+    return computedPath;
+  }
+
+  const group = normalizeTicketGroup(entry?.group || "sub");
+  const archivedYearMonth = String(entry?.archiveYearMonth || "").trim();
+  const archivedDay = String(entry?.archiveDay || "").trim();
+  if (String(entry?.status || "").toLowerCase() === "archived" && archivedYearMonth && archivedDay) {
+    const dayPath = makePath(
+      ticketDir,
+      "archive",
+      group,
+      archivedYearMonth,
+      archivedDay,
+      fileName
+    );
+    if (existsSync(dayPath)) {
+      return dayPath;
+    }
+  }
+
+  const candidates = readdirSync(ticketDir, { withFileTypes: true });
+  const stack = [...candidates.filter(item => item.isDirectory()).map(item => makePath(ticketDir, item.name))];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (!existsSync(dir)) continue;
+
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const item of entries) {
+      if (item.isDirectory()) {
+        if (item.name === ".git" || item.name === "node_modules") continue;
+        stack.push(makePath(dir, item.name));
+        continue;
+      }
+      if (item.isFile() && item.name === fileName) {
+        return makePath(dir, item.name);
+      }
+    }
+  }
+
+  return computedPath;
+}
+
+export function readTicketDocument(cwd, entry, options: Record<string, any> = {}) {
+  const shouldCompute = options.computePath || !entry?.path;
+  const absPath = shouldCompute
+    ? resolveTicketEntryOrComputedPath(cwd, entry)
+    : resolveTicketEntryPath(cwd, entry);
+  const fallbackAbsPath = shouldCompute ? absPath : resolveTicketEntryOrComputedPath(cwd, entry);
+  const finalAbsPath = absPath === fallbackAbsPath ? absPath : fallbackAbsPath;
+
+  const parse = options.parse ?? true;
+  const requireExists = options.requireExists ?? true;
+  const action = options.action || "ticket";
+
+  const exists = existsSync(finalAbsPath);
+  if (!exists && requireExists) {
+    const target = entry?.path || "unknown";
+    throw new Error(`${action}: Ticket file not found: ${target}`);
+  }
+
+  if (!exists) {
+    return {
+      absPath: finalAbsPath,
+      exists: false,
+      body: "",
+      meta: {},
+      content: "",
+      docmeta: null,
+      docmetaRaw: ""
+    };
+  }
+
+  const body = readFileSync(finalAbsPath, "utf8");
+  if (!parse) {
+    return { absPath: finalAbsPath, exists: true, body, meta: {}, content: "", docmeta: null, docmetaRaw: "" };
+  }
+
+  const parsed = parseFrontMatter(body);
+  const ticketDocMeta = splitTicketDocMetaSection(parsed.content || "");
+  return {
+    absPath: finalAbsPath,
+    exists: true,
+    body,
+    ...parsed,
+    content: ticketDocMeta.body,
+    docmeta: ticketDocMeta.docmeta,
+    docmetaRaw: ticketDocMeta.docmetaRaw
+  };
+}
+
+export function renderTicketDocument({ meta = {} as Record<string, any>, content = "", docmeta = null } = {}) {
+  return stringifyFrontMatter(meta, appendTicketDocMetaSection(content, docmeta));
+}
+
+export function writeTicketMarkdownFile(absPath, body) {
+  writeFileLF(absPath, normalizeMarkdownContent(body));
+}
+
+export function writeTicketDocument(absPath, doc = {}) {
+  writeTicketMarkdownFile(absPath, renderTicketDocument(doc));
+}

package/scripts/cli-ticket-evidence.ts

@@ -0,0 +1,312 @@
+import { CliOpts, toSnakeCaseKey } from "./cli-utils.js";
+
+export function hasPlaceholderTokens(text) {
+  const lines = String(text || "")
+    .split("\n")
+    .map(line => line.trim().toLowerCase())
+    .filter(Boolean);
+
+  return lines.some(line => {
+    const normalized = line
+      .replace(/^[-*]\s+/, "")
+      .replace(/^\d+\.\s+/, "")
+      .trim();
+    return /^\[(?:add|fill)[^\]]*\]$/.test(normalized)
+      || /^<[^>]*(?:placeholder|todo|tbd|fill|add)[^>]*>$/.test(normalized)
+      || /^(?:placeholder|todo|tbd)$/.test(normalized);
+  });
+}
+
+export const ANALYSIS_DESIGN_SECTION_REQUIREMENTS = [
+  {
+    section: "Analysis",
+    reason: "analysis_missing",
+    scaffolds: [
+      "Record root-cause analysis, relevant file:line evidence, and hypotheses here."
+    ]
+  },
+  {
+    section: "Direction",
+    reason: "direction_missing",
+    scaffolds: [
+      "Record the proposed fix direction or follow-up design path."
+    ]
+  }
+];
+
+export const REQUIRED_PHASE1_SECTIONS = [
+  "Scope & Approval",
+  "Plan",
+  "Analysis",
+  "Direction"
+];
+
+export const REQUIRED_APC_MARKERS = [];
+
+const PHASE1_DATA_SECTIONS = [
+  "Plan",
+  "Analysis",
+  "Direction"
+];
+
+function dataSectionsForType(_type = "") {
+  return [...PHASE1_DATA_SECTIONS];
+}
+
+export function resolveTicketType(_opts) {
+  return "standard";
+}
+
+const FOLLOW_UP_DECISION_NO_FOLLOW_UP_PATTERNS = [
+  /\bno[- ]follow[- ]up\b/i,
+  /\bfollow[- ]up\s*:\s*none\b/i,
+  /\bno further action\b/i,
+  /\bnone required\b/i,
+  /후속(?:\s+작업)?\s*(?:없음|불필요)/,
+  /추가(?:\s+작업)?\s*(?:없음|불필요)/
+];
+
+export function parseMarkdownH2Sections(content) {
+  const lines = String(content || "").split("\n");
+  const sections = new Map();
+  let currentHeading = "";
+  let buffer = [];
+
+  const flush = () => {
+    if (!currentHeading) return;
+    sections.set(currentHeading, buffer.join("\n").trim());
+  };
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^##\s+(.+?)\s*$/);
+    if (headingMatch) {
+      flush();
+      currentHeading = headingMatch[1].trim();
+      buffer = [];
+      continue;
+    }
+    if (currentHeading) {
+      buffer.push(line);
+    }
+  }
+
+  flush();
+  return sections;
+}
+
+const PHASE1_HEADING_ALIASES = new Map([
+  ["apc", "Scope & Approval"],
+  ["agent permission contract", "Scope & Approval"],
+  ["agent permission contract (apc)", "Scope & Approval"],
+  ["scope", "Scope & Approval"],
+  ["compact plan", "Plan"],
+  ["problem analysis", "Analysis"],
+  ["source observations", "Analysis"],
+  ["cause hypotheses", "Analysis"],
+  ["audit evidence", "Analysis"],
+  ["improvement direction", "Direction"],
+  ...REQUIRED_PHASE1_SECTIONS.map(section => [section.toLowerCase(), section] as [string, string])
+]);
+
+export function normalizePhase1PlanBodyHeadings(body) {
+  return String(body || "").split("\n").map((line) => {
+    const match = line.match(/^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/);
+    if (!match) return line;
+    const normalized = PHASE1_HEADING_ALIASES.get(match[1].trim().toLowerCase());
+    return normalized ? `## ${normalized}` : line;
+  }).join("\n");
+}
+
+export function extractMarkdownSection(content, heading) {
+  return parseMarkdownH2Sections(content).get(String(heading || "").trim()) || "";
+}
+
+function extractMarkdownSectionByAliases(content, aliases) {
+  const sections = parseMarkdownH2Sections(content);
+  for (const alias of aliases) {
+    const value = sections.get(String(alias || "").trim());
+    if (value !== undefined) return value;
+  }
+  return "";
+}
+
+function hasSubstantiveSectionContent(text, scaffolds = []) {
+  const src = String(text || "").trim();
+  if (!src || hasPlaceholderTokens(src)) return false;
+  const normalized = src.replace(/\s+/g, " ");
+  return !scaffolds.some(phrase => normalized.includes(phrase));
+}
+
+function hasApcMarker(text, marker) {
+  const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const markerPattern = new RegExp(`^\\s*(?:#{1,6}\\s+)?${escapedMarker}(?:\\s|$)`);
+  return String(text || "").split("\n").some(line => markerPattern.test(line));
+}
+
+function getApcContentWithoutMarkers(text) {
+  return String(text || "")
+    .split("\n")
+    .map(line => {
+      for (const { marker } of REQUIRED_APC_MARKERS) {
+        const escapedMarker = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const markerPattern = new RegExp(`^\\s*(?:#{1,6}\\s+)?${escapedMarker}\\s*`);
+        if (markerPattern.test(line)) return line.replace(markerPattern, "");
+      }
+      return line;
+    })
+    .join("\n")
+    .trim();
+}
+
+function getMissingApcFields(text) {
+  return REQUIRED_APC_MARKERS
+    .filter(({ marker }) => !hasApcMarker(text, marker))
+    .map(field => field.name);
+}
+
+export function getPhase1PlanBodyReasons(body, opts: CliOpts = {}) {
+  const content = String(body || "");
+  const sections = parseMarkdownH2Sections(content);
+  const reasons = [];
+
+  for (const sectionName of ["Scope & Approval", ...dataSectionsForType()]) {
+    const sectionKey = toSnakeCaseKey(sectionName);
+    if (!sections.has(sectionName)) {
+      reasons.push(`${sectionKey}_missing`);
+      continue;
+    }
+    if (!hasSubstantiveSectionContent(sections.get(sectionName), [])) {
+      reasons.push(`${sectionKey}_incomplete`);
+    }
+  }
+
+  return reasons;
+}
+
+export function phase1SectionsForType(_type = "") {
+  return ["Agent Permission Contract (APC)", ...dataSectionsForType()];
+}
+
+export function getAnalysisDesignIncompleteReasons(meta, content) {
+  const reasons = [];
+  for (const requirement of ANALYSIS_DESIGN_SECTION_REQUIREMENTS) {
+    if (!hasSubstantiveSectionContent(extractMarkdownSection(content, requirement.section), requirement.scaffolds)) {
+      reasons.push(requirement.reason);
+    }
+  }
+
+  return reasons;
+}
+
+export function hasSubstantiveFollowUpDecision(content) {
+  return hasSubstantiveSectionContent(extractMarkdownSection(content, "Follow-up Decision"), []);
+}
+
+export function followUpDecisionMeansNoFollowUp(content) {
+  const text = extractMarkdownSection(content, "Follow-up Decision");
+  if (!hasSubstantiveSectionContent(text, [])) return false;
+  return FOLLOW_UP_DECISION_NO_FOLLOW_UP_PATTERNS.some(pattern => pattern.test(text));
+}
+
+export function hasTicketCompletionEvidence(content) {
+  return hasSubstantiveSectionContent(extractMarkdownSection(content, "Completion Report"), [])
+    || hasSubstantiveSectionContent(extractMarkdownSection(content, "Verification Outcome"), [])
+    || followUpDecisionMeansNoFollowUp(content);
+}
+
+const PHASE2_EXECUTION_SLOT_HEADINGS = [
+  "실행 슬롯",
+  "Execution Slots",
+  "Execution",
+];
+
+const PHASE2_EXECUTION_SLOT_FIELDS = [
+  /files\s+changed\s*:/i,
+  /commands?\s+run\s*:/i,
+  /interim\s+evidence\s*:/i,
+  /approved\s+scope\s*:/i,
+];
+
+export function hasPhase2ExecutionEvidence(content) {
+  const body = String(content || "");
+  // Check any phase2 execution slot heading section has non-empty content
+  for (const heading of PHASE2_EXECUTION_SLOT_HEADINGS) {
+    const section = extractMarkdownSection(body, heading);
+    if (section) {
+      const hasFilledField = PHASE2_EXECUTION_SLOT_FIELDS.some(pattern => {
+        const match = section.match(new RegExp(pattern.source + "\\s*(.+)", "i"));
+        return match && match[1] && match[1].trim().length > 0;
+      });
+      if (hasFilledField) return true;
+    }
+  }
+  // Fallback: any substantive content in Analysis or Direction (for bug-fix style tickets)
+  return hasSubstantiveSectionContent(extractMarkdownSection(body, "Analysis"), [])
+    || hasSubstantiveSectionContent(extractMarkdownSection(body, "Problem Analysis"), []);
+}
+
+// Compact, .md-aware slot status so `ticket use` shows what is already filled
+// vs. still empty, plus affected files — preventing the agent from re-reading the
+// ticket .md / find-grepping the tree to reconstruct context. Output stays terse.
+const SLOT_STATUS_SECTIONS_BY_PHASE = {
+  1: ["Scope & Approval", "Plan", "Analysis", "Direction"],
+  2: ["Scope & Approval", "Plan", "Analysis", "Direction"],
+  3: ["Analysis", "Direction", "Execution Result", "Verification"],
+  4: ["Execution Result", "Verification", "Residual Risk", "Follow-up Decision"]
+};
+
+// Pull file-ish tokens (path/with/slashes or name.ext) from the sections most
+// likely to record affected files, capped so the line never sprawls.
+function extractAffectedFiles(content, limit = 6) {
+  const src = [
+    extractMarkdownSection(content, "Execution Result"),
+    extractMarkdownSection(content, "Scope & Approval"),
+    extractMarkdownSection(content, "Plan")
+  ].join("\n");
+  const matches = src.match(/[\w./-]+\.[A-Za-z][\w]{0,4}\b/g) || [];
+  const seen = [];
+  for (const m of matches) {
+    const f = m.replace(/^[-*\s]+/, "");
+    if (!seen.includes(f)) seen.push(f);
+    if (seen.length >= limit) break;
+  }
+  return seen;
+}
+
+export function buildSlotStatusSummary(content, phase = 2) {
+  const sections = SLOT_STATUS_SECTIONS_BY_PHASE[phase >= 4 ? 4 : phase] || SLOT_STATUS_SECTIONS_BY_PHASE[2];
+  const filled = [];
+  const empty = [];
+  for (const name of sections) {
+    if (hasSubstantiveSectionContent(extractMarkdownSection(content, name), [])) filled.push(name);
+    else empty.push(name);
+  }
+  const files = extractAffectedFiles(content);
+  const lines = [];
+  lines.push(`[filled] ${filled.length ? filled.join(" · ") : "(none)"}`);
+  lines.push(`[empty]  ${empty.length ? empty.join(" · ") : "(none)"}`);
+  if (files.length) lines.push(`[files]  ${files.join(", ")}`);
+  return lines.join("\n");
+}
+
+export function getCloseWorkflowReasons(meta, content) {
+  const reasons = [];
+  const analysisScaffolds = ANALYSIS_DESIGN_SECTION_REQUIREMENTS[0].scaffolds;
+  const directionScaffolds = ANALYSIS_DESIGN_SECTION_REQUIREMENTS[1].scaffolds;
+  // Accept both canonical ("Analysis") and legacy ("Problem Analysis") heading names.
+  const analysisText = extractMarkdownSection(content, "Analysis")
+    || extractMarkdownSection(content, "Problem Analysis");
+  if (!hasSubstantiveSectionContent(analysisText, analysisScaffolds)) {
+    reasons.push("problem_analysis_missing");
+  }
+
+  // Accept both canonical ("Direction") and legacy ("Improvement Direction") heading names.
+  const directionText = extractMarkdownSection(content, "Direction")
+    || extractMarkdownSection(content, "Improvement Direction");
+  if (!hasSubstantiveSectionContent(directionText, directionScaffolds)
+    && !hasSubstantiveFollowUpDecision(content)) {
+    reasons.push("follow_up_decision_missing");
+  }
+
+  return reasons;
+}