@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdk/src/query/check-decision-coverage.ts

@@ -0,0 +1,554 @@
+/**
+ * Decision-coverage gates — issue #2492.
+ *
+ * Two handlers, two semantics:
+ *
+ *   - `check.decision-coverage-plan`  — translation gate, BLOCKING.
+ *     Plan-phase calls this after the existing requirements coverage gate.
+ *     Each trackable CONTEXT.md decision must appear (by id or normalized
+ *     phrase) in at least one PLAN.md `must_haves` / `truths` block or in
+ *     the plan body. A miss returns `passed: false` with a clear message
+ *     naming the missed decision; the workflow surfaces this to the user
+ *     and refuses to mark the phase planned.
+ *
+ *   - `check.decision-coverage-verify` — validation gate, NON-BLOCKING.
+ *     Verify-phase calls this. Each trackable decision is searched in the
+ *     phase's shipped artifacts (PLAN.md, SUMMARY.md, files_modified, recent
+ *     commit subjects). Misses are reported but do NOT change verification
+ *     status. Rationale: by verification time the work is done; a fuzzy
+ *     "honored" check is a soft signal, not a blocker.
+ *
+ * Both gates short-circuit when `workflow.context_coverage_gate` is `false`.
+ *
+ * Match strategy (used by both gates):
+ *   1. Strict id match — `D-NN` appears verbatim somewhere in the searched
+ *      text. This is the path users should aim for.
+ *   2. Soft phrase match — a normalized 6+-word slice of the decision text
+ *      appears as a substring. Catches plans/summaries that paraphrase but
+ *      forget the id.
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { loadConfig } from '../config.js';
+import { parseDecisions, type ParsedDecision } from './decisions.js';
+import type { QueryHandler } from './utils.js';
+
+const execFile = promisify(execFileCb);
+
+interface GateUncoveredItem {
+  id: string;
+  text: string;
+  category: string;
+}
+
+interface PlanGateData {
+  passed: boolean;
+  skipped: boolean;
+  reason?: string;
+  total: number;
+  covered: number;
+  uncovered: GateUncoveredItem[];
+  message: string;
+}
+
+interface VerifyGateData {
+  skipped: boolean;
+  blocking: false;
+  reason?: string;
+  total: number;
+  honored: number;
+  not_honored: GateUncoveredItem[];
+  message: string;
+}
+
+function normalizePhrase(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Minimum normalized words a decision must have to be soft-matchable. */
+const SOFT_PHRASE_MIN_WORDS = 6;
+
+/**
+ * Build a soft-match phrase: the first 6 normalized words. Six is empirically
+ * long enough to avoid collisions with common English fragments and short
+ * enough to survive minor rewordings.
+ *
+ * Returns an empty string when the decision text has fewer than
+ * SOFT_PHRASE_MIN_WORDS words — such decisions are effectively id-only and
+ * callers must rely on a `D-NN` citation (review F5).
+ */
+function softPhrase(text: string): string {
+  const words = normalizePhrase(text).split(' ').filter(Boolean);
+  if (words.length < SOFT_PHRASE_MIN_WORDS) return '';
+  return words.slice(0, SOFT_PHRASE_MIN_WORDS).join(' ');
+}
+
+/** True when a decision is too short to soft-match — caller must cite by id. */
+function requiresIdCitation(decision: ParsedDecision): boolean {
+  const wordCount = normalizePhrase(decision.text).split(' ').filter(Boolean).length;
+  return wordCount < SOFT_PHRASE_MIN_WORDS;
+}
+
+/** True when decision text or id appears in `haystack`. */
+function decisionMentioned(haystack: string, decision: ParsedDecision): boolean {
+  if (!haystack) return false;
+  const idRe = new RegExp(`\\b${decision.id}\\b`);
+  if (idRe.test(haystack)) return true;
+  const phrase = softPhrase(decision.text);
+  if (!phrase) return false; // too short to soft-match — id citation required
+  return normalizePhrase(haystack).includes(phrase);
+}
+
+async function readIfExists(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+async function loadPlanContents(phaseDir: string): Promise<string[]> {
+  if (!existsSync(phaseDir)) return [];
+  let entries: string[] = [];
+  try {
+    entries = await readdir(phaseDir);
+  } catch {
+    return [];
+  }
+  const planFiles = entries.filter((e) => /-PLAN\.md$/.test(e));
+  const out: string[] = [];
+  for (const f of planFiles) {
+    out.push(await readIfExists(join(phaseDir, f)));
+  }
+  return out;
+}
+
+/**
+ * One plan reduced to the sections the BLOCKING translation gate searches.
+ *
+ * The plan-phase gate refuses to honor a decision mention buried in a code
+ * fence, an HTML comment, or arbitrary prose elsewhere on the page. The user
+ * must put a `D-NN` citation (or a 6+-word phrase) in a designated section
+ * so they have an unambiguous way to make a decision deliberately uncovered.
+ *
+ * Designated sections (review F4):
+ *   - Front-matter `must_haves` block (YAML)
+ *   - Front-matter `truths` block (YAML)
+ *   - Front-matter `objective` field
+ *   - Body section under a heading whose text contains "must_haves",
+ *     "truths", "tasks", or "objective" (case-insensitive)
+ *
+ * HTML comments (`<!-- ... -->`) and fenced code blocks are stripped before
+ * extraction so neither a commented-out citation nor a literal example
+ * counts as coverage.
+ */
+interface PlanSections {
+  /** Concatenation of all designated section text, with HTML comments and code fences stripped. */
+  designated: string;
+}
+
+const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
+
+/** Strip HTML comments AND fenced code blocks from `text`. */
+function stripCommentsAndFences(text: string): string {
+  return text
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ');
+}
+
+/** Extract a YAML block scalar (key followed by indented continuation lines). */
+function extractYamlBlock(frontmatter: string, key: string): string {
+  const re = new RegExp(`^${key}\\s*:(.*)$`, 'm');
+  const match = frontmatter.match(re);
+  if (!match) return '';
+  const startIdx = (match.index ?? 0) + match[0].length;
+  const sameLine = match[1] ?? '';
+  const rest = frontmatter.slice(startIdx + 1).split(/\r?\n/);
+  const block: string[] = [sameLine];
+  for (const line of rest) {
+    // Stop at a non-indented, non-empty line (next top-level key) or end of frontmatter.
+    if (line === '' || /^\s/.test(line)) {
+      block.push(line);
+    } else {
+      break;
+    }
+  }
+  return block.join('\n');
+}
+
+function extractPlanSections(planContent: string): PlanSections {
+  if (!planContent) return { designated: '' };
+  const cleaned = stripCommentsAndFences(planContent);
+
+  // Split front-matter from body.
+  const fmMatch = cleaned.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  const frontmatter = fmMatch ? fmMatch[1] : '';
+  const body = fmMatch ? fmMatch[2] : cleaned;
+
+  const fmParts: string[] = [];
+  for (const key of ['must_haves', 'truths', 'objective']) {
+    const block = extractYamlBlock(frontmatter, key);
+    if (block) fmParts.push(block);
+  }
+
+  // Body sections under designated headings (must_haves, truths, tasks, objective).
+  const bodyLines = body.split(/\r?\n/);
+  const bodyParts: string[] = [];
+  let inDesignated = false;
+  for (const line of bodyLines) {
+    const heading = /^#{1,6}\s+/.test(line);
+    if (heading) {
+      inDesignated = DESIGNATED_HEADINGS_RE.test(line);
+      if (inDesignated) bodyParts.push(line);
+      continue;
+    }
+    if (inDesignated) bodyParts.push(line);
+  }
+
+  return { designated: [...fmParts, bodyParts.join('\n')].join('\n\n') };
+}
+
+async function loadPlanSections(phaseDir: string): Promise<PlanSections[]> {
+  const contents = await loadPlanContents(phaseDir);
+  return contents.map(extractPlanSections);
+}
+
+/** True when a decision is mentioned in any plan's designated sections. */
+function planSectionsMention(planSections: PlanSections[], decision: ParsedDecision): boolean {
+  for (const p of planSections) {
+    if (decisionMentioned(p.designated, decision)) return true;
+  }
+  return false;
+}
+
+async function loadGateConfig(projectDir: string, workstream?: string): Promise<boolean> {
+  try {
+    const cfg = await loadConfig(projectDir, workstream);
+    const wf = (cfg.workflow ?? {}) as unknown as Record<string, unknown>;
+    const v = wf.context_coverage_gate;
+    if (typeof v === 'boolean') return v;
+    // Tolerate stringified booleans coming from environment-variable-style configs,
+    // but warn loudly on numeric / other-shaped values so silent type drift surfaces.
+    // Schema-vs-loadConfig validation gap (review F16, mirror of #2609).
+    if (typeof v === 'string') {
+      const lower = v.toLowerCase();
+      if (lower === 'false' || lower === 'true') return lower !== 'false';
+      console.warn(
+        `[sdd] workflow.context_coverage_gate is a string "${v}" — expected boolean. Defaulting to ON.`,
+      );
+      return true;
+    }
+    if (v !== undefined && v !== null) {
+      console.warn(
+        `[sdd] workflow.context_coverage_gate has invalid type ${typeof v} (value: ${JSON.stringify(v)}); expected boolean. Defaulting to ON.`,
+      );
+    }
+    return true; // default ON
+  } catch {
+    return true;
+  }
+}
+
+function resolvePath(p: string, projectDir: string): string {
+  return isAbsolute(p) ? p : join(projectDir, p);
+}
+
+function buildPlanMessage(uncovered: GateUncoveredItem[]): string {
+  if (uncovered.length === 0) return 'All trackable CONTEXT.md decisions are covered by plans.';
+  const lines = [
+    `## ⚠ Decision Coverage Gap`,
+    ``,
+    `${uncovered.length} CONTEXT.md decision(s) are not covered by any plan:`,
+    ``,
+  ];
+  for (const u of uncovered) {
+    lines.push(`- **${u.id}** (${u.category || 'uncategorized'}): ${u.text}`);
+  }
+  lines.push('');
+  lines.push(
+    'Resolve by citing `D-NN:` in a relevant plan\'s `must_haves`/`truths` (or body),',
+  );
+  lines.push(
+    'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
+  );
+  return lines.join('\n');
+}
+
+function buildVerifyMessage(notHonored: GateUncoveredItem[]): string {
+  if (notHonored.length === 0)
+    return 'All trackable CONTEXT.md decisions are honored by shipped artifacts.';
+  const lines = [
+    `### Decision Coverage (warning)`,
+    ``,
+    `${notHonored.length} decision(s) not found in shipped artifacts:`,
+    ``,
+  ];
+  for (const u of notHonored) {
+    lines.push(`- **${u.id}** (${u.category || 'uncategorized'}): ${u.text}`);
+  }
+  lines.push('');
+  lines.push('This is a soft warning — verification status is unchanged.');
+  return lines.join('\n');
+}
+
+// ─── Plan-phase gate ──────────────────────────────────────────────────────
+
+export const checkDecisionCoveragePlan: QueryHandler = async (args, projectDir, workstream) => {
+  const phaseDir = args[0] ? resolvePath(args[0], projectDir) : '';
+  const contextPath = args[1] ? resolvePath(args[1], projectDir) : '';
+
+  const enabled = await loadGateConfig(projectDir, workstream);
+  if (!enabled) {
+    const data: PlanGateData = {
+      passed: true,
+      skipped: true,
+      reason: 'workflow.context_coverage_gate is false',
+      total: 0,
+      covered: 0,
+      uncovered: [],
+      message: 'Decision coverage gate disabled by config.',
+    };
+    return { data };
+  }
+
+  if (!contextPath || !existsSync(contextPath)) {
+    const data: PlanGateData = {
+      passed: true,
+      skipped: true,
+      reason: 'CONTEXT.md missing',
+      total: 0,
+      covered: 0,
+      uncovered: [],
+      message: 'No CONTEXT.md — nothing to check.',
+    };
+    return { data };
+  }
+
+  const contextRaw = await readIfExists(contextPath);
+  const decisions = parseDecisions(contextRaw).filter((d) => d.trackable);
+  if (decisions.length === 0) {
+    const data: PlanGateData = {
+      passed: true,
+      skipped: true,
+      reason: 'no trackable decisions',
+      total: 0,
+      covered: 0,
+      uncovered: [],
+      message: 'No trackable decisions in CONTEXT.md.',
+    };
+    return { data };
+  }
+
+  const planSections = await loadPlanSections(phaseDir);
+
+  const uncovered: GateUncoveredItem[] = [];
+  let covered = 0;
+  for (const d of decisions) {
+    if (planSectionsMention(planSections, d)) {
+      covered++;
+    } else {
+      uncovered.push({ id: d.id, text: d.text, category: d.category });
+    }
+  }
+
+  const passed = uncovered.length === 0;
+  const data: PlanGateData = {
+    passed,
+    skipped: false,
+    total: decisions.length,
+    covered,
+    uncovered,
+    message: buildPlanMessage(uncovered),
+  };
+  return { data };
+};
+
+// ─── Verify-phase gate ────────────────────────────────────────────────────
+
+/**
+ * Recent commit subjects + bodies, capped at 200 to span typical phase boundaries
+ * even on busy repos. The non-blocking verify gate trades precision for recall —
+ * a few extra commits in the haystack only inflate "honored" counts harmlessly,
+ * while too few commits could cause false misses on long-running phases (review F18).
+ */
+async function recentCommitMessages(projectDir: string, limit = 200): Promise<string> {
+  try {
+    const { stdout } = await execFile('git', ['log', `-n`, String(limit), '--pretty=%s%n%b'], {
+      cwd: projectDir,
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    return stdout;
+  } catch {
+    return '';
+  }
+}
+
+/** Per-file size cap when slurping modified-file contents into the verify haystack. */
+const MAX_MODIFIED_FILE_BYTES = 256 * 1024;
+
+/** Read a file and truncate to MAX_MODIFIED_FILE_BYTES; returns '' on error. */
+async function readBoundedFile(absPath: string): Promise<string> {
+  try {
+    const raw = await readFile(absPath, 'utf-8');
+    return raw.length > MAX_MODIFIED_FILE_BYTES ? raw.slice(0, MAX_MODIFIED_FILE_BYTES) : raw;
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * True when `candidatePath` (after resolution) is contained within `rootDir`.
+ * Rejects absolute paths outside the root, `..` traversal, and any input
+ * whose canonical form escapes the project boundary (review F7).
+ *
+ * Note: this is a lexical check. Symlink targets are NOT resolved here — we
+ * intentionally do not follow links, so a symlink inside the project pointing
+ * outside is not de-referenced (we read the link's target only if it resolves
+ * within projectDir). For full symlink hardening callers should run on a
+ * trusted SUMMARY.md.
+ */
+function isInsideRoot(candidatePath: string, rootDir: string): boolean {
+  const root = isAbsolute(rootDir) ? rootDir : join(process.cwd(), rootDir);
+  const target = isAbsolute(candidatePath) ? candidatePath : join(root, candidatePath);
+  // Normalize both via path.resolve-equivalent (join handles `..`).
+  const normalizedRoot = root.endsWith('/') ? root : root + '/';
+  const normalizedTarget = target;
+  return normalizedTarget === root || normalizedTarget.startsWith(normalizedRoot);
+}
+
+async function readModifiedFilesContent(projectDir: string, summaries: string[]): Promise<string> {
+  // Walk EVERY summary independently and aggregate file paths. The previous
+  // implementation matched only the first `files_modified:` block in a
+  // concatenated string — when two summaries shipped in one phase the second
+  // plan's files were silently dropped (review F6).
+  const out: string[] = [];
+  let total = 0;
+  for (const summary of summaries) {
+    if (!summary) continue;
+    // /g so multiple `files_modified:` blocks in a single summary are also captured.
+    const blockMatches = summary.matchAll(/files_modified:\s*\n((?:[ \t]*-\s+.+\n?)+)/g);
+    for (const blockMatch of blockMatches) {
+      const block = blockMatch[1] ?? '';
+      const files = [...block.matchAll(/-\s+(.+)/g)].map((m) =>
+        m[1].trim().replace(/^["']|["']$/g, ''),
+      );
+      for (const f of files) {
+        if (!f) continue;
+        if (total >= 50) break; // cap total files across all summaries
+        // Reject absolute paths AND any relative path that escapes projectDir.
+        if (!isInsideRoot(f, projectDir)) {
+          console.warn(
+            `[sdd] decision-coverage: skipping files_modified entry "${f}" — outside project root`,
+          );
+          continue;
+        }
+        out.push(await readBoundedFile(resolvePath(f, projectDir)));
+        total++;
+      }
+      if (total >= 50) break;
+    }
+    if (total >= 50) break;
+  }
+  return out.join('\n\n');
+}
+
+export const checkDecisionCoverageVerify: QueryHandler = async (args, projectDir, workstream) => {
+  const phaseDir = args[0] ? resolvePath(args[0], projectDir) : '';
+  const contextPath = args[1] ? resolvePath(args[1], projectDir) : '';
+
+  const enabled = await loadGateConfig(projectDir, workstream);
+  if (!enabled) {
+    const data: VerifyGateData = {
+      skipped: true,
+      blocking: false,
+      reason: 'workflow.context_coverage_gate is false',
+      total: 0,
+      honored: 0,
+      not_honored: [],
+      message: 'Decision coverage gate disabled by config.',
+    };
+    return { data };
+  }
+
+  if (!contextPath || !existsSync(contextPath)) {
+    const data: VerifyGateData = {
+      skipped: true,
+      blocking: false,
+      reason: 'CONTEXT.md missing',
+      total: 0,
+      honored: 0,
+      not_honored: [],
+      message: 'No CONTEXT.md — nothing to check.',
+    };
+    return { data };
+  }
+
+  const contextRaw = await readIfExists(contextPath);
+  const decisions = parseDecisions(contextRaw).filter((d) => d.trackable);
+  if (decisions.length === 0) {
+    const data: VerifyGateData = {
+      skipped: true,
+      blocking: false,
+      reason: 'no trackable decisions',
+      total: 0,
+      honored: 0,
+      not_honored: [],
+      message: 'No trackable decisions in CONTEXT.md.',
+    };
+    return { data };
+  }
+
+  // Verify-phase haystack is intentionally broad — this gate is non-blocking and looks
+  // for honored decisions across all phase artifacts, not just plan front-matter sections.
+  const planContents = await loadPlanContents(phaseDir);
+  // Read all *-SUMMARY.md files in phaseDir, capped to keep the haystack bounded.
+  const summaryParts: string[] = [];
+  let summaryContent = '';
+  if (existsSync(phaseDir)) {
+    try {
+      const entries = await readdir(phaseDir);
+      for (const e of entries.filter((x) => /-SUMMARY\.md$/.test(x))) {
+        summaryParts.push(await readIfExists(join(phaseDir, e)));
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  summaryContent = summaryParts.join('\n\n');
+
+  const filesModifiedContent = await readModifiedFilesContent(projectDir, summaryParts);
+  const commits = await recentCommitMessages(projectDir);
+
+  const haystack = [planContents.join('\n\n'), summaryContent, filesModifiedContent, commits].join(
+    '\n\n',
+  );
+
+  const notHonored: GateUncoveredItem[] = [];
+  let honored = 0;
+  for (const d of decisions) {
+    if (decisionMentioned(haystack, d)) {
+      honored++;
+    } else {
+      notHonored.push({ id: d.id, text: d.text, category: d.category });
+    }
+  }
+
+  const data: VerifyGateData = {
+    skipped: false,
+    blocking: false,
+    total: decisions.length,
+    honored,
+    not_honored: notHonored,
+    message: buildVerifyMessage(notHonored),
+  };
+  return { data };
+};

package/sdk/src/query/check-gates.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for `check.gates` (decision-routing audit §3.2).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { checkGates } from './check-gates.js';
+
+describe('checkGates', () => {
+  let projectDir: string;
+
+  beforeEach(async () => {
+    projectDir = join(tmpdir(), `sdd-check-gates-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(join(projectDir, '.planning', 'phases'), { recursive: true });
+    // Write a clean STATE.md
+    await writeFile(
+      join(projectDir, '.planning', 'STATE.md'),
+      '---\nstatus: active\n---\n\n# Project State\n\nStatus: active\n',
+      'utf-8',
+    );
+  });
+
+  afterEach(async () => {
+    await rm(projectDir, { recursive: true, force: true });
+  });
+
+  it('throws when workflow name arg is missing', async () => {
+    await expect(checkGates([], projectDir)).rejects.toThrow();
+  });
+
+  it('returns passed true when no blockers exist', async () => {
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(true);
+    expect(d.blockers).toEqual([]);
+  });
+
+  it('returns blocker when .continue-here.md is present in root', async () => {
+    await writeFile(join(projectDir, '.continue-here.md'), '# Continue here', 'utf-8');
+
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(false);
+    const blockers = d.blockers as Array<Record<string, unknown>>;
+    expect(blockers.length).toBeGreaterThan(0);
+    expect(blockers[0].gate).toBe('continue-here');
+    expect(blockers[0].severity).toBe('blocking');
+  });
+
+  it('returns blocker when STATE.md has status: failed', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'STATE.md'),
+      '---\nstatus: failed\n---\n\n# Project State\n',
+      'utf-8',
+    );
+
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(false);
+    const blockers = d.blockers as Array<Record<string, unknown>>;
+    const stateBlocker = blockers.find(b => b.gate === 'state-error');
+    expect(stateBlocker).toBeDefined();
+  });
+
+  it('returns blocker when STATE.md has status: error', async () => {
+    await writeFile(
+      join(projectDir, '.planning', 'STATE.md'),
+      '---\nstatus: error\n---\n\n# Project State\n',
+      'utf-8',
+    );
+
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(d.passed).toBe(false);
+    const blockers = d.blockers as Array<Record<string, unknown>>;
+    const stateBlocker = blockers.find(b => b.gate === 'state-error');
+    expect(stateBlocker).toBeDefined();
+  });
+
+  it('includes warnings shape in result', async () => {
+    const { data } = await checkGates(['execute-phase'], projectDir);
+    const d = data as Record<string, unknown>;
+    expect(Array.isArray(d.warnings)).toBe(true);
+  });
+
+  it('returns verification-debt warning when phase VERIFICATION.md has FAIL rows', async () => {
+    const phaseDir = join(projectDir, '.planning', 'phases', '01-foundation');
+    await mkdir(phaseDir, { recursive: true });
+    await writeFile(
+      join(phaseDir, 'VERIFICATION.md'),
+      '| T-01 | Auth works | FAIL |\n| T-02 | User model | PASS |\n',
+      'utf-8',
+    );
+
+    const { data } = await checkGates(['execute-phase', '--phase', '1'], projectDir);
+    const d = data as Record<string, unknown>;
+    const warnings = d.warnings as Array<Record<string, unknown>>;
+    const debtWarning = warnings.find(w => w.gate === 'verification-debt');
+    expect(debtWarning).toBeDefined();
+  });
+});