feat(sdk): non-pass UAT items emit NON_PASS_RESULT reason (#3184)

Cycle 2 of ~15: introduces REASON_CODE frozen enum and UatReason
typed shape. Non-pass items (result not literally 'pass') now
contribute a typed reason instead of being invisible to callers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

sdk/src/query/phase-uat-passed.test.ts

@@ -6,7 +6,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { isPhaseUatPassed } from './phase-uat-passed.js';
+import { isPhaseUatPassed, REASON_CODE } from './phase-uat-passed.js';
 
 const UAT_PASS_CONTENT = `---
 status: complete
@@ -42,4 +42,35 @@ describe('isPhaseUatPassed', () => {
     expect(result.items[0].result).toBe('pass');
     expect(result.reasons.length).toBe(0);
   });
+
+  it('returns passed=false with NON_PASS_RESULT reason when single UAT item has result: issue', async () => {
+    const nonPassContent = `---
+status: complete
+phase: 5
+source: roadmap
+started: 2026-05-18T00:00:00Z
+updated: 2026-05-18T00:00:00Z
+---
+
+### 1. Some item
+expected: thing happens
+result: issue
+`;
+    const localTmp = await mkdtemp(join(tmpdir(), 'gsd-uat-c2-'));
+    try {
+      const phaseDir = join(localTmp, '.planning', 'phases', '05-non-pass');
+      await mkdir(phaseDir, { recursive: true });
+      await writeFile(join(phaseDir, '05-HUMAN-UAT.md'), nonPassContent);
+
+      const result = await isPhaseUatPassed(localTmp, '5');
+      expect(result.passed).toBe(false);
+      expect(result.items.length).toBe(1);
+      expect(result.reasons.length).toBe(1);
+      expect(result.reasons[0].code).toBe(REASON_CODE.NON_PASS_RESULT);
+      expect(result.reasons[0].capturedValue).toBe('issue');
+      expect(result.reasons[0].itemName).toBe('Some item');
+    } finally {
+      await rm(localTmp, { recursive: true, force: true });
+    }
+  });
 });

sdk/src/query/phase-uat-passed.ts

@@ -1,20 +1,40 @@
 /**
  * isPhaseUatPassed — SDK predicate answering "is phase N's UAT contract satisfied?"
  *
- * Cycle 1 of ~15 (walking skeleton): happy path only. No injection stripping,
- * no orphan detection, no human_verification frontmatter merge, no REASON_CODEs.
+ * Cycle 2 of ~15: introduces REASON_CODE frozen enum and UatReason typed shape.
+ * Non-pass items (result not literally 'pass') emit a typed NON_PASS_RESULT reason.
  */
 
 import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { resolvePhaseDir } from './phase-list-queries.js';
 
+export const REASON_CODE = Object.freeze({
+  NON_PASS_RESULT: 'non_pass_result',
+} as const);
+
+export type ReasonCode = typeof REASON_CODE[keyof typeof REASON_CODE];
+
+export type UatReason = {
+  code: ReasonCode;
+  file?: string;
+  itemName?: string;
+  capturedValue?: string;
+};
+
 /** Regex to parse all UAT items regardless of result value. */
 const UAT_ITEM_PATTERN =
   /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*(\w+)/g;
 
-function parseAllUatItems(content: string): Record<string, unknown>[] {
-  const items: Record<string, unknown>[] = [];
+interface UatItem {
+  test: number;
+  name: string;
+  expected: string;
+  result: string;
+}
+
+function parseAllUatItems(content: string): UatItem[] {
+  const items: UatItem[] = [];
   UAT_ITEM_PATTERN.lastIndex = 0;
   let m: RegExpMatchArray | null;
   while ((m = UAT_ITEM_PATTERN.exec(content)) !== null) {
@@ -36,7 +56,7 @@ export async function isPhaseUatPassed(
   workstream?: string,
 ): Promise<{
   passed: boolean;
-  reasons: unknown[];
+  reasons: UatReason[];
   reasonsHuman: string[];
   items: Record<string, unknown>[];
 }> {
@@ -48,13 +68,28 @@ export async function isPhaseUatPassed(
   const files = await readdir(dir);
   const uatFiles = files.filter((f) => f.endsWith('-HUMAN-UAT.md'));
 
-  const items: Record<string, unknown>[] = [];
+  const items: UatItem[] = [];
+  const reasons: UatReason[] = [];
+
   for (const file of uatFiles) {
-    const content = await readFile(join(dir, file), 'utf-8');
-    items.push(...parseAllUatItems(content));
+    const filePath = join(dir, file);
+    const relFile = relative(projectDir, filePath);
+    const content = await readFile(filePath, 'utf-8');
+    const parsed = parseAllUatItems(content);
+    for (const item of parsed) {
+      items.push(item);
+      if (item.result !== 'pass') {
+        reasons.push({
+          code: REASON_CODE.NON_PASS_RESULT,
+          file: relFile,
+          itemName: item.name,
+          capturedValue: item.result,
+        });
+      }
+    }
   }
 
-  const passed = items.length > 0 && items.every((i) => i.result === 'pass');
+  const passed = items.length > 0 && reasons.length === 0;
 
-  return { passed, reasons: [], reasonsHuman: [], items };
+  return { passed, reasons, reasonsHuman: [], items };
 }