gsdd-cli 0.27.0 → 0.29.0

package/bin/lib/phase.mjs

@@ -3,17 +3,10 @@
 // IMPORTANT: No module-scope process.cwd() — ESM caching means sub-modules
 // evaluate once, so CWD must be computed inside function bodies.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
-import { dirname, join, relative } from 'path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, realpathSync } from 'fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'path';
 import { output } from './cli-utils.mjs';
-import { writeFingerprint } from './session-fingerprint.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
-import {
-  compareUiProofSlots,
-  findUiProofBundleFiles,
-  parseUiProofSlotsContent,
-  readUiProofBundleFile,
-} from './ui-proof.mjs';
 
 const PHASE_STATUS_MARKERS = {
   not_started: '[ ]',
@@ -175,314 +168,722 @@ function extractPlanFileArtifacts(planContent, workspaceRoot) {
   return artifacts;
 }
 
-function isPlanArtifactSatisfied(artifact) {
-  if (artifact.operation === 'delete') return !artifact.exists;
-  return artifact.exists;
+function extractFrontmatter(content) {
+  const match = String(content || '').replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+  return match ? match[1] : '';
 }
 
-function planArtifactFixHint(artifact) {
-  if (artifact.operation === 'delete') {
-    return `Complete the planned DELETE for ${artifact.file}, or revise the plan if the file should remain.`;
-  }
-  return `Create or update ${artifact.file} so the planned ${artifact.operation.toUpperCase()} artifact exists, or revise the plan if it is no longer in scope.`;
+function readTopLevelScalar(frontmatter, key) {
+  const escapedKey = String(key).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = String(frontmatter || '').match(new RegExp(`^${escapedKey}:\\s*(.*)$`, 'm'));
+  return match ? normalizeScalarValue(match[1]) : null;
 }
 
-function evaluatePlanArtifacts(artifacts) {
-  const unsatisfied = artifacts
-    .filter((artifact) => !isPlanArtifactSatisfied(artifact))
-    .map((artifact) => ({
-      ...artifact,
-      severity: 'blocker',
-      expected: artifact.operation === 'delete' ? 'absent' : 'present',
-      fix_hint: planArtifactFixHint(artifact),
-    }));
-  return {
-    satisfied: unsatisfied.length === 0,
-    unsatisfied,
-  };
+function hasTopLevelKey(frontmatter, key) {
+  const escapedKey = String(key).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^${escapedKey}:\\s*.*$`, 'm').test(String(frontmatter || ''));
 }
 
-function normalizeUiProofIssue(issue) {
-  return {
-    ...issue,
-    severity: issue.severity || 'blocker',
-    fix_hint: issue.fix_hint || issue.fix || 'Fix the UI proof issue before claiming verification is complete.',
-  };
+function readTopLevelBlock(frontmatter, key) {
+  const escapedKey = String(key).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const lines = String(frontmatter || '').replace(/\r\n/g, '\n').split('\n');
+  const startIndex = lines.findIndex((line) => new RegExp(`^${escapedKey}:\\s*(.*)$`).test(line));
+  if (startIndex === -1) return null;
+
+  const scalar = normalizeScalarValue(lines[startIndex].replace(new RegExp(`^${escapedKey}:\\s*`), ''));
+  const nested = [];
+  for (const line of lines.slice(startIndex + 1)) {
+    if (/^\S[^:]*:\s*/.test(line)) break;
+    if (line.trim()) nested.push(line.trim());
+  }
+  return { scalar, nested };
+}
+
+function legacyUiProofSlotsState(frontmatter) {
+  const block = readTopLevelBlock(frontmatter, 'ui_proof_slots');
+  if (!block) return null;
+  if (/^\[\s*\]$/.test(block.scalar)) return 'empty';
+  if (isMeaningfulFieldValue(block.scalar)) return 'present';
+  return block.nested.length > 0 ? 'present' : 'empty';
 }
 
 function stripInlineComment(value) {
-  return String(value || '').replace(/\s+#.*$/, '').trim();
+  const text = String(value || '');
+  let quote = null;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (quote) {
+      if (quote === '"' && char === '\\') {
+        index += 1;
+        continue;
+      }
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '#') return text.slice(0, index);
+  }
+  return text;
 }
 
-function stripOuterScalarQuotes(value) {
-  return String(value)
-    .trim()
-    .replace(/^(['"])([\s\S]*)\1$/g, '$2')
-    .trim();
+function normalizeScalarValue(value) {
+  let normalized = stripInlineComment(value).trim();
+  if (
+    (normalized.startsWith('"') && normalized.endsWith('"'))
+    || (normalized.startsWith("'") && normalized.endsWith("'"))
+  ) {
+    normalized = normalized.slice(1, -1).trim();
+  }
+  return normalized;
 }
 
-function normalizeNullableFrontmatterValue(value) {
-  const stripped = stripOuterScalarQuotes(value);
-  if (!stripped) return '';
-  if (stripped === '~') return '';
-  if (/^null$/i.test(stripped)) return '';
-  return stripped;
+function extractMarkdownSection(content, heading) {
+  return extractMarkdownSections(content, heading)[0] || '';
 }
 
-function extractUiProofSlotIds(value) {
-  const ids = [];
-  const slotPattern = /['"]?slot_id['"]?\s*:\s*['"]?([^,'"\]\s}]+)['"]?/g;
-  for (const match of String(value || '').matchAll(slotPattern)) {
-    ids.push(match[1].replace(/^['"]|['"]$/g, ''));
+function extractMarkdownSections(content, heading) {
+  const normalized = String(content || '').replace(/\r\n/g, '\n');
+  const escapedHeading = String(heading).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const headingMatcher = new RegExp(`^##\\s+${escapedHeading}\\s*$`, 'gim');
+  const matches = Array.from(normalized.matchAll(headingMatcher));
+  return matches.map((headingMatch, index) => {
+    const start = headingMatch.index + headingMatch[0].length;
+    const nextStart = matches[index + 1]?.index;
+    const rest = normalized.slice(start, nextStart);
+    const nextHeadingIndex = rest.search(/^##\s+/m);
+    return (nextHeadingIndex === -1 ? rest : rest.slice(0, nextHeadingIndex)).trim();
+  }).filter(Boolean);
+}
+
+function sectionFieldValue(section, label) {
+  const text = String(section || '');
+  const escapedLabel = String(label).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`^\\s*(?:[-*]\\s*)?${escapedLabel}:\\s*(.*)$`, 'im').exec(text);
+  if (!match) return '';
+
+  const inlineValue = normalizeScalarValue(match[1]);
+  if (inlineValue) return inlineValue;
+
+  const nestedValues = [];
+  const followingLines = text.slice(match.index + match[0].length).split(/\r?\n/);
+  for (const line of followingLines) {
+    if (!line.trim()) continue;
+    if (/^\S/.test(line)) break;
+    const nestedBullet = line.match(/^\s+[-*]\s*(.+)$/);
+    if (nestedBullet) {
+      nestedValues.push(nestedBullet[1].trim());
+      continue;
+    }
+    const nestedText = line.match(/^\s{2,}(.+)$/);
+    if (nestedText) {
+      nestedValues.push(nestedText[1].trim());
+      continue;
+    }
+    break;
   }
-  return ids;
+  return normalizeScalarValue(nestedValues.join(' '));
+}
+
+function isMeaningfulFieldValue(value) {
+  const normalized = normalizeScalarValue(value);
+  if (!normalized) return false;
+  if (/^n\/?a$/i.test(normalized)) return false;
+  if (/^(none|null|nil|~|tbd|todo|unknown)$/i.test(normalized)) return false;
+  if (/^\[.*\]$/.test(normalized)) return false;
+  if (/^<.*>$/.test(normalized)) return false;
+  return true;
+}
+
+function nonEmptyField(section, label) {
+  const value = sectionFieldValue(section, label);
+  return isMeaningfulFieldValue(value);
 }
 
-function readPlanFrontmatter(planContent) {
-  const content = String(planContent || '');
-  if (!content.startsWith('---')) return '';
-  const lines = content.split(/\r?\n/);
-  const frontmatter = [];
-  for (let index = 1; index < lines.length; index += 1) {
-    if (lines[index].trim() === '---') return frontmatter.join('\n');
-    frontmatter.push(lines[index]);
+function firstFieldValue(section, labels) {
+  for (const label of labels) {
+    const value = sectionFieldValue(section, label);
+    if (isMeaningfulFieldValue(value)) return value;
   }
   return '';
 }
 
-function frontmatterKeyBlock(frontmatter, key) {
-  const lines = String(frontmatter || '').split(/\r?\n/);
-  const keyPattern = new RegExp(`^${key}:[ \\t]*(.*)$`);
-  for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(keyPattern);
-    if (!match) continue;
-    const block = [];
-    for (let next = index + 1; next < lines.length; next += 1) {
-      const line = lines[next];
-      if (/^\S[^:\n]*:\s*/.test(line)) break;
-      block.push(line);
-    }
-    return { inline: stripInlineComment(match[1]), block };
+function evidenceKindValues(section) {
+  const value = firstFieldValue(section, ['Evidence kind', 'Evidence kinds']);
+  return value
+    .split(/[,/;|]|\band\b/i)
+    .map((part) => normalizeScalarValue(part).toLowerCase())
+    .filter(Boolean);
+}
+
+function hasSupportedBrowserProofEvidenceKind(section) {
+  return evidenceKindValues(section).some((kind) => kind === 'runtime' || kind === 'test');
+}
+
+function hasPassingBrowserProofResult(section) {
+  const value = firstFieldValue(section, ['Result']).toLowerCase();
+  if (!isMeaningfulFieldValue(value)) return false;
+  if (/\b(not\s+passed|fail(?:ed|ing)?|partial|partly|blocked|waived|deferred|missing|not[_ -]?applicable|unknown)\b/i.test(value)) {
+    return false;
   }
-  return null;
+  return /\b(pass(?:ed|ing)?|satisfied|success(?:ful)?)\b/i.test(value);
 }
 
-function frontmatterScalar(frontmatter, key) {
-  const entry = frontmatterKeyBlock(frontmatter, key);
-  if (!entry) return null;
-  if (entry.inline && !['|', '>'].includes(entry.inline)) return entry.inline;
-  return entry.block
-    .map((line) => line.trim())
-    .filter(Boolean)
-    .join(' ')
-    .trim();
+function isBoundedBrowserProofClaim(section) {
+  const value = firstFieldValue(section, ['Claim limit']).toLowerCase();
+  if (!isMeaningfulFieldValue(value)) return false;
+  if (/\b(no limit|unlimited|entire app|whole app|full app|complete app|everything works|all works|all flows|all ui|all screens|works everywhere)\b/i.test(value)) {
+    return false;
+  }
+  return true;
 }
 
-function readPlanUiProofContract(planContent) {
-  const frontmatter = readPlanFrontmatter(planContent);
-  const slotsEntry = frontmatterKeyBlock(frontmatter, 'ui_proof_slots');
-  const rationale = normalizeNullableFrontmatterValue(frontmatterScalar(frontmatter, 'no_ui_proof_rationale') || '');
-  const result = {
-    hasUiProofKey: Boolean(slotsEntry),
-    declaresSlots: false,
-    explicitEmptySlots: false,
-    noUiProofRationale: rationale,
-    hasNoUiProofRationale: Boolean(rationale.trim()),
-    slotIds: [],
-  };
+function hasPrivacySafetyNote(section) {
+  if (firstFieldValue(section, ['Privacy/safety', 'Privacy note', 'Safety note', 'Safe to publish'])) return true;
+  const artifacts = firstFieldValue(section, ['Artifacts']);
+  return /\b(local[-_ ]?only|safe to publish|not safe to publish|publishable|private|unsafe|sanitized)\b/i.test(artifacts);
+}
 
-  if (!slotsEntry) return result;
+function browserProofFixHint(code) {
+  if (code === 'retired_browser_proof_contract') {
+    return 'Replace retired ui_proof_slots/no_ui_proof_rationale fields with browser_proof_required and browser_proof_rationale.';
+  }
+  if (code === 'legacy_browser_proof_contract') {
+    return 'Update PLAN.md frontmatter to browser_proof_required: false and browser_proof_rationale when you next touch this phase.';
+  }
+  if (code === 'legacy_browser_proof_slots_require_migration') {
+    return 'Migrate non-empty ui_proof_slots to browser_proof_required: true plus a Browser Proof Plan before verifying this phase.';
+  }
+  if (code === 'conflicting_browser_proof_contract') {
+    return 'Use either the new browser_proof_* frontmatter or the legacy ui_proof_* frontmatter, not both.';
+  }
+  if (code === 'missing_browser_proof_declaration') {
+    return 'Add browser_proof_required: true|false and browser_proof_rationale to PLAN.md frontmatter.';
+  }
+  if (code === 'invalid_browser_proof_required') {
+    return 'Set browser_proof_required to true or false in PLAN.md frontmatter.';
+  }
+  if (code === 'missing_browser_proof_rationale') {
+    return 'Add a nonblank browser_proof_rationale explaining why browser proof is or is not required.';
+  }
+  if (code === 'missing_browser_proof_plan') {
+    return 'Add a ## Browser Proof Plan section or set browser_proof_required: false with a rationale if the work is not UI-sensitive.';
+  }
+  if (code === 'missing_browser_proof_observation') {
+    return 'Record a ## Browser Proof Observation in SUMMARY.md or link to an observation record before verifying browser-sensitive work.';
+  }
+  if (code === 'incomplete_browser_proof_observation') {
+    return 'Complete the Browser Proof Observation fields or narrow the proof claim.';
+  }
+  if (code === 'failed_browser_proof_observation') {
+    return 'Record a passing browser-proof observation, or narrow the claim and leave verification blocked.';
+  }
+  if (code === 'unsupported_browser_proof_evidence_kind') {
+    return 'Use Evidence kind: runtime or Evidence kind: test for browser proof, or narrow the claim.';
+  }
+  if (code === 'overbroad_browser_proof_claim') {
+    return 'Narrow Claim limit to the exact route, state, viewport, and behavior actually observed.';
+  }
+  if (code === 'invalid_browser_proof_observation_link') {
+    return 'Link browser-proof observation records as repo-local regular files inside this workspace.';
+  }
+  if (code === 'unmatched_browser_proof_observation') {
+    return 'Add a Plan field to each Browser Proof Observation that names the exact required PLAN.md artifact.';
+  }
+  return 'Complete the Browser Proof Plan fields or narrow the proof claim.';
+}
 
-  if (slotsEntry.inline) {
-    if (['[]', 'null', '~'].includes(slotsEntry.inline)) {
-      result.explicitEmptySlots = true;
-      return result;
-    }
-    result.declaresSlots = true;
-    result.slotIds.push(...extractUiProofSlotIds(slotsEntry.inline));
-    return result;
-  }
-
-  let sawMeaningfulLine = false;
-  for (const line of slotsEntry.block) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    sawMeaningfulLine = true;
-    if (/^\s+-\s+/.test(line)) result.declaresSlots = true;
-    result.slotIds.push(...extractUiProofSlotIds(trimmed));
-  }
-
-  result.explicitEmptySlots = !result.declaresSlots && !sawMeaningfulLine;
-  return result;
-}
-
-function findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths) {
-  const candidates = new Set();
-  const declaredPlans = [];
-  const declaredSlotIds = [];
-  const noUiPlans = [];
-  const contractErrors = [];
-  const names = new Set([
-    'ui-proof-slots.json',
-    'ui-proof-slots.md',
-    'UI-PROOF-SLOTS.json',
-    'UI-PROOF-SLOTS.md',
-    'planned-ui-proof.json',
-    'planned-ui-proof.md',
-  ]);
-
-  for (const planDisplayPath of planDisplayPaths) {
-    const fullPlanPath = join(planningDir, 'phases', planDisplayPath);
-    if (!existsSync(fullPlanPath)) continue;
-    const planContent = readFileSync(fullPlanPath, 'utf-8');
-    const relPlanPath = relative(planningDir, fullPlanPath).replace(/\\/g, '/');
-    const contract = readPlanUiProofContract(planContent);
-    const planDir = dirname(fullPlanPath);
-    const sidecars = [];
-    if (existsSync(planDir)) {
-      for (const entry of readdirSync(planDir, { withFileTypes: true })) {
-        if (entry.isFile() && names.has(entry.name)) {
-          sidecars.push(join(planDir, entry.name));
-        }
+function evaluateBrowserProofContract(planContent, planPath) {
+  const frontmatter = extractFrontmatter(planContent);
+  let requiredRaw = readTopLevelScalar(frontmatter, 'browser_proof_required');
+  let rationale = readTopLevelScalar(frontmatter, 'browser_proof_rationale');
+  let declarationPresent = requiredRaw !== null || rationale !== null;
+  const legacySlots = legacyUiProofSlotsState(frontmatter);
+  const legacyRationale = readTopLevelScalar(frontmatter, 'no_ui_proof_rationale');
+  const legacyNoUiCompatible = !declarationPresent
+    && legacySlots === 'empty'
+    && isMeaningfulFieldValue(legacyRationale);
+  const retiredKeys = ['ui_proof_slots', 'no_ui_proof_rationale', 'proof_bundle_version', 'claim_limits']
+    .filter((key) => hasTopLevelKey(frontmatter, key));
+  const blockers = [];
+  const warnings = [];
+
+  if (declarationPresent && retiredKeys.length > 0) {
+    blockers.push({
+      code: 'conflicting_browser_proof_contract',
+      severity: 'blocker',
+      path: planPath,
+      message: `PLAN.md mixes new browser-proof field(s) with retired field(s): ${retiredKeys.join(', ')}.`,
+      fix_hint: browserProofFixHint('conflicting_browser_proof_contract'),
+    });
+    return {
+      path: planPath,
+      declaration_present: declarationPresent,
+      required: null,
+      rationale,
+      legacy_compatible: false,
+      satisfied: false,
+      warnings,
+      blockers,
+    };
+  }
+
+  if (!declarationPresent && legacySlots === 'present') {
+    blockers.push({
+      code: 'legacy_browser_proof_slots_require_migration',
+      severity: 'blocker',
+      path: planPath,
+      message: 'PLAN.md uses legacy non-empty ui_proof_slots; migrate them to browser_proof_required plus a Browser Proof Plan before verification.',
+      fix_hint: browserProofFixHint('legacy_browser_proof_slots_require_migration'),
+    });
+    return {
+      path: planPath,
+      declaration_present: false,
+      required: null,
+      rationale: legacyRationale,
+      legacy_compatible: false,
+      satisfied: false,
+      warnings,
+      blockers,
+    };
+  }
+
+  if (!declarationPresent && legacySlots === 'empty' && !isMeaningfulFieldValue(legacyRationale)) {
+    blockers.push({
+      code: 'missing_browser_proof_rationale',
+      severity: 'blocker',
+      path: planPath,
+      message: 'Legacy ui_proof_slots: [] requires a meaningful no_ui_proof_rationale, or migration to browser_proof_required/browser_proof_rationale.',
+      fix_hint: browserProofFixHint('missing_browser_proof_rationale'),
+    });
+    return {
+      path: planPath,
+      declaration_present: false,
+      required: null,
+      rationale: legacyRationale,
+      legacy_compatible: false,
+      satisfied: false,
+      warnings,
+      blockers,
+    };
+  }
+
+  if (legacyNoUiCompatible) {
+    requiredRaw = 'false';
+    rationale = legacyRationale;
+    declarationPresent = true;
+    warnings.push({
+      code: 'legacy_browser_proof_contract',
+      severity: 'warning',
+      path: planPath,
+      message: 'PLAN.md uses legacy no-UI proof frontmatter; treating it as browser_proof_required: false for compatibility.',
+      fix_hint: browserProofFixHint('legacy_browser_proof_contract'),
+    });
+  }
+
+  const blockingRetiredKeys = legacyNoUiCompatible
+    ? retiredKeys.filter((key) => key !== 'ui_proof_slots' && key !== 'no_ui_proof_rationale')
+    : retiredKeys;
+
+  if (blockingRetiredKeys.length > 0) {
+    blockers.push({
+      code: 'retired_browser_proof_contract',
+      severity: 'blocker',
+      path: planPath,
+      message: `PLAN.md uses retired browser-proof field(s): ${blockingRetiredKeys.join(', ')}.`,
+      fix_hint: browserProofFixHint('retired_browser_proof_contract'),
+    });
+  }
+
+  if (!declarationPresent && retiredKeys.length === 0) {
+    blockers.push({
+      code: 'missing_browser_proof_declaration',
+      severity: 'blocker',
+      path: planPath,
+      message: 'PLAN.md must declare browser_proof_required and browser_proof_rationale before verification.',
+      fix_hint: browserProofFixHint('missing_browser_proof_declaration'),
+    });
+    return {
+      path: planPath,
+      declaration_present: false,
+      required: null,
+      rationale: null,
+      legacy_compatible: false,
+      satisfied: false,
+      warnings,
+      blockers,
+    };
+  }
+
+  const normalizedRequired = String(requiredRaw || '').toLowerCase();
+  const required = normalizedRequired === 'true'
+    ? true
+    : normalizedRequired === 'false'
+      ? false
+      : null;
+
+  if (required === null) {
+    blockers.push({
+      code: 'invalid_browser_proof_required',
+      severity: 'blocker',
+      path: planPath,
+      message: 'browser_proof_required must be true or false when the browser-proof contract is declared.',
+      fix_hint: browserProofFixHint('invalid_browser_proof_required'),
+    });
+  }
+
+  if (!isMeaningfulFieldValue(rationale)) {
+    blockers.push({
+      code: 'missing_browser_proof_rationale',
+      severity: 'blocker',
+      path: planPath,
+      message: 'browser_proof_rationale is required when the browser-proof contract is declared.',
+      fix_hint: browserProofFixHint('missing_browser_proof_rationale'),
+    });
+  }
+
+  if (required === true) {
+    const section = extractMarkdownSection(planContent, 'Browser Proof Plan');
+    if (!section) {
+      blockers.push({
+        code: 'missing_browser_proof_plan',
+        severity: 'blocker',
+        path: planPath,
+        message: 'browser_proof_required is true but PLAN.md has no ## Browser Proof Plan section.',
+        fix_hint: browserProofFixHint('missing_browser_proof_plan'),
+      });
+    } else {
+      const missingFields = ['Routes/states', 'Viewports', 'Runtime path', 'Observations', 'Artifacts', 'Claim limit']
+        .filter((field) => !nonEmptyField(section, field));
+      const hasEvidenceCommand = nonEmptyField(section, 'Evidence command');
+      const hasNoCommandRationale = nonEmptyField(section, 'No-command rationale');
+      if (!hasEvidenceCommand && !hasNoCommandRationale) {
+        missingFields.push('Evidence command or No-command rationale');
+      }
+      if (!hasSupportedBrowserProofEvidenceKind(section)) {
+        missingFields.push('Evidence kind');
+      }
+      if (!hasPrivacySafetyNote(section)) {
+        missingFields.push('Privacy/safety');
+      }
+      if (!isBoundedBrowserProofClaim(section)) {
+        missingFields.push('bounded Claim limit');
+      }
+      if (missingFields.length > 0) {
+        blockers.push({
+          code: 'incomplete_browser_proof_plan',
+          severity: 'blocker',
+          path: planPath,
+          message: `Browser Proof Plan is missing required field(s): ${missingFields.join(', ')}.`,
+          fix_hint: browserProofFixHint('incomplete_browser_proof_plan'),
+        });
       }
     }
+  }
 
-    if (contract.hasUiProofKey && !contract.declaresSlots && !contract.hasNoUiProofRationale) {
-      contractErrors.push(normalizeUiProofIssue({
-        code: 'missing_no_ui_proof_rationale',
-        path: `${relPlanPath}.no_ui_proof_rationale`,
-        message: 'Plan declares empty ui_proof_slots but does not provide a no_ui_proof_rationale.',
-        fix: 'Add a nonblank no_ui_proof_rationale for non-UI work, or declare required UI proof slots and add a planned slots artifact.',
-      }));
-    }
+  return {
+    path: planPath,
+    declaration_present: declarationPresent,
+    required,
+    rationale,
+    legacy_compatible: legacyNoUiCompatible,
+    satisfied: blockers.length === 0,
+    warnings,
+    blockers,
+  };
+}
 
-    if (contract.hasNoUiProofRationale && !contract.declaresSlots) {
-      noUiPlans.push({ plan: relPlanPath, sidecars });
+function sanitizeLinkedObservationPath(value) {
+  let text = normalizeScalarValue(value);
+  const markdownLink = text.match(/^\[[^\]]+\]\(([^)]+)\)$/);
+  if (markdownLink) text = markdownLink[1].trim();
+  text = text.replace(/^`|`$/g, '').trim();
+  return text;
+}
+
+function isInsidePath(parent, child) {
+  const relativePath = relative(resolve(parent), resolve(child));
+  return relativePath === '' || (!!relativePath && !relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+
+function readLinkedObservationRecords(summaryContent, summaryFullPath, workspaceRoot) {
+  const records = [];
+  const blockers = [];
+  const matcher = /^\s*(?:[-*]\s*)?(?:Browser Proof Observation|Browser proof observation|Observation record|Browser proof record):\s*(.+)$/gim;
+  let match;
+  while ((match = matcher.exec(String(summaryContent || '')))) {
+    const linkedPath = sanitizeLinkedObservationPath(match[1]);
+    if (!linkedPath) continue;
+    if (/^[a-z]+:\/\//i.test(linkedPath)) {
+      blockers.push({
+        code: 'invalid_browser_proof_observation_link',
+        severity: 'blocker',
+        path: linkedPath,
+        message: 'Browser Proof Observation link must be a repo-local relative file path, not a URL.',
+        fix_hint: browserProofFixHint('invalid_browser_proof_observation_link'),
+      });
+      continue;
+    }
+    if (isAbsolute(linkedPath)) {
+      blockers.push({
+        code: 'invalid_browser_proof_observation_link',
+        severity: 'blocker',
+        path: linkedPath,
+        message: 'Browser Proof Observation link must be a repo-local relative file path.',
+        fix_hint: browserProofFixHint('invalid_browser_proof_observation_link'),
+      });
       continue;
     }
 
-    if (!contract.declaresSlots) continue;
-
-    declaredPlans.push(relPlanPath);
-    for (const slotId of contract.slotIds) {
-      declaredSlotIds.push({ plan: relPlanPath, slot_id: slotId });
+    const candidates = [resolve(dirname(summaryFullPath), linkedPath), resolve(workspaceRoot, linkedPath)]
+      .filter((candidate, index, list) => list.indexOf(candidate) === index);
+    const existingPath = candidates.find((candidate) => existsSync(candidate));
+    if (!existingPath) {
+      blockers.push({
+        code: 'invalid_browser_proof_observation_link',
+        severity: 'blocker',
+        path: linkedPath,
+        message: 'Browser Proof Observation link does not resolve to an existing file in this workspace.',
+        fix_hint: browserProofFixHint('invalid_browser_proof_observation_link'),
+      });
+      continue;
     }
-    for (const entry of readdirSync(planDir, { withFileTypes: true })) {
-      if (entry.isFile() && names.has(entry.name)) {
-        candidates.add(join(planDir, entry.name));
+    try {
+      const realWorkspaceRoot = realpathSync(workspaceRoot);
+      const realExistingPath = realpathSync(existingPath);
+      if (!isInsidePath(realWorkspaceRoot, realExistingPath)) {
+        blockers.push({
+          code: 'invalid_browser_proof_observation_link',
+          severity: 'blocker',
+          path: linkedPath,
+          message: 'Browser Proof Observation link resolves outside this workspace.',
+          fix_hint: browserProofFixHint('invalid_browser_proof_observation_link'),
+        });
+        continue;
+      }
+      const stat = statSync(existingPath);
+      if (!stat.isFile()) {
+        blockers.push({
+          code: 'invalid_browser_proof_observation_link',
+          severity: 'blocker',
+          path: linkedPath,
+          message: 'Browser Proof Observation link must resolve to a regular file.',
+          fix_hint: browserProofFixHint('invalid_browser_proof_observation_link'),
+        });
+        continue;
       }
+      records.push(readFileSync(existingPath, 'utf-8'));
+    } catch (error) {
+      blockers.push({
+        code: 'invalid_browser_proof_observation_link',
+        severity: 'blocker',
+        path: linkedPath,
+        message: `Browser Proof Observation link could not be read: ${error.code || error.message}.`,
+        fix_hint: browserProofFixHint('invalid_browser_proof_observation_link'),
+      });
     }
   }
-  return { declaredPlans, declaredSlotIds, noUiPlans, contractErrors, files: [...candidates].sort() };
+  return { records, blockers };
 }
 
-function comparePhaseUiProof({ planningDir, workspaceRoot, planDisplayPaths }) {
-  const plannedDiscovery = findUiProofSlotPlansAndFiles(planningDir, planDisplayPaths);
-  const plannedFiles = plannedDiscovery.files;
-  const phaseDirs = new Set(planDisplayPaths.map((planDisplayPath) => dirname(join(planningDir, 'phases', planDisplayPath))));
-  const observedFiles = findUiProofBundleFiles(planningDir)
-    .filter((filePath) => phaseDirs.has(dirname(filePath)));
+function findBrowserProofObservationSections(summaryContent, summaryFullPath, workspaceRoot) {
+  const linked = readLinkedObservationRecords(summaryContent, summaryFullPath, workspaceRoot);
+  return {
+    sections: [
+      ...extractMarkdownSections(summaryContent, 'Browser Proof Observation'),
+      ...linked.records
+        .flatMap((record) => extractMarkdownSections(record, 'Browser Proof Observation')),
+    ].filter(Boolean),
+    blockers: linked.blockers,
+  };
+}
 
-  const plannedSlots = [];
-  const errors = [];
-  const warnings = [];
-  const planned = [];
-  const observed = [];
-
-  errors.push(...plannedDiscovery.contractErrors);
-  for (const noUiPlan of plannedDiscovery.noUiPlans) {
-    for (const filePath of noUiPlan.sidecars) {
-      warnings.push({
-        code: 'stale_ui_proof_sidecar_ignored',
-        severity: 'warn',
-        path: relative(workspaceRoot, filePath).replace(/\\/g, '/'),
-        message: `Plan ${noUiPlan.plan} records no_ui_proof_rationale, so the UI proof sidecar is ignored for closure.`,
-        fix_hint: 'Remove or classify the stale sidecar if it no longer belongs to this non-UI phase.',
-      });
-    }
+function browserProofObservationIssues(section) {
+  const requiredFieldSets = [
+    ['Flow', 'Routes/states'],
+    ['Viewports'],
+    ['Runtime path'],
+    ['Evidence kind', 'Evidence kinds'],
+    ['Evidence command', 'No-command rationale'],
+    ['Observed', 'Observations'],
+    ['Artifacts'],
+    ['Result'],
+    ['Claim limit'],
+  ];
+  const missingFields = requiredFieldSets
+    .filter((labels) => !labels.some((label) => nonEmptyField(section, label)))
+    .map((labels) => labels.join(' or '));
+  if (!hasPrivacySafetyNote(section)) {
+    missingFields.push('Privacy/safety');
   }
+  const issues = missingFields.length > 0
+    ? [{
+        code: 'incomplete_browser_proof_observation',
+        missingFields,
+        message: `Browser Proof Observation is missing required observed-proof field(s): ${missingFields.join(', ')}.`,
+      }]
+    : [];
+  if (!hasSupportedBrowserProofEvidenceKind(section)) {
+    issues.push({
+      code: 'unsupported_browser_proof_evidence_kind',
+      message: 'Browser Proof Observation evidence kind must include runtime or test.',
+    });
+  }
+  if (!hasPassingBrowserProofResult(section)) {
+    issues.push({
+      code: 'failed_browser_proof_observation',
+      message: 'Browser Proof Observation result is not an explicit pass.',
+    });
+  }
+  if (!isBoundedBrowserProofClaim(section)) {
+    issues.push({
+      code: 'overbroad_browser_proof_claim',
+      message: 'Browser Proof Observation claim limit is missing or too broad.',
+    });
+  }
+  return issues;
+}
 
-  for (const filePath of plannedFiles) {
-    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
-    const parsed = parseUiProofSlotsContent(readFileSync(filePath, 'utf-8'), rel);
-    planned.push(rel);
-    plannedSlots.push(...parsed.slots);
-    errors.push(...parsed.errors.map(normalizeUiProofIssue));
-  }
-
-  if (plannedSlots.length > 0 && plannedDiscovery.declaredSlotIds.length > 0) {
-    const plannedSlotIds = new Set(plannedSlots.map((slot) => String(slot?.slot_id || '')));
-    for (const declaredSlot of plannedDiscovery.declaredSlotIds) {
-      if (plannedSlotIds.has(String(declaredSlot.slot_id))) continue;
-      errors.push(normalizeUiProofIssue({
-        code: 'planned_ui_proof_slots_drift',
-        path: `${declaredSlot.plan}.ui_proof_slots`,
-        message: `Plan declares UI proof slot ${declaredSlot.slot_id}, but no matching slot exists in the planned UI proof artifact.`,
-        fix: 'Update ui-proof-slots.json or ui-proof-slots.md beside the plan so it matches the plan-declared slot IDs, or update the plan declaration.',
-      }));
-    }
+function isCompleteBrowserProofObservation(section) {
+  return browserProofObservationIssues(section).length === 0;
+}
+
+function normalizeArtifactReference(value) {
+  return String(value || '').replace(/\\/g, '/').toLowerCase();
+}
+
+function observationReferencesPlan(section, planPath) {
+  const planReference = sectionFieldValue(section, 'Plan')
+    || sectionFieldValue(section, 'Plan artifact')
+    || sectionFieldValue(section, 'PLAN');
+  if (!isMeaningfulFieldValue(planReference)) return false;
+  const normalizedReferences = normalizeArtifactReference(planReference)
+    .split(/[\n,;]+/)
+    .map((reference) => reference.trim().replace(/^\.\//, ''))
+    .filter(Boolean);
+  const normalizedPlanPath = normalizeArtifactReference(planPath);
+  return normalizedReferences.some((reference) => reference === normalizedPlanPath);
+}
+
+function evaluateBrowserProofObservation(browserProofPlans, matchingSummaries, phasesDir, workspaceRoot) {
+  const requiredPlans = browserProofPlans.filter((plan) => plan.required === true);
+  if (requiredPlans.length === 0 || matchingSummaries.length === 0) {
+    return {
+      satisfied: true,
+      sections: [],
+      warnings: [],
+      blockers: [],
+    };
   }
 
-  const observedBundles = [];
-  for (const filePath of observedFiles) {
-    const rel = relative(workspaceRoot, filePath).replace(/\\/g, '/');
-    const parsed = readUiProofBundleFile(filePath);
-    observed.push(rel);
-    if (parsed.errors.length > 0) {
-      errors.push(...parsed.errors.map((error) => normalizeUiProofIssue({ ...error, path: error.path || rel })));
-      continue;
-    }
-    observedBundles.push({
-      source: rel,
-      bundle: parsed.bundle,
-      options: {
-        requireLocalArtifactExists: true,
-        workspaceRoot,
-        bundleDir: dirname(filePath),
-      },
-    });
+  const sections = matchingSummaries.flatMap((summaryPath) => {
+    const summaryFullPath = join(phasesDir, summaryPath);
+    if (!existsSync(summaryFullPath)) return [];
+    const found = findBrowserProofObservationSections(
+      readFileSync(summaryFullPath, 'utf-8'),
+      summaryFullPath,
+      workspaceRoot
+    );
+    return found.sections.map((section) => ({ section, summaryPath }));
+  });
+  const linkBlockers = matchingSummaries.flatMap((summaryPath) => {
+    const summaryFullPath = join(phasesDir, summaryPath);
+    if (!existsSync(summaryFullPath)) return [];
+    return findBrowserProofObservationSections(
+      readFileSync(summaryFullPath, 'utf-8'),
+      summaryFullPath,
+      workspaceRoot
+    ).blockers.map((blocker) => ({ ...blocker, path: `${summaryPath}: ${blocker.path}` }));
+  });
+
+  if (sections.length === 0 && linkBlockers.length === 0) {
+    return {
+      satisfied: false,
+      sections,
+      warnings: [],
+      blockers: [{
+        code: 'missing_browser_proof_observation',
+        severity: 'blocker',
+        path: matchingSummaries.join(', '),
+        message: 'A plan requires browser proof, but no SUMMARY.md or linked record contains ## Browser Proof Observation.',
+        fix_hint: browserProofFixHint('missing_browser_proof_observation'),
+      }],
+    };
   }
 
-  if (plannedFiles.length === 0 && plannedDiscovery.declaredPlans.length > 0) {
-    const missingError = {
-      code: 'missing_planned_ui_proof_slots_file',
+  const issueBlockers = sections.flatMap(({ section, summaryPath }) => (
+    browserProofObservationIssues(section).map((issue) => ({
+      code: issue.code,
       severity: 'blocker',
-      path: plannedDiscovery.declaredPlans[0],
-      message: 'Plan declares ui_proof_slots but no ui-proof-slots artifact was found beside the plan.',
-      fix_hint: 'Create ui-proof-slots.json or ui-proof-slots.md beside the plan, or set ui_proof_slots: [] with a no_ui_proof_rationale if the phase is not UI-sensitive.',
-    };
+      path: summaryPath,
+      message: issue.message,
+      fix_hint: browserProofFixHint(issue.code),
+    }))
+  ));
+  const completeSections = sections.filter(({ section }) => isCompleteBrowserProofObservation(section));
+  if (completeSections.length === 0) {
     return {
-      planned,
-      observed,
-      status: 'missing',
-      comparison: { status: 'missing', slots: [], errors: [missingError] },
-      errors: [missingError],
-      warnings,
+      satisfied: false,
+      sections: sections.map(({ section }) => section),
+      warnings: [],
+      blockers: [...linkBlockers, ...issueBlockers],
     };
   }
 
-  if (plannedFiles.length === 0) {
+  const unmatchedPlans = requiredPlans.filter((plan) => (
+    !completeSections.some(({ section }) => observationReferencesPlan(section, plan.path))
+  ));
+  const unmatchedBlockers = unmatchedPlans.map((plan) => ({
+    code: 'unmatched_browser_proof_observation',
+    severity: 'blocker',
+    path: plan.path,
+    message: `No complete Browser Proof Observation references required plan ${plan.path}.`,
+    fix_hint: browserProofFixHint('unmatched_browser_proof_observation'),
+  }));
+  const blockers = [...linkBlockers, ...issueBlockers, ...unmatchedBlockers];
+  if (blockers.length === 0) {
     return {
-      planned,
-      observed,
-      status: errors.length > 0 ? 'partial' : 'not_applicable',
-      comparison: null,
-      errors,
-      warnings,
+      satisfied: true,
+      sections: sections.map(({ section }) => section),
+      warnings: [],
+      blockers: [],
     };
   }
 
-  const comparison = errors.length > 0
-    ? { status: 'partial', slots: [], errors: errors.map(normalizeUiProofIssue) }
-    : compareUiProofSlots(plannedSlots, observedBundles);
+  return {
+    satisfied: false,
+    sections: sections.map(({ section }) => section),
+    warnings: [],
+    blockers,
+  };
+}
 
+function isPlanArtifactSatisfied(artifact) {
+  if (artifact.operation === 'delete') return !artifact.exists;
+  return artifact.exists;
+}
+
+function planArtifactFixHint(artifact) {
+  if (artifact.operation === 'delete') {
+    return `Complete the planned DELETE for ${artifact.file}, or revise the plan if the file should remain.`;
+  }
+  return `Create or update ${artifact.file} so the planned ${artifact.operation.toUpperCase()} artifact exists, or revise the plan if it is no longer in scope.`;
+}
+
+function evaluatePlanArtifacts(artifacts) {
+  const unsatisfied = artifacts
+    .filter((artifact) => !isPlanArtifactSatisfied(artifact))
+    .map((artifact) => ({
+      ...artifact,
+      severity: 'blocker',
+      expected: artifact.operation === 'delete' ? 'absent' : 'present',
+      fix_hint: planArtifactFixHint(artifact),
+    }));
   return {
-    planned,
-    observed,
-    status: comparison.status,
-    comparison,
-    errors: comparison.errors || errors,
-    warnings,
+    satisfied: unsatisfied.length === 0,
+    unsatisfied,
   };
 }
 
@@ -568,6 +969,7 @@ export function cmdPhaseStatus(...args) {
     return;
   }
   const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const stateName = basename(planningDir);
   const [phaseNumber, status] = normalizedArgs;
 
   if (!phaseNumber || !status) {
@@ -588,9 +990,8 @@ export function cmdPhaseStatus(...args) {
     const changed = updated !== roadmap;
     if (changed) {
       writeFileSync(roadmapPath, updated);
-      try { writeFingerprint(planningDir); } catch { /* best-effort */ }
     }
-    output({ phase: phaseNumber, status, roadmap: '.planning/ROADMAP.md', changed });
+    output({ phase: phaseNumber, status, roadmap: `${stateName}/ROADMAP.md`, changed });
   } catch (error) {
     console.error(error.message);
     process.exitCode = 1;
@@ -605,9 +1006,10 @@ export function cmdFindPhase(...args) {
     return;
   }
   const phaseNum = normalizedArgs[0];
+  const stateName = basename(planningDir);
 
   if (!existsSync(planningDir)) {
-    output({ error: 'No .planning/ directory found. Run `npx -y gsdd-cli init` then the new-project workflow first.' });
+    output({ error: `No ${stateName}/ directory found. Run \`npx -y gsdd-cli init\` then the new-project workflow first.` });
     return;
   }
 
@@ -660,9 +1062,10 @@ export function buildPhaseVerificationReport(...args) {
   if (!phaseNum) {
     return { ok: false, error: 'Usage: gsdd verify <phase-number>', exitCode: 1 };
   }
+  const stateName = basename(planningDir);
 
   if (!existsSync(planningDir)) {
-    return { ok: false, error: 'No .planning/ directory found.', exitCode: 1 };
+    return { ok: false, error: `No ${stateName}/ directory found.`, exitCode: 1 };
   }
   const phasesDir = join(planningDir, 'phases');
   const matchingPlans = findFiles(phasesDir, `${padPhase(phaseNum)}-PLAN`);
@@ -672,7 +1075,7 @@ export function buildPhaseVerificationReport(...args) {
     prerequisiteBlockers.push({
       code: 'missing_phase_plan',
       severity: 'blocker',
-      path: `.planning/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-PLAN.md`,
+      path: `${stateName}/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-PLAN.md`,
       message: `No PLAN.md artifact was found for phase ${normalizePhaseToken(phaseNum)}.`,
       fix_hint: `Run /gsdd-plan ${normalizePhaseToken(phaseNum)} before verifying this phase.`,
     });
@@ -681,7 +1084,7 @@ export function buildPhaseVerificationReport(...args) {
     prerequisiteBlockers.push({
       code: 'missing_phase_summary',
       severity: 'blocker',
-      path: `.planning/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-SUMMARY.md`,
+      path: `${stateName}/phases/${padPhase(phaseNum)}-*/${padPhase(phaseNum)}-SUMMARY.md`,
       message: `No SUMMARY.md artifact was found for phase ${normalizePhaseToken(phaseNum)}.`,
       fix_hint: `Run /gsdd-execute ${normalizePhaseToken(phaseNum)} before verifying this phase.`,
     });
@@ -692,27 +1095,45 @@ export function buildPhaseVerificationReport(...args) {
       ? extractPlanFileArtifacts(readFileSync(fullPath, 'utf-8'), workspaceRoot)
       : [];
   });
-  const artifactStatus = evaluatePlanArtifacts(artifacts);
-  const uiProof = comparePhaseUiProof({
-    planningDir,
-    workspaceRoot,
-    planDisplayPaths: matchingPlans,
+  const browserProofPlans = matchingPlans.map((planPath) => {
+    const fullPath = join(phasesDir, planPath);
+    return existsSync(fullPath)
+      ? evaluateBrowserProofContract(readFileSync(fullPath, 'utf-8'), planPath)
+      : {
+          path: planPath,
+          declaration_present: false,
+          required: null,
+          rationale: null,
+          satisfied: true,
+          warnings: [],
+          blockers: [],
+        };
   });
-  const uiProofSatisfied = ['satisfied', 'not_applicable'].includes(uiProof.status);
+  const browserProofObservationStatus = evaluateBrowserProofObservation(
+    browserProofPlans,
+    matchingSummaries,
+    phasesDir,
+    workspaceRoot
+  );
+  const browserProofBlockers = [
+    ...browserProofPlans.flatMap((plan) => plan.blockers),
+    ...browserProofObservationStatus.blockers,
+  ];
+  const browserProofWarnings = [
+    ...browserProofPlans.flatMap((plan) => plan.warnings || []),
+    ...(browserProofObservationStatus.warnings || []),
+  ];
+  const artifactStatus = evaluatePlanArtifacts(artifacts);
   const legacyVerified = matchingPlans.length > 0 && matchingSummaries.length > 0;
-  const uiProofGate = {
-    status: uiProof.status,
-    required: uiProof.status !== 'not_applicable',
-    satisfied: uiProofSatisfied,
-    blocks_verification: uiProof.status !== 'not_applicable' && !uiProofSatisfied,
-    required_block: uiProof.status !== 'not_applicable' && !uiProofSatisfied ? 'ui-proof-failed' : null,
-  };
   const blockedOn = [
     ...(prerequisiteBlockers.length > 0 ? ['prerequisites'] : []),
     ...(artifactStatus.satisfied ? [] : ['artifacts']),
-    ...(uiProofGate.blocks_verification ? ['ui_proof'] : []),
+    ...(browserProofBlockers.length > 0 ? ['browser_proof'] : []),
   ];
-  const closureVerified = legacyVerified && prerequisiteBlockers.length === 0 && artifactStatus.satisfied && uiProofSatisfied;
+  const closureVerified = legacyVerified
+    && prerequisiteBlockers.length === 0
+    && artifactStatus.satisfied
+    && browserProofBlockers.length === 0;
 
   const result = {
     phase: normalizePhaseToken(phaseNum),
@@ -722,7 +1143,13 @@ export function buildPhaseVerificationReport(...args) {
     artifacts,
     allExist: artifacts.every((artifact) => artifact.exists),
     artifact_status: artifactStatus,
-    uiProof,
+    browser_proof_status: {
+      satisfied: browserProofBlockers.length === 0,
+      plans: browserProofPlans,
+      observations: browserProofObservationStatus,
+      warnings: browserProofWarnings,
+      blockers: browserProofBlockers,
+    },
     verified: closureVerified,
     legacy_verified: legacyVerified,
     phase_artifacts_present: legacyVerified,
@@ -730,7 +1157,6 @@ export function buildPhaseVerificationReport(...args) {
       satisfied: prerequisiteBlockers.length === 0,
       blockers: prerequisiteBlockers,
     },
-    ui_proof: uiProofGate,
     blocked_on: blockedOn,
     blocks_verification: blockedOn.length > 0,
   };