gsdd-cli 0.20.0 → 0.22.0

package/agents/executor.md

@@ -211,7 +211,18 @@ Before reporting a task complete:
 - A task is not complete because code was written. It is complete when the intended verification path actually passes.
 
 ### UI Proof Execution
-If the plan defines UI proof slots, record observed proof against the exact claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit before claiming task completion. Artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports are local-only/unsafe by default and cannot back public, tracked, delivery, release, or publication proof claims. Use `gsdd ui-proof validate <path>` or `gsdd health` when a bundle exists. Artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. Missing or weakly linked evidence must be recorded as proof debt, waiver, deferment, or reduced claim language rather than satisfied proof.
+If the plan defines UI proof slots, record observed proof against the exact claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit before claiming task completion.
+
+Use `agent-browser` as the default live UI proof path:
+- open the planned route/state
+- capture interactive snapshots/refs when relevant
+- exercise the changed flow
+- capture screenshots for the planned viewport(s)
+- record relevant console/network observations
+
+If `agent-browser` is unavailable, record the availability constraint and closest project-native interactive browser fallback in the proof bundle instead of silently treating the fallback as the default path. Existing Playwright/package-script browser tests remain canonical repeatable regression evidence when present; use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification.
+
+Artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports are local-only/unsafe by default and cannot back public, tracked, delivery, release, or publication proof claims. Use `gsdd ui-proof validate <path>` or `gsdd health` when a bundle exists. Artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. Missing or weakly linked evidence must be recorded as proof debt, waiver, deferment, or reduced claim language rather than satisfied proof.
 </execution_loop>
 
 <checkpoint_protocol>

package/agents/planner.md

@@ -158,6 +158,8 @@ For UI-sensitive work, plan proof slots that can later be matched exactly to cla
 
 Require observed artifacts to carry `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; when a planned slot is meant to support public, publication, tracked, delivery, or release proof, say to validate the observed bundle with `gsdd ui-proof validate <path> --claim <...>`. `gsdd ui-proof validate`/`gsdd health` must catch invalid bundle metadata when present.
 
+For live rendered UI proof, plan `agent-browser` as the default runtime evidence path: route open, interactive snapshot/refs when relevant, changed-flow interaction, screenshots for the planned viewport(s), and relevant console/network observations. If `agent-browser` is unavailable in the runtime, require an explicit availability constraint and the closest project-native interactive browser fallback before narrowing the claim. Existing Playwright/package-script browser tests remain the canonical repeatable regression path when present; do not scaffold new browser infrastructure by default. The planner chooses viewport coverage, but must explain why the viewport set is sufficient for the claim or narrow the claim limit; responsive claims need desktop/mobile or equivalent state coverage.
+
 Do not let source annotations, AST/cAST findings, semantic search, comments, or Semble-like retrieval satisfy proof slots; they are discovery hints only. Human acceptance can narrow or waive a claim and record proof debt, but it must not turn missing or mismatched non-human evidence into `satisfied` proof.
 </ui_proof_planning>
 

package/agents/verifier.md

@@ -123,7 +123,7 @@ Do not return a flat symptom list when the same underlying breakage explains mul
 
 Visual correctness, live interaction quality, and some external integrations still need explicit human checks.
 
-For UI proof slots, fail closed unless observed proof is matched to the exact claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. Artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; local-only or unsafe artifacts cannot back public, tracked, delivery, release, or publication proof claims, and `gsdd ui-proof validate`/`gsdd health` metadata failures block the stronger proof claim. Screenshots, traces, reports, Gherkin, a11y scans, E2E outputs, manual notes, source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval do not satisfy proof by existence alone. Human acceptance records risk, waiver, deferment, proof debt, or a narrowed claim; it does not upgrade missing or mismatched non-human proof to `satisfied`.
+For UI proof slots, fail closed unless observed proof is matched to the exact claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. For live UI runtime proof, expect `agent-browser` as the default captured tool unless the observed bundle explains a project-native equivalent or an availability constraint; do not fail solely because another browser tool was used, but downgrade vague proof that lacks exact route/state, viewport coverage or rationale, interactive steps/refs where relevant, screenshot/report artifacts, or relevant console/network observations. Existing Playwright/package-script browser tests count as canonical repeatable regression evidence, not as a replacement for scoped runtime proof when the slot requires `runtime`. Artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; local-only or unsafe artifacts cannot back public, tracked, delivery, release, or publication proof claims, and `gsdd ui-proof validate`/`gsdd health` metadata failures block the stronger proof claim. Screenshots, traces, reports, Gherkin, a11y scans, E2E outputs, manual notes, source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval do not satisfy proof by existence alone. Human acceptance records risk, waiver, deferment, proof debt, or a narrowed claim; it does not upgrade missing or mismatched non-human proof to `satisfied`.
 
 ## Step 9: Determine overall status
 

package/bin/lib/health.mjs

@@ -147,13 +147,13 @@ export function createCmdHealth(ctx) {
       const parsed = readUiProofBundleFile(bundlePath);
       const validation = parsed.errors.length > 0
         ? { valid: false, errors: parsed.errors }
-        : validateUiProofBundle(parsed.bundle);
+        : validateUiProofBundle(parsed.bundle, { requireLocalArtifactExists: true, workspaceRoot: cwd });
       if (!validation.valid) {
         errors.push({
           id: 'E10',
           severity: 'ERROR',
           message: `${relativePath} has invalid UI proof metadata (${validation.errors.map((entry) => entry.code).join(', ')})`,
-          fix: 'Run `gsdd ui-proof validate <path>` and add required privacy metadata, claim limits, fixed evidence kinds, observation artifact references, and safe-to-publish handling.',
+          fix: 'Run `gsdd ui-proof validate <path>` and add required privacy metadata, claim limits, fixed evidence kinds, concise tool provenance, failure classification when failed or partial, observation artifact references, existing local artifact paths, and safe-to-publish handling.',
         });
       }
     }

package/bin/lib/init-runtime.mjs

@@ -186,9 +186,12 @@ Commands:
   phase-status <N> <status>   Update ROADMAP.md phase status ([ ] / [-] / [x])
   lifecycle-preflight <surface> [phase]
                               Inspect deterministic lifecycle gate results for a workflow surface
-  session-fingerprint write    Rebaseline planning-state drift after reviewing changed planning files
+  session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]
+                              Rebaseline planning-state drift after reviewing changed planning files
   ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]
                               Validate UI proof metadata; use --claim for stronger proof uses
+  ui-proof compare <planned-slots-json> [observed-bundle-json ...]
+                              Compare planned UI proof slots against observed bundles
   help                        Show this summary
 
 Platforms (for --tools):
@@ -259,7 +262,7 @@ Advanced/internal helpers (kept available, but not the primary first-run user st
   lifecycle-preflight       Inspect deterministic lifecycle gate results for a workflow surface
   session-fingerprint       Rebaseline the local planning-state fingerprint after review
   phase-status              Update ROADMAP.md phase status through the local helper surface
-  ui-proof                  Validate UI proof metadata; use --claim for stronger proof uses
+  ui-proof                  Validate UI proof metadata and compare planned slots to observed bundles
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/lifecycle-preflight.mjs

@@ -52,6 +52,11 @@ const SURFACE_POLICIES = {
     ownedWrites: ['spec', 'roadmap', 'phase-directories'],
     explicitLifecycleMutation: 'none',
   },
+  'plan-milestone-gaps': {
+    classification: 'owned_write',
+    ownedWrites: ['roadmap', 'phase-directories'],
+    explicitLifecycleMutation: 'none',
+  },
   resume: {
     classification: 'owned_write',
     ownedWrites: ['checkpoint-cleanup'],

package/bin/lib/rendering.mjs

@@ -72,10 +72,12 @@ function printHelp() {
     '  lifecycle-preflight <surface> [phase]',
     '                               Inspect lifecycle gate results for a workflow surface',
     '                               Example: node .planning/bin/gsdd.mjs lifecycle-preflight verify 1 --expects-mutation phase-status',
-    '  session-fingerprint write',
+    '  session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]',
     '                               Rebaseline planning-state drift after reviewing changed planning files',
     '  ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]',
     '                               Validate UI proof metadata; use --claim for stronger proof uses',
+    '  ui-proof compare <planned-slots-json> [observed-bundle-json ...]',
+    '                               Compare planned UI proof slots against observed bundles',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',

package/bin/lib/session-fingerprint.mjs

@@ -63,16 +63,56 @@ export function cmdSessionFingerprint(...args) {
     return;
   }
 
-  const [action] = normalizedArgs;
+  const [action, ...flags] = normalizedArgs;
   if (action !== 'write') {
-    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write');
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]');
     process.exitCode = 1;
     return;
   }
 
+  const allowChanged = parseAllowChanged(flags);
+  if (allowChanged.invalid) {
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write [--allow-changed <ROADMAP.md,SPEC.md,config.json>]');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (allowChanged.files.length > 0) {
+    const drift = checkDrift(planningDir);
+    const changedFiles = drift.files.filter((file) => file.status !== 'unchanged').map((file) => file.file);
+    const unexpected = changedFiles.filter((file) => !allowChanged.files.includes(file));
+    if (unexpected.length > 0) {
+      output({
+        operation: 'session-fingerprint write',
+        changedFiles,
+        allowedChanged: allowChanged.files,
+        written: false,
+        reason: 'unexpected_planning_drift',
+        unexpected,
+      });
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   output({ operation: 'session-fingerprint write', fingerprint: writeFingerprint(planningDir) });
 }
 
+function parseAllowChanged(flags) {
+  const files = [];
+  for (let index = 0; index < flags.length; index += 1) {
+    if (flags[index] !== '--allow-changed') return { invalid: true, files: [] };
+    const value = flags[index + 1];
+    if (!value || value.startsWith('--')) return { invalid: true, files: [] };
+    files.push(...value.split(',').map((entry) => entry.trim()).filter(Boolean));
+    index += 1;
+  }
+  for (const file of files) {
+    if (!FINGERPRINT_SOURCES.includes(file)) return { invalid: true, files: [] };
+  }
+  return { invalid: false, files: [...new Set(files)] };
+}
+
 /**
  * Read the stored fingerprint from .planning/.state-fingerprint.json.
  * Returns null if the file does not exist or is unparseable.

package/bin/lib/ui-proof.mjs

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { isAbsolute, join, relative, resolve } from 'path';
+import { dirname, isAbsolute, join, relative, resolve } from 'path';
 import { output } from './cli-utils.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
 
@@ -10,6 +10,8 @@ const ARTIFACT_VISIBILITIES = Object.freeze(['local_only', 'repo_tracked', 'publ
 const RAW_ARTIFACT_TYPES = Object.freeze(['screenshot', 'trace', 'video', 'dom_snapshot', 'dom-snapshot', 'dom', 'report']);
 const PUBLIC_CLAIM_USES = Object.freeze(['public', 'publication', 'tracked', 'delivery', 'release']);
 const CLAIM_USES = Object.freeze([...PUBLIC_CLAIM_USES, 'local', 'local_only']);
+const FAILURE_CLASSIFICATIONS = Object.freeze(['product_bug', 'missing_infra', 'flaky_harness', 'ambiguous_spec']);
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9_.:-]*$/;
 const REQUIRED_BUNDLE_FIELDS = Object.freeze([
   'proof_bundle_version',
   'scope',
@@ -25,6 +27,19 @@ const REQUIRED_BUNDLE_FIELDS = Object.freeze([
   'claim_limits',
 ]);
 const REQUIRED_SCOPE_FIELDS = Object.freeze(['work_item', 'claim', 'requirement_ids', 'slot_ids']);
+const REQUIRED_SLOT_FIELDS = Object.freeze([
+  'slot_id',
+  'claim',
+  'route_state',
+  'required_evidence_kinds',
+  'minimum_observations',
+  'environment',
+  'viewport',
+  'expected_artifact_types',
+  'validation_command',
+  'manual_acceptance_required',
+  'claim_limit',
+]);
 const REQUIRED_ARTIFACT_FIELDS = Object.freeze(['visibility', 'retention', 'sensitivity', 'safe_to_publish']);
 const REQUIRED_OBSERVATION_FIELDS = Object.freeze(['observation', 'claim', 'route_state', 'evidence_kind', 'artifact_refs', 'privacy', 'result', 'claim_limit']);
 const REQUIRED_PRIVACY_FIELDS = Object.freeze(['data_classification', 'raw_artifacts_safe_to_publish', 'retention']);
@@ -72,12 +87,12 @@ function normalizeArray(value) {
 
 function artifactType(artifact) {
   const explicit = typeof artifact.type === 'string' ? artifact.type.toLowerCase() : '';
-  const artifactPath = typeof artifact.path === 'string' ? artifact.path.toLowerCase() : '';
-  if (/screenshot|\.png$|\.jpe?g$|\.webp$/.test(artifactPath)) return 'screenshot';
-  if (/trace|\.zip$/.test(artifactPath)) return 'trace';
-  if (/video|\.mp4$|\.webm$|\.mov$/.test(artifactPath)) return 'video';
-  if (/dom|\.html?$/.test(artifactPath)) return 'dom_snapshot';
-  if (/report/.test(artifactPath)) return 'report';
+  const artifactRef = artifactReference(artifact)?.toLowerCase() || '';
+  if (/screenshot|\.png$|\.jpe?g$|\.webp$/.test(artifactRef)) return 'screenshot';
+  if (/trace|\.zip$/.test(artifactRef)) return 'trace';
+  if (/video|\.mp4$|\.webm$|\.mov$/.test(artifactRef)) return 'video';
+  if (/dom|\.html?$/.test(artifactRef)) return 'dom_snapshot';
+  if (/report/.test(artifactRef)) return 'report';
   return explicit;
 }
 
@@ -172,6 +187,19 @@ function validateEvidenceKinds(bundle, errors) {
   }
 }
 
+function validateToolsUsed(bundle, errors) {
+  const tools = normalizeArray(bundle?.evidence_inputs?.tools_used);
+  if (tools.length === 0) {
+    addError(errors, 'missing_tools_used', 'evidence_inputs.tools_used', 'Missing UI proof tool provenance.', 'Record concise tool IDs such as browser, playwright, manual, or project-specific command IDs.');
+    return;
+  }
+  for (const [index, tool] of tools.entries()) {
+    if (!TOOL_ID_PATTERN.test(tool)) {
+      addError(errors, 'invalid_tool_id', `evidence_inputs.tools_used[${index}]`, `Invalid UI proof tool identifier: ${tool}`, 'Use a concise lowercase identifier without spaces, for example browser, playwright, manual, or gsdd-ui-proof-validate.');
+    }
+  }
+}
+
 function validateResult(bundle, errors) {
   if (!isPlainObject(bundle?.result)) return;
   if (!hasValue(bundle.result.claim_status)) {
@@ -181,6 +209,28 @@ function validateResult(bundle, errors) {
   }
 }
 
+function validateFailureClassification(bundle, errors) {
+  const statuses = [
+    bundle?.result?.claim_status,
+    ...Object.values(isPlainObject(bundle?.result?.comparison_status_by_slot) ? bundle.result.comparison_status_by_slot : {}),
+    ...normalizeArray(bundle?.observations).map((observation) => isPlainObject(observation) ? observation.result : null),
+    ...normalizeArray(bundle?.commands_or_manual_steps).map((step) => isPlainObject(step) ? step.result : null),
+  ].filter(Boolean);
+  const failedOrPartial = statuses.some((status) => status === 'failed' || status === 'partial');
+  const classifications = normalizeArray(bundle?.result?.failure_classification || bundle?.result?.failure_classifications);
+
+  if (failedOrPartial && classifications.length === 0) {
+    addError(errors, 'missing_failure_classification', 'result.failure_classification', 'Failed or partial UI proof must classify why it failed.', `Use one of: ${FAILURE_CLASSIFICATIONS.join(', ')}.`);
+    return;
+  }
+
+  for (const [index, classification] of classifications.entries()) {
+    if (!FAILURE_CLASSIFICATIONS.includes(classification)) {
+      addError(errors, 'invalid_failure_classification', `result.failure_classification[${index}]`, `Invalid UI proof failure classification: ${classification}`, `Use only: ${FAILURE_CLASSIFICATIONS.join(', ')}.`);
+    }
+  }
+}
+
 function validateComparisonStatuses(bundle, errors) {
   const statuses = bundle?.result?.comparison_status_by_slot;
   if (!isPlainObject(statuses)) {
@@ -202,6 +252,10 @@ function validateComparisonStatuses(bundle, errors) {
       addError(errors, 'invalid_comparison_status', `result.comparison_status_by_slot.${slot}`, `Invalid UI proof comparison status: ${status}`, `Use only: ${COMPARISON_STATUSES.join(', ')}.`);
     }
   }
+  const unsatisfiedStatuses = Object.values(statuses).filter((status) => !['satisfied', 'not_applicable'].includes(status));
+  if (bundle?.result?.claim_status === 'passed' && unsatisfiedStatuses.length > 0) {
+    addError(errors, 'inconsistent_claim_status', 'result.claim_status', 'UI proof claim_status cannot be passed when comparison statuses are unsatisfied.', 'Use partial, failed, waived, deferred, or not_applicable when any slot comparison is not satisfied.');
+  }
 }
 
 function validateClaimLimits(bundle, errors) {
@@ -234,7 +288,7 @@ function isSanitizedSensitivity(value) {
   return typeof value === 'string' && /(^|[_\s-])(sanitized|public_safe|public-safe)($|[_\s-])/.test(value.toLowerCase());
 }
 
-function validateArtifacts(bundle, errors, publicClaim) {
+function validateArtifacts(bundle, errors, publicClaim, options = {}) {
   const artifacts = normalizeArray(bundle?.artifacts);
   if (artifacts.length === 0) {
     addError(errors, 'missing_artifacts', 'artifacts', 'Missing UI proof artifacts list.', 'Record artifact metadata for each referenced proof artifact.');
@@ -254,6 +308,12 @@ function validateArtifacts(bundle, errors, publicClaim) {
     } else {
       validateArtifactReferenceSafety(ref, artifactPath, errors);
       artifactRefs.add(ref);
+      if (options.requireLocalArtifactExists && !/^https?:\/\//i.test(ref) && hasValue(options.workspaceRoot)) {
+        const artifactFile = resolve(options.workspaceRoot, ref);
+        if (!existsSync(artifactFile) || statSync(artifactFile).isDirectory()) {
+          addError(errors, 'missing_local_artifact', artifactPath, `UI proof artifact file does not exist: ${ref}`, 'Create the referenced artifact, correct the path, or narrow the proof claim.');
+        }
+      }
     }
     for (const field of REQUIRED_ARTIFACT_FIELDS) {
       requireField(artifact, field, artifactPath, errors);
@@ -277,6 +337,40 @@ function validateArtifacts(bundle, errors, publicClaim) {
   return artifactRefs;
 }
 
+export function validateUiProofSlots(slots) {
+  const errors = [];
+  const normalizedSlots = normalizeArray(slots);
+  if (normalizedSlots.length === 0) {
+    addError(errors, 'missing_planned_slots', 'ui_proof_slots', 'Planned UI proof input must include at least one slot.', 'Provide ui_proof_slots or no_ui_proof_rationale for non-UI work.');
+    return { valid: false, errors, warnings: [] };
+  }
+
+  for (const [index, slot] of normalizedSlots.entries()) {
+    const slotPath = `ui_proof_slots[${index}]`;
+    if (!isPlainObject(slot)) {
+      addError(errors, 'invalid_planned_slot', slotPath, 'Planned UI proof slot must be an object.', 'Record a scoped slot with claim, route_state, viewport, evidence, artifacts, validation, and claim limit.');
+      continue;
+    }
+    for (const field of REQUIRED_SLOT_FIELDS) requireField(slot, field, slotPath, errors);
+    for (const [kindIndex, kind] of normalizeArray(slot.required_evidence_kinds || slot.requiredEvidenceKinds).entries()) {
+      if (!EVIDENCE_KINDS.includes(kind)) {
+        addError(errors, 'unsupported_planned_evidence_kind', `${slotPath}.required_evidence_kinds[${kindIndex}]`, `Unsupported planned UI proof evidence kind: ${kind}`, `Use only: ${EVIDENCE_KINDS.join(', ')}.`);
+      }
+    }
+    if (hasValue(slot.manual_acceptance_required) && typeof slot.manual_acceptance_required !== 'boolean') {
+      addError(errors, 'invalid_manual_acceptance_required', `${slotPath}.manual_acceptance_required`, 'manual_acceptance_required must be a boolean.', 'Use true only when human judgment is required for this slot; otherwise use false.');
+    }
+    if (normalizeArray(slot.minimum_observations || slot.minimumObservations).length === 0) {
+      addError(errors, 'missing_minimum_observations', `${slotPath}.minimum_observations`, 'Planned UI proof slot must include minimum observations.', 'List the observations execution must prove for this slot.');
+    }
+    if (normalizeArray(slot.expected_artifact_types || slot.expectedArtifactTypes).length === 0) {
+      addError(errors, 'missing_expected_artifact_types', `${slotPath}.expected_artifact_types`, 'Planned UI proof slot must include expected artifact types.', 'List expected artifact types such as screenshot, trace, report, or dom_snapshot.');
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings: [] };
+}
+
 function validatePrivacy(bundle, errors, publicClaim) {
   validateObservationPrivacy(bundle.privacy, 'privacy', errors);
   if (publicClaim && bundle.privacy?.raw_artifacts_safe_to_publish !== true) {
@@ -305,6 +399,316 @@ function validateObservationArtifactRefs(bundle, artifactRefs, errors) {
   }
 }
 
+function stableString(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+function valuesMatch(planned, observed) {
+  if (!hasValue(planned)) return true;
+  if (!hasValue(observed)) return false;
+  return stableString(planned) === stableString(observed);
+}
+
+function slotId(slot, index) {
+  return slot?.slot_id || slot?.slotId || slot?.id || `ui-proof-slot-${index + 1}`;
+}
+
+function observationText(observation) {
+  if (typeof observation === 'string') return observation;
+  if (isPlainObject(observation) && typeof observation.observation === 'string') return observation.observation;
+  return '';
+}
+
+function includesObservation(observations, expected) {
+  const expectedText = typeof expected === 'string' ? expected.trim() : observationText(expected).trim();
+  if (!expectedText) return true;
+  return observations.some((observation) => observationText(observation).includes(expectedText));
+}
+
+function normalizeObservedBundle(entry) {
+  if (entry?.bundle) {
+    return {
+      bundle: entry.bundle,
+      validation: entry.validation || validateUiProofBundle(entry.bundle, entry.options || {}),
+      source: entry.source || entry.filePath || 'observed bundle',
+    };
+  }
+  return {
+    bundle: entry,
+    validation: validateUiProofBundle(entry),
+    source: 'observed bundle',
+  };
+}
+
+function compareSlotToBundle(slot, slotIdValue, observed) {
+  const issues = [];
+  const bundle = observed.bundle;
+  const observations = normalizeArray(bundle?.observations);
+  if (!observed.validation.valid) {
+    issues.push({
+      code: 'invalid_observed_bundle',
+      path: observed.source,
+      message: `Observed UI proof bundle for slot ${slotIdValue} failed metadata validation.`,
+      details: observed.validation.errors,
+    });
+  }
+
+  const bundleStatus = bundle?.result?.comparison_status_by_slot?.[slotIdValue];
+  if (bundle?.result?.claim_status !== 'passed') {
+    issues.push({
+      code: 'unsatisfied_observed_claim_status',
+      path: 'result.claim_status',
+      message: `Observed UI proof bundle claim status is ${bundle?.result?.claim_status || 'missing'} for slot ${slotIdValue}.`,
+    });
+  }
+  if (bundleStatus !== 'satisfied') {
+    issues.push({
+      code: 'unsatisfied_observed_comparison_status',
+      path: `result.comparison_status_by_slot.${slotIdValue}`,
+      message: `Observed UI proof bundle reports ${bundleStatus || 'missing'} for slot ${slotIdValue}.`,
+    });
+  }
+
+  const requiredKinds = normalizeArray(slot?.required_evidence_kinds || slot?.requiredEvidenceKinds);
+  const observedKinds = normalizeArray(bundle?.evidence_inputs?.kinds);
+  const missingKinds = requiredKinds.filter((kind) => !observedKinds.includes(kind));
+  if (missingKinds.length > 0) {
+    issues.push({
+      code: 'missing_required_evidence_kind',
+      path: 'evidence_inputs.kinds',
+      message: `Observed UI proof for slot ${slotIdValue} is missing required evidence kind(s): ${missingKinds.join(', ')}.`,
+    });
+  }
+  const missingNonHuman = missingKinds.filter((kind) => kind !== 'human');
+  if (missingNonHuman.length > 0 && observedKinds.includes('human')) {
+    issues.push({
+      code: 'human_evidence_cannot_bypass_required_non_human_evidence',
+      path: 'evidence_inputs.kinds',
+      message: `Human evidence cannot satisfy missing non-human UI proof evidence for slot ${slotIdValue}: ${missingNonHuman.join(', ')}.`,
+    });
+  }
+
+  if (!valuesMatch(slot?.route_state || slot?.routeState, bundle?.route_state)) {
+    issues.push({
+      code: 'route_state_mismatch',
+      path: 'route_state',
+      message: `Observed UI proof route/state does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  if (!valuesMatch(slot?.environment, bundle?.environment)) {
+    issues.push({
+      code: 'environment_mismatch',
+      path: 'environment',
+      message: `Observed UI proof environment does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  if (!valuesMatch(slot?.viewport, bundle?.viewport)) {
+    issues.push({
+      code: 'viewport_mismatch',
+      path: 'viewport',
+      message: `Observed UI proof viewport does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  const requirementId = slot?.requirement_id || slot?.requirementId;
+  if (hasValue(requirementId) && !normalizeArray(bundle?.scope?.requirement_ids).includes(requirementId)) {
+    issues.push({
+      code: 'requirement_mismatch',
+      path: 'scope.requirement_ids',
+      message: `Observed UI proof bundle does not declare planned requirement ${requirementId} for slot ${slotIdValue}.`,
+    });
+  }
+
+  if (hasValue(slot?.claim) && bundle?.scope?.claim !== slot.claim) {
+    issues.push({
+      code: 'claim_mismatch',
+      path: 'scope.claim',
+      message: `Observed UI proof bundle claim does not match planned slot ${slotIdValue}.`,
+    });
+  }
+
+  if (hasValue(slot?.claim) && !observations.some((observation) => observation?.claim === slot.claim)) {
+    issues.push({
+      code: 'observation_claim_mismatch',
+      path: 'observations[].claim',
+      message: `Observed UI proof observations do not support the exact planned claim for slot ${slotIdValue}.`,
+    });
+  }
+
+  const supportingObservations = observations
+    .map((observation, index) => ({ observation, index }))
+    .filter(({ observation }) => !hasValue(slot?.claim) || observation?.claim === slot.claim);
+
+  if (hasValue(slot?.route_state || slot?.routeState)) {
+    for (const { observation, index } of supportingObservations) {
+      if (!valuesMatch(slot?.route_state || slot?.routeState, observation?.route_state)) {
+        issues.push({
+          code: 'observation_route_state_mismatch',
+          path: `observations[${index}].route_state`,
+          message: `Observed UI proof observation route/state does not match planned slot ${slotIdValue}.`,
+        });
+      }
+    }
+  }
+
+  const passedSupportingKinds = new Set(
+    supportingObservations
+      .filter(({ observation }) => observation?.result === 'passed')
+      .map(({ observation }) => observation?.evidence_kind)
+      .filter(Boolean)
+  );
+  const missingSupportingKinds = requiredKinds.filter((kind) => !passedSupportingKinds.has(kind));
+  if (missingSupportingKinds.length > 0) {
+    issues.push({
+      code: 'missing_supporting_observation_evidence_kind',
+      path: 'observations[].evidence_kind',
+      message: `Observed UI proof for slot ${slotIdValue} lacks passed supporting observation(s) for required evidence kind(s): ${missingSupportingKinds.join(', ')}.`,
+    });
+  }
+
+  for (const [index, step] of normalizeArray(bundle?.commands_or_manual_steps).entries()) {
+    if (step?.result !== 'passed') {
+      issues.push({
+        code: 'unsatisfied_proof_step',
+        path: `commands_or_manual_steps[${index}].result`,
+        message: `Observed UI proof command/manual step is ${step?.result || 'missing'} for slot ${slotIdValue}.`,
+      });
+    }
+  }
+
+  const manualAcceptanceRequired = slot?.manual_acceptance_required === true || slot?.manualAcceptanceRequired === true;
+  if (manualAcceptanceRequired) {
+    if (!observedKinds.includes('human')) {
+      issues.push({
+        code: 'missing_manual_acceptance_evidence',
+        path: 'evidence_inputs.kinds',
+        message: `Observed UI proof for slot ${slotIdValue} is missing required human evidence for manual acceptance.`,
+      });
+    }
+    if (!passedSupportingKinds.has('human')) {
+      issues.push({
+        code: 'missing_manual_acceptance_observation',
+        path: 'observations[].evidence_kind',
+        message: `Observed UI proof for slot ${slotIdValue} lacks a passed human observation for manual acceptance.`,
+      });
+    }
+  }
+
+  for (const { observation, index } of supportingObservations) {
+    if (observation?.result !== 'passed') {
+      issues.push({
+        code: 'unsatisfied_observation_result',
+        path: `observations[${index}].result`,
+        message: `Observed UI proof observation is ${observation?.result || 'missing'} for slot ${slotIdValue}.`,
+      });
+    }
+  }
+
+  for (const expected of normalizeArray(slot?.minimum_observations || slot?.minimumObservations)) {
+    if (!includesObservation(supportingObservations.map(({ observation }) => observation), expected)) {
+      issues.push({
+        code: 'missing_minimum_observation',
+        path: 'observations',
+        message: `Observed UI proof for slot ${slotIdValue} is missing a planned minimum observation.`,
+      });
+    }
+  }
+
+  if (hasValue(slot?.claim_limit || slot?.claimLimit)) {
+    const claimLimit = slot.claim_limit || slot.claimLimit;
+    if (!normalizeArray(bundle?.claim_limits).includes(claimLimit)) {
+      issues.push({
+        code: 'missing_claim_limit',
+        path: 'claim_limits',
+        message: `Observed UI proof for slot ${slotIdValue} does not preserve the planned claim limit.`,
+      });
+    }
+  }
+
+  const expectedArtifactTypes = normalizeArray(slot?.expected_artifact_types || slot?.expectedArtifactTypes);
+  const observedArtifactTypes = new Set(normalizeArray(bundle?.artifacts).filter(isPlainObject).flatMap((artifact) => [
+    typeof artifact.type === 'string' ? artifact.type.toLowerCase() : '',
+    artifactType(artifact),
+  ]).filter(Boolean));
+  const missingArtifactTypes = expectedArtifactTypes.filter((type) => !observedArtifactTypes.has(type));
+  if (missingArtifactTypes.length > 0) {
+    issues.push({
+      code: 'missing_expected_artifact_type',
+      path: 'artifacts[].type',
+      message: `Observed UI proof for slot ${slotIdValue} is missing expected artifact type(s): ${missingArtifactTypes.join(', ')}.`,
+    });
+  }
+
+  const status = issues.length === 0 ? 'satisfied' : (bundleStatus === 'missing' ? 'missing' : 'partial');
+  return { status, issues, source: observed.source };
+}
+
+export function compareUiProofSlots(plannedSlots, observedBundles) {
+  const slots = normalizeArray(plannedSlots);
+  const slotValidation = validateUiProofSlots(slots);
+  const bundles = normalizeArray(observedBundles).map(normalizeObservedBundle);
+  const results = [];
+  const errors = [...slotValidation.errors];
+
+  for (const observed of bundles) {
+    if (!observed.validation.valid) {
+      errors.push({
+        code: 'invalid_observed_bundle',
+        path: observed.source,
+        message: `Observed UI proof bundle ${observed.source} failed metadata validation.`,
+        details: observed.validation.errors,
+      });
+    }
+  }
+
+  for (const [index, slot] of slots.entries()) {
+    const slotIdValue = slotId(slot, index);
+    const matchingBundles = bundles.filter((observed) => normalizeArray(observed.bundle?.scope?.slot_ids).includes(slotIdValue));
+    if (matchingBundles.length === 0) {
+      results.push({
+        slot_id: slotIdValue,
+        status: 'missing',
+        issues: [{
+          code: 'missing_observed_bundle',
+          path: 'scope.slot_ids',
+          message: `No observed UI proof bundle declares planned slot ${slotIdValue}.`,
+        }],
+      });
+      continue;
+    }
+
+    const candidates = matchingBundles.map((observed) => compareSlotToBundle(slot, slotIdValue, observed));
+    const satisfied = candidates.find((candidate) => candidate.status === 'satisfied');
+    if (satisfied) {
+      results.push({ slot_id: slotIdValue, status: 'satisfied', issues: [], source: satisfied.source });
+      continue;
+    }
+    const partial = candidates.find((candidate) => candidate.status === 'partial') || candidates[0];
+    results.push({ slot_id: slotIdValue, status: partial.status, issues: partial.issues, source: partial.source });
+  }
+
+  const statuses = results.map((result) => result.status);
+  const status = errors.length > 0
+    ? 'partial'
+    : statuses.length === 0
+    ? 'not_applicable'
+    : statuses.every((value) => value === 'satisfied')
+      ? 'satisfied'
+      : statuses.every((value) => value === 'missing')
+        ? 'missing'
+        : 'partial';
+
+  return { status, slots: results, errors };
+}
+
 export function validateUiProofBundle(bundle, options = {}) {
   const errors = [];
   const warnings = [];
@@ -319,23 +723,25 @@ export function validateUiProofBundle(bundle, options = {}) {
   const publicClaim = hasPublicClaim(bundle, options);
   validateClaimUses(bundle, options, errors);
   validateEvidenceKinds(bundle, errors);
+  validateToolsUsed(bundle, errors);
   validateCommandsOrManualSteps(bundle, errors);
   validateObservations(bundle, errors);
   validateResult(bundle, errors);
+  validateFailureClassification(bundle, errors);
   validateComparisonStatuses(bundle, errors);
   validateClaimLimits(bundle, errors);
   validatePrivacy(bundle, errors, publicClaim);
   validatePublicObservationPrivacy(bundle, errors, publicClaim);
-  const artifactRefs = validateArtifacts(bundle, errors, publicClaim);
+  const artifactRefs = validateArtifacts(bundle, errors, publicClaim, options);
   validateObservationArtifactRefs(bundle, artifactRefs, errors);
 
   return { valid: errors.length === 0, errors, warnings };
 }
 
-export function parseUiProofBundleContent(content, filePath = 'UI proof bundle') {
+function parseJsonOrFencedContent(content, filePath, label) {
   const trimmed = content.trim();
   if (!trimmed) {
-    return { bundle: null, errors: [{ code: 'empty_bundle_file', path: filePath, message: 'UI proof bundle file is empty.', fix: 'Write JSON UI proof metadata before validating.' }] };
+    return { value: null, errors: [{ code: 'empty_file', path: filePath, message: `${label} file is empty.`, fix: 'Write JSON metadata before validating.' }] };
   }
 
   const jsonCandidates = [trimmed];
@@ -344,15 +750,62 @@ export function parseUiProofBundleContent(content, filePath = 'UI proof bundle')
 
   for (const candidate of jsonCandidates) {
     try {
-      return { bundle: JSON.parse(candidate), errors: [] };
+      return { value: JSON.parse(candidate), errors: [] };
     } catch {
       // Try next candidate; final error is reported below.
     }
   }
 
   return {
-    bundle: null,
-    errors: [{ code: 'unparseable_bundle', path: filePath, message: 'UI proof bundle metadata is not valid JSON.', fix: 'Use a .json proof bundle or a markdown fenced JSON block; no YAML parser dependency is installed.' }],
+    value: null,
+    errors: [{ code: 'unparseable_json', path: filePath, message: `${label} metadata is not valid JSON.`, fix: 'Use a .json file or a markdown fenced JSON block; no YAML parser dependency is installed.' }],
+  };
+}
+
+export function parseUiProofBundleContent(content, filePath = 'UI proof bundle') {
+  const parsed = parseJsonOrFencedContent(content, filePath, 'UI proof bundle');
+  return { bundle: parsed.value, errors: parsed.errors.map((error) => ({
+    ...error,
+    code: error.code === 'empty_file' ? 'empty_bundle_file' : error.code === 'unparseable_json' ? 'unparseable_bundle' : error.code,
+    message: error.code === 'empty_file'
+      ? 'UI proof bundle file is empty.'
+      : error.code === 'unparseable_json'
+        ? 'UI proof bundle metadata is not valid JSON.'
+        : error.message,
+    fix: error.code === 'empty_file'
+      ? 'Write JSON UI proof metadata before validating.'
+      : error.fix,
+  })) };
+}
+
+export function parseUiProofSlotsContent(content, filePath = 'UI proof slots') {
+  const parsed = parseJsonOrFencedContent(content, filePath, 'UI proof slots');
+  if (parsed.errors.length > 0) return { slots: [], errors: parsed.errors };
+
+  const value = parsed.value;
+  const slots = Array.isArray(value)
+    ? value
+    : normalizeArray(value?.ui_proof_slots || value?.uiProofSlots || value?.planned_slots || value?.plannedSlots);
+
+  if (slots.length === 0) {
+    return {
+      slots: [],
+      errors: [{
+        code: 'missing_planned_slots',
+        path: filePath,
+        message: 'Planned UI proof input must be an array or contain ui_proof_slots.',
+        fix: 'Provide JSON with an array of planned slots or an object with ui_proof_slots.',
+      }],
+    };
+  }
+
+  const validation = validateUiProofSlots(slots);
+  return {
+    slots,
+    errors: validation.errors.map((error) => ({
+      ...error,
+      path: error.path === 'ui_proof_slots' ? filePath : `${filePath}.${error.path}`,
+    })),
   };
 }
 
@@ -428,12 +881,61 @@ function cmdValidate(cwd, args) {
   const parsed = readUiProofBundleFile(target);
   const validation = parsed.errors.length > 0
     ? { valid: false, errors: parsed.errors, warnings: [] }
-    : validateUiProofBundle(parsed.bundle, { claimUses: parseClaimUse(flags) });
+    : validateUiProofBundle(parsed.bundle, {
+      claimUses: parseClaimUse(flags),
+      requireLocalArtifactExists: true,
+      workspaceRoot: cwd,
+      bundleDir: dirname(target),
+    });
 
   output({ operation: 'ui-proof validate', target: targetArg, valid: validation.valid, errors: validation.errors, warnings: validation.warnings });
   if (!validation.valid) process.exitCode = 1;
 }
 
+function cmdCompare(cwd, args) {
+  const [plannedArg, ...observedArgs] = args;
+  if (!plannedArg) fail('Usage: gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]');
+
+  const plannedPath = resolveWorkspacePath(cwd, plannedArg);
+  if (!existsSync(plannedPath) || statSync(plannedPath).isDirectory()) fail(`Planned UI proof slots file does not exist: ${plannedArg}`);
+
+  const planned = parseUiProofSlotsContent(readFileSync(plannedPath, 'utf-8'), plannedArg);
+  const observedBundles = [];
+  const observedTargets = [];
+  const observedErrors = [];
+
+  for (const observedArg of observedArgs) {
+    const observedPath = resolveWorkspacePath(cwd, observedArg);
+    if (!existsSync(observedPath) || statSync(observedPath).isDirectory()) fail(`Observed UI proof bundle file does not exist: ${observedArg}`);
+    const parsed = readUiProofBundleFile(observedPath);
+    if (parsed.errors.length > 0) {
+      observedErrors.push(...parsed.errors.map((error) => ({ ...error, path: observedArg })));
+      observedBundles.push({
+        bundle: {},
+        validation: { valid: false, errors: parsed.errors, warnings: [] },
+        source: observedArg,
+      });
+    } else {
+      observedBundles.push({ bundle: parsed.bundle, source: observedArg });
+    }
+    observedTargets.push(observedArg);
+  }
+
+  const comparison = planned.errors.length > 0
+    ? { status: 'partial', slots: [], errors: planned.errors }
+    : compareUiProofSlots(planned.slots, observedBundles);
+
+  output({
+    operation: 'ui-proof compare',
+    planned: plannedArg,
+    observed: observedTargets,
+    status: comparison.status,
+    slots: comparison.slots,
+    errors: [...(comparison.errors || []), ...observedErrors],
+  });
+  if (!['satisfied', 'not_applicable'].includes(comparison.status)) process.exitCode = 1;
+}
+
 export function cmdUiProof(...args) {
   const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(args);
   if (invalid) {
@@ -447,8 +949,11 @@ export function cmdUiProof(...args) {
       case 'validate':
         cmdValidate(workspaceRoot, rest);
         return;
+      case 'compare':
+        cmdCompare(workspaceRoot, rest);
+        return;
       default:
-        fail('Usage: gsdd ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]');
+        fail('Usage: gsdd ui-proof <validate|compare> ...');
     }
   } catch (error) {
     if (error instanceof UiProofError) {

package/distilled/DESIGN.md

@@ -2817,30 +2817,36 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 
 ## D62 - Repo-Native UI Proof Contract
 
-**Decision (2026-04-28):** UI-sensitive work should carry a compact planned proof-slot contract and, when executed, an observed UI proof bundle that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`.
+**Decision (2026-04-28; revised 2026-05-08):** UI-sensitive work should carry a compact planned proof-slot contract and, when executed, an observed UI proof bundle that references artifacts by path or link while preserving the existing closure evidence kinds: `code`, `test`, `runtime`, `delivery`, and `human`. For live rendered UI proof, `agent-browser` is the default runtime evidence path for consumers, while existing Playwright tests remain the canonical repeatable browser-regression path when present. The deterministic `ui-proof` validator remains provider-agnostic structural validation, but it now validates planned slot specificity, concise tool provenance, local artifact path existence when validating from files, raw-artifact safety for paths and URLs, and failed/partial proof classification so the workflow cannot degrade back into unstructured "looks good" review.
 
 **Context:**
 - UI proof targets the recurring failure mode where agents claim a UI works or looks good without rendered proof, matched observations, or explicit human judgment.
 - The contract defines proof slots, proof bundles, comparison statuses, fail-closed agent guardrails, deterministic metadata validation, privacy metadata, and health visibility without adding a browser-provider framework.
 - GSD's archived planner, executor, and verifier roles preserve strong lifecycle discipline, but they do not provide this UI-specific planned-vs-observed proof model. GSDD keeps the lifecycle leverage and adds a repo-native UI proof substrate without adding a browser-provider framework.
+- OneShot's QC guidance and Vercel's `agent-browser` skill converge on an interactive browser loop for snapshots, ref-based interaction, screenshots, and network/console-adjacent inspection. GSDD adapts that as a default workflow instruction, not as a hard validator dependency.
 
 **Decision:**
 - Planning must classify UI-sensitive work and require either `ui_proof_slots` or an explicit `no_ui_proof_rationale`.
-- Planned slots record claim, route/state, required evidence kinds, minimum observations, environment/viewport, manual-acceptance requirement, claim limit, and requirement IDs.
+- Planned slots record claim, route/state, required evidence kinds, minimum observations, expected artifact types, runnable validation command, environment/viewport, manual-acceptance requirement, claim limit, and requirement IDs.
 - Observed proof bundles record claim, requirement/slot IDs, route/state, environment, viewport, evidence inputs, commands/manual steps, observations, artifacts, privacy metadata, result, and claim limits.
+- Planned slots must be tight enough for the plan checker to reject vague proof: specific route/state, viewport rationale or narrowed claim limit, minimum observations, expected artifact types, runnable validation, and matchability back to the exact UI claim.
+- The planner chooses viewport coverage, but responsive or layout-sensitive claims require desktop/mobile or equivalent state coverage unless the claim is explicitly narrowed.
+- Execution defaults to `agent-browser` for live UI runtime proof: open the route/state, capture interactive snapshots/refs where relevant, exercise the changed flow, capture screenshots for planned viewport(s), and record relevant console/network observations.
+- Existing Playwright tests or package scripts remain the canonical repeatable browser-regression evidence when present. Playwright scripting is reserved for checks `agent-browser` cannot cover cleanly, such as JS-disabled behavior, structured console listeners, or multi-context testing.
 - Verification compares planned slots to observed bundles using `satisfied`, `partial`, `missing`, `waived`, `deferred`, and `not_applicable`; waiver and deferral are not proof.
 - UI correctness claims fail closed unless rendered proof is matched exactly to claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit, or an explicit waiver/deferment narrows the claim.
 - Human acceptance may close a narrowed claim and record proof debt, but it must not convert missing or mismatched non-human evidence into `satisfied` proof.
 - Screenshots, traces, videos, reports, accessibility scans, Gherkin, and visual diffs are artifact types or activities mapped onto the five existing evidence kinds, not new evidence kinds.
 - Source annotations, AST/cAST findings, semantic search hits, comments, and Semble-like retrieval may discover proof obligations, but they are discovery hints only and do not satisfy proof slots.
 - Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver, and human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence.
-- Deterministic metadata enforcement keeps the evidence and comparison-status vocabularies unchanged: artifact entries require `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to `local_only` plus `safe_to_publish: false`; `bin/lib/ui-proof.mjs` validates required bundle/observation fields, structured command/manual-step entries, fixed evidence kinds, claim/result statuses, comparison statuses, claim limits, privacy metadata, safe artifact references, and public/tracked/delivery proof claims backed by local-only, unsafe, unsanitized, or privacy-contradictory artifacts.
-- `gsdd health` reports invalid known UI proof bundles as E10 using the same validator, staying read-only and metadata-only.
+- Deterministic validation keeps the evidence and comparison-status vocabularies unchanged: planned slots require specific claim, route/state, evidence, expected artifacts, validation, viewport, and claim-limit fields; artifact entries require `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to `local_only` plus `safe_to_publish: false`; `bin/lib/ui-proof.mjs` validates required bundle/observation fields, structured command/manual-step entries, fixed evidence kinds, concise `tools_used` IDs, claim/result statuses, comparison statuses, failure classification for failed/partial proof, claim limits, privacy metadata, safe artifact references, local artifact path existence when validating file-backed bundles, and public/tracked/delivery proof claims backed by local-only, unsafe, unsanitized, or privacy-contradictory artifacts.
+- `gsdd health` reports invalid known UI proof bundles as E10 using the same validator, staying read-only and avoiding raw artifact content inspection.
+- Failed UI proof is reported through existing GSDD gap/proof-debt language. Product behavior defects, missing or blocked infrastructure, flaky harnesses, and ambiguous specs explain causes, but they do not add new evidence kinds, result statuses, or comparison statuses.
 
 **Leverage:**
-- Lost: UI-sensitive work now carries a small proof-contract burden, and invalid proof metadata can degrade/break health before agents can claim rendered UI outcomes.
-- Kept: repo-native markdown artifacts, optional project tooling, fixed closure evidence kinds, generated-surface freshness, and the plan/execute/verify separation.
-- Gained: exact claim-to-proof traceability, strict comparison statuses, privacy and claim-limit metadata, fail-closed overclaim guardrails, deterministic metadata validation, and health-visible protection against unsafe public proof claims.
+- Lost: UI-sensitive work now carries a small proof-contract burden, and default live proof guidance adds slightly more specificity for planners/checkers to enforce.
+- Kept: repo-native markdown artifacts, optional project tooling, fixed closure evidence kinds, generated-surface freshness, the plan/execute/verify separation, and provider-agnostic deterministic metadata validation.
+- Gained: exact claim-to-proof traceability, strict comparison statuses, privacy and claim-limit metadata, fail-closed overclaim guardrails, deterministic metadata validation, a concrete live browser evidence path, and health-visible protection against unsafe public proof claims.
 
 **Evidence:**
 - `distilled/templates/ui-proof.md`
@@ -2849,11 +2855,22 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 - `bin/lib/templates.mjs`, `bin/lib/ui-proof.mjs`, `bin/lib/health.mjs`, `bin/lib/rendering.mjs`
 - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs`
 - GSD comparison: the upstream planner, executor, and verifier role patterns preserve lifecycle rigor, but they do not define UI proof slots or planned-vs-observed UI proof bundles.
+- OneShot QC source: `https://github.com/oneshot-repo/OneShot/tree/main/skills`
+- Vercel `agent-browser` docs: `https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md` and `https://agent-browser.dev/snapshots`
+- Playwright docs: `https://playwright.dev/docs/trace-viewer`, `https://playwright.dev/docs/next/screenshots`, and `https://playwright.dev/mcp/tools/tracing`
+- Chrome DevTools for agents/MCP docs: `https://developer.chrome.com/docs/devtools/agents` and `https://developer.chrome.com/blog/chrome-devtools-mcp?hl=en`
+- Harness and UI-agent pitfall sources: `https://www.anthropic.com/engineering/harness-design-long-running-apps`, `https://www.huuhka.net/browser-verification-for-coding-agents-chrome-devtools-mcp-vs-agent-browser/`, `https://www.developersdigest.tech/blog/long-running-agents-need-harnesses`, `https://codemyspec.com/blog/agentic-qa-verification`, `https://dev.to/ratikkoka/your-ui-is-invisible-to-ai-agents-heres-how-to-fix-it-1ib3`, `https://dev.to/louaiboumediene/the-ai-harness-why-your-ai-coding-agent-is-only-as-smart-as-the-repo-you-put-it-in-cml`, and `https://tessl.io/blog/webmcp-making-web-apps-faster-and-cheaper-for-ai-agents/`
+- OpenSpec docs: `https://openspec.dev/`
+- LeanSpec docs: `https://www.lean-spec.dev/docs/guide/first-principles`
+- OpenAI Codex docs: `https://help.openai.com/en/articles/11369540-codex-in-chatgpt`
+- Anthropic Agent Skills docs: `https://docs.claude.com/en/docs/agents-and-tools/agent-skills`
+- GitHub Copilot customization docs: `https://docs.github.com/en/copilot/concepts/prompting/response-customization`
 
 **Consequences:**
 - Future UI-related phases must not add new evidence kinds by treating artifact types as proof categories.
 - Future dogfood or runtime validation must not upgrade artifact counts or human waivers into proof.
 - Generated runtime surfaces and local templates must stay freshness-checkable through `gsdd update --templates` and health diagnostics.
+- Future provider/tooling work must not make `agent-browser` a required validator field without a separate product decision; the current contract makes it the default workflow path, not a schema lock.
 
 ---
 

package/distilled/EVIDENCE-INDEX.md

@@ -491,6 +491,19 @@
 - `agents/planner.md`, `agents/executor.md`, `agents/verifier.md`, `distilled/templates/delegates/plan-checker.md`
 - `bin/lib/templates.mjs`, `bin/lib/ui-proof.mjs`, `bin/lib/health.mjs`, `bin/lib/rendering.mjs`
 - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.health.test.cjs`, `tests/gsdd.init.test.cjs`
+- OneShot QC/browser policy: https://github.com/oneshot-repo/OneShot/tree/main/skills
+- Vercel agent-browser docs: https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md, https://agent-browser.dev/snapshots
+- Playwright browser proof docs: https://playwright.dev/docs/trace-viewer, https://playwright.dev/docs/next/screenshots, https://playwright.dev/mcp/tools/tracing
+- Chrome DevTools agent/browser docs: https://developer.chrome.com/docs/devtools/agents, https://developer.chrome.com/blog/chrome-devtools-mcp?hl=en
+- Harness engineering source: https://www.anthropic.com/engineering/harness-design-long-running-apps
+- UI-agent browser verification source: https://www.huuhka.net/browser-verification-for-coding-agents-chrome-devtools-mcp-vs-agent-browser/
+- Agent harness discipline source: https://www.developersdigest.tech/blog/long-running-agents-need-harnesses
+- Agentic QA verification-gap source: https://codemyspec.com/blog/agentic-qa-verification
+- Agent-hostile UI semantics source: https://dev.to/ratikkoka/your-ui-is-invisible-to-ai-agents-heres-how-to-fix-it-1ib3
+- Browser-harness efficiency source: https://dev.to/louaiboumediene/the-ai-harness-why-your-ai-coding-agent-is-only-as-smart-as-the-repo-you-put-it-in-cml
+- Dynamic-UI harness brittleness source: https://tessl.io/blog/webmcp-making-web-apps-faster-and-cheaper-for-ai-agents/
+- Long-term pitfalls carried forward: do not accept screenshot-free "looks good" claims, weak planned slots, unverified artifact paths, stale interactive refs after page mutation, partial/failed proof without failure classification, raw artifact publication without privacy metadata, browser contention in parallel checks, or semantic/selector-poor UI that forces fragile coordinate inspection.
+- Supporting spec/runtime docs: https://openspec.dev/, https://www.lean-spec.dev/docs/guide/first-principles, https://help.openai.com/en/articles/11369540-codex-in-chatgpt, https://docs.claude.com/en/docs/agents-and-tools/agent-skills, https://docs.github.com/en/copilot/concepts/prompting/response-customization
 
 ---
 

package/distilled/templates/delegates/plan-checker.md

@@ -35,6 +35,7 @@ Verify these dimensions:
 - `escalation_integrity`: tasks include checkpoints or escalation when evidence, permissions, user decisions, or risky ambiguity are required.
 - `closure_honesty`: the plan's done criteria and evidence limits support only claims that execution can actually prove.
 - `closure_honesty`: for UI proof, reject agent-only `looks good` closure, artifact-count proof, unsupported evidence kinds, and human acceptance that converts missing/mismatched non-human evidence into `satisfied` proof. Waiver, deferment, proof debt, or narrowed-claim language is acceptable only when the stronger UI claim is not treated as proven.
+- `closure_honesty`: for UI proof planning, reject weak slots that omit a specific route/state, viewport rationale or narrowed viewport claim limit, minimum observations, expected artifact types, runnable validation, or a way to compare observed proof back to the planned claim. Treat under-specified viewport coverage as a blocker for responsive or layout-sensitive claims. `agent-browser` is the default live runtime evidence path; do not block a slot solely for using another project-native browser path, but require the plan to explain the `agent-browser` availability constraint and fallback choice.
 - `closure_honesty`: for UI proof privacy, require artifact `visibility`, `retention`, `sensitivity`, and `safe_to_publish`, require `gsdd ui-proof validate` or `gsdd health` when bundle metadata exists, and reject public/tracked/delivery/publication proof claims backed by local-only or `safe_to_publish: false` artifacts.
 - `high_leverage_review`: high-leverage surfaces have a second-pass review or equivalent contradiction/staleness check before completion.
 - `approach_alignment`: when APPROACH.md is provided, verify that plan tasks implement the chosen approaches from the user's decisions. Check:

package/distilled/templates/ui-proof.md

@@ -4,6 +4,10 @@ Use this template when work affects rendered UI or when a plan defines `ui_proof
 
 UI proof uses the existing closure evidence kinds only: `code`, `test`, `runtime`, `delivery`, and `human`. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities that map onto those evidence kinds. They are not new evidence kinds.
 
+For live rendered UI evidence, default to `agent-browser`: open the route, capture an interactive snapshot/refs when interaction is part of the claim, exercise the changed flow, capture screenshots for the planned viewport(s), and record console/network observations when they affect the claim. If the repo already has Playwright tests or a package script wrapping them, those remain the canonical repeatable regression path; use them as `test` evidence and use `agent-browser` for complementary live runtime proof. Do not introduce new Playwright, Cypress, Storybook, CI, browser MCP, or visual-regression infrastructure just to satisfy this template. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled behavior, structured console listeners, or multi-context testing.
+
+Tool availability is part of the proof record. In runtimes where `agent-browser` is not available, first state that availability constraint, then use the closest project-native interactive browser path and record the fallback in `evidence_inputs.tools_used`, `commands_or_manual_steps`, and `claim_limits`. A fallback can support a narrowed local runtime claim, but it must not silently pretend that the default `agent-browser` path ran.
+
 ## Planned Proof Slots
 
 Every UI-sensitive plan needs either at least one slot under `ui_proof_slots` or an explicit `no_ui_proof_rationale` explaining why no rendered UI proof is required.
@@ -19,13 +23,15 @@ ui_proof_slots:
     minimum_observations:
       - "Changed control is visible and usable in the stated state."
       - "Expected interaction completes without console/runtime error."
+    expected_artifact_types: [screenshot, report]
+    validation_command: "gsdd ui-proof compare {work_item_dir}/ui-proof-slots.json {work_item_dir}/UI-PROOF.md"
     environment:
       app_url: "http://localhost:3000"
       data_state: "synthetic or seeded data"
     viewport:
       width: 1280
       height: 720
-      notes: "Use project default unless responsive behavior is part of the claim."
+      notes: "State why this viewport is enough for the claim, or add separate slots/observations for mobile, desktop, or responsive states."
     manual_acceptance_required: false
     claim_limit: "Does not prove cross-browser layout, full accessibility conformance, production delivery, or unrelated UI states."
 no_ui_proof_rationale: null
@@ -34,6 +40,8 @@ no_ui_proof_rationale: null
 Slot rules:
 - Keep each slot tied to one exact UI claim.
 - Use the lightest proof that can catch a botched rendered experience for that claim.
+- Specify the route/state, viewport choice, minimum observations, expected artifact types, and runnable validation path tightly enough that a checker can reject vague proof before execution.
+- The planner chooses the viewport set, but the slot must explain the choice. Include desktop and mobile proof when the claim covers responsive layout or when the changed surface is likely to behave differently across those sizes; otherwise narrow the claim limit.
 - Source annotations, AST/cAST findings, semantic search hits, comments, and Semble-like retrieval may help discover proof obligations. They are discovery hints only; they do not satisfy proof slots.
 - Do not add Playwright, Cypress, Storybook, Cucumber, CI, browser MCP, or visual-regression tooling by default.
 - Human approval is required for visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication decisions.
@@ -43,6 +51,8 @@ Slot rules:
 
 Create or update this bundle during execution or verification when planned UI proof slots exist. JSON is the canonical machine-readable proof bundle format. Markdown proof files must include fenced JSON for deterministic validation.
 
+Replace placeholders such as `{work_item_dir}` with the current phase, quick-task, or brownfield-change directory before running commands or validating the bundle.
+
 ```json
 {
   "proof_bundle_version": 1,
@@ -58,7 +68,7 @@ Create or update this bundle during execution or verification when planned UI pr
   },
   "environment": {
     "app_url": "http://localhost:3000",
-    "browser": "project default or manual browser",
+    "browser": "agent-browser default; record fallback when unavailable",
     "browser_version": "record if known",
     "os": "record if relevant",
     "data_state": "synthetic or seeded data"
@@ -70,7 +80,7 @@ Create or update this bundle during execution or verification when planned UI pr
   },
   "evidence_inputs": {
     "kinds": ["test", "runtime"],
-    "tools_used": ["manual"]
+    "tools_used": ["playwright", "agent-browser"]
   },
   "commands_or_manual_steps": [
     {
@@ -80,7 +90,12 @@ Create or update this bundle during execution or verification when planned UI pr
       "attempts": 1
     },
     {
-      "manual_step": "Open /example as synthetic user and complete the changed interaction.",
+      "command": "agent-browser open http://localhost:3000/example && agent-browser snapshot -i && agent-browser screenshot {work_item_dir}/artifacts/example-1280.png --full",
+      "result": "passed",
+      "attempts": 1
+    },
+    {
+      "manual_step": "Using agent-browser refs, complete the changed interaction as a synthetic user and check for visible breakage or relevant console/network failures.",
       "result": "passed"
     }
   ],
@@ -93,7 +108,7 @@ Create or update this bundle during execution or verification when planned UI pr
         "state": "role, data state, feature flag, loading/error/empty state, or component story"
       },
       "evidence_kind": "runtime",
-      "artifact_refs": ["test-results/changed-flow-report/index.html"],
+      "artifact_refs": ["test-results/changed-flow-report/index.html", "{work_item_dir}/artifacts/example-1280.png"],
       "privacy": {
         "data_classification": "synthetic",
         "raw_artifacts_safe_to_publish": false,
@@ -112,6 +127,15 @@ Create or update this bundle during execution or verification when planned UI pr
       "sensitivity": "possible",
       "safe_to_publish": false,
       "notes": "Local report only; not public proof."
+    },
+    {
+      "path": "{work_item_dir}/artifacts/example-1280.png",
+      "type": "screenshot",
+      "visibility": "local_only",
+      "retention": "temporary_review",
+      "sensitivity": "possible",
+      "safe_to_publish": false,
+      "notes": "Local screenshot only; not public proof unless sanitized and reclassified."
     }
   ],
   "privacy": {
@@ -129,7 +153,8 @@ Create or update this bundle during execution or verification when planned UI pr
     "claim_status": "passed",
     "comparison_status_by_slot": {
       "ui-01": "satisfied"
-    }
+    },
+    "failure_classification": null
   },
   "claim_limits": [
     "Does not prove Safari/WebKit behavior.",
@@ -149,10 +174,11 @@ Bundle rules:
 - Local-only or `safe_to_publish: false` artifacts can support local review only; they must not back tracked, public, delivery, release, or publication proof claims.
 - Human acceptance may close a narrowed claim only by recording waiver, deferment, or proof debt; it must not upgrade missing or mismatched non-human proof to `satisfied`.
 - Quick-mode UI proof should use deterministic synthetic IDs such as `quick-001` and `quick-001-ui-01` when roadmap requirement IDs do not exist.
+- Classify failed UI proof using existing GSDD gap/proof-debt language: `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. Do not add new result statuses or evidence kinds for those causes.
 
 ## Deterministic Validation
 
-Use `gsdd ui-proof validate <path>` on JSON proof-bundle metadata or markdown fenced JSON before relying on a bundle for closure; add `--claim <public|publication|tracked|delivery|release>` only when validating that stronger proof use. Required observed-bundle top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`. The validator checks required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, `result.claim_status`, observation `result`, comparison statuses, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, and explicit public/tracked/delivery proof claims that rely on local-only, unsafe, unsanitized, or privacy-contradictory artifacts. `claim_status`, observation `result`, and command/manual-step `result` use `passed`, `failed`, `partial`, `waived`, `deferred`, or `not_applicable`. It is metadata-only and does not inspect raw screenshot, trace, video, DOM, or report contents.
+Use `gsdd ui-proof validate <path>` on JSON proof-bundle metadata or markdown fenced JSON before relying on a bundle for closure; add `--claim <public|publication|tracked|delivery|release>` only when validating that stronger proof use. Use `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when verifying planned proof slots against observed bundles through the deterministic product-facing path. Required planned-slot fields are `slot_id`, `claim`, `route_state`, `required_evidence_kinds`, `minimum_observations`, `expected_artifact_types`, `validation_command`, `environment`, `viewport`, `manual_acceptance_required`, and `claim_limit`. Required observed-bundle top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`. The validator checks planned-slot specificity, required bundle and observation fields, structured command/manual-step entries, fixed evidence kinds, concise `tools_used` IDs, `result.claim_status`, observation `result`, comparison statuses, failure classification for failed/partial proof, non-empty claim limits, locked artifact and observation privacy fields, observation-to-artifact references, workspace-relative/http(s) artifact references, existing local artifact paths when validating from files, and explicit public/tracked/delivery proof claims that rely on local-only, unsafe, unsanitized, or privacy-contradictory artifacts. `claim_status`, observation `result`, and command/manual-step `result` use `passed`, `failed`, `partial`, `waived`, `deferred`, or `not_applicable`; failed/partial proof uses `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. It does not inspect raw screenshot, trace, video, DOM, or report contents and does not require any specific browser provider such as `agent-browser`.
 
 ## Comparison Statuses
 

package/distilled/workflows/execute.md

@@ -166,8 +166,9 @@ Before reporting a task complete:
 
 ### UI Proof Execution
 If the plan defines non-empty `ui_proof_slots`, create or update the observed UI proof bundle before claiming completion; required top-level fields are `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
-Use existing UI tooling when available and cheap; manual/browser proof is acceptable when it records route/state, steps, observations, artifact references, and claim limits. Do not install Playwright, Cypress, Cucumber, Storybook, browser MCP, CI, or visual-regression tooling by default. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes map onto existing evidence kinds, not new evidence kinds; reference raw artifacts by path/link instead of storing them inline.
+Use `agent-browser` as the default live UI proof path. Record the planned route/state open, interactive snapshots/refs when interaction is part of the claim, changed-flow interaction, screenshots for planned viewport(s), and relevant console/network observations. If `agent-browser` is unavailable, record the availability constraint and the closest project-native interactive browser fallback in the proof bundle instead of silently treating the fallback as the default path. If the repo already has Playwright tests or a package script wrapping them, run the relevant targeted test as canonical repeatable regression evidence; keep `agent-browser` as complementary runtime proof. Use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification. Do not install Playwright, Cypress, Cucumber, Storybook, browser MCP, CI, or visual-regression tooling by default. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes map onto existing evidence kinds, not new evidence kinds; reference raw artifacts by path/link instead of storing them inline.
 Each artifact entry must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to `local_only` and `safe_to_publish: false` unless explicitly sanitized. Use `gsdd ui-proof validate <path>` when bundle metadata exists, adding `--claim <...>` only when relying on the bundle for public, tracked, delivery, release, or publication proof. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication decisions require human evidence or explicit waiver; artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. If evidence does not match the slot claim, route/state, observation, artifact path/manual step, privacy metadata, result, and claim limit, record proof debt, waiver, deferment, or reduced claim language rather than `satisfied` proof.
+Classify failed UI proof using existing gap/proof-debt language: `product_bug`, `missing_infra`, `flaky_harness`, or `ambiguous_spec`. Do not add new evidence kinds or result statuses for those causes.
 
 ### Git Guidance
 

package/distilled/workflows/plan-milestone-gaps.md

@@ -15,6 +15,18 @@ If no audit file exists: stop and direct the user to run `/gsdd-audit-milestone`
 If audit status is `passed`: stop and direct the user to run `/gsdd-complete-milestone` instead.
 </prerequisites>
 
+<repo_root_helper_contract>
+All `node .planning/bin/gsdd.mjs ...` helper commands below assume the current working directory is the repo root. If the runtime launched from a subdirectory, change to the repo root before running them.
+</repo_root_helper_contract>
+
+<lifecycle_preflight>
+Before writing ROADMAP gap-closure phases or phase directories, run:
+
+- `node .planning/bin/gsdd.mjs lifecycle-preflight plan-milestone-gaps`
+
+If the preflight result is `blocked`, STOP and report the blocker. This workflow intentionally mutates planning truth, so it must not proceed through pre-existing planning-state drift.
+</lifecycle_preflight>
+
 <load_context>
 Before starting, read these files:
 
@@ -144,6 +156,14 @@ Create a directory for each gap closure phase:
 
 No files inside — `/gsdd-plan` populates them.
 
+## 8. Rebaseline Planning Fingerprint
+
+After confirming the ROADMAP update and phase directories exist, run:
+
+- `node .planning/bin/gsdd.mjs session-fingerprint write --allow-changed ROADMAP.md`
+
+This records the user-confirmed ROADMAP mutation so the recommended `/gsdd-plan [N]` handoff does not immediately block on expected `planning_state_drift`. The `--allow-changed ROADMAP.md` guard must fail if `SPEC.md` or `config.json` also drifted after preflight; stop and reconcile that unexpected drift instead of rebaselining it. Do not run this if the ROADMAP write failed or the phase directories are missing.
+
 </process>
 
 <success_criteria>
@@ -155,6 +175,7 @@ No files inside — `/gsdd-plan` populates them.
 - [ ] User confirmed gap closure plan before ROADMAP.md was updated
 - [ ] ROADMAP.md updated with new gap closure phases
 - [ ] Phase directories created
+- [ ] `session-fingerprint write` ran after the reviewed ROADMAP update so `/gsdd-plan [N]` is not stranded by expected planning drift
 </success_criteria>
 
 **MANDATORY: `.planning/ROADMAP.md` must be updated on disk before this workflow is complete. If the write fails, STOP and report the failure. Without the updated ROADMAP, the phase cycle cannot begin.**

package/distilled/workflows/plan.md

@@ -136,8 +136,9 @@ If any of these are missing or contradictory, STOP. Report the exact missing con
 </phase_contract_gate>
 
 <ui_proof_planning>
-For UI-sensitive work, include compact `ui_proof_slots` with `slot_id`, optional `requirement_id`, `claim`, `route_state`, fixed evidence kinds (`code`, `test`, `runtime`, `delivery`, `human`), `minimum_observations`, `environment`, `viewport`, `manual_acceptance_required`, and `claim_limit`; otherwise set `no_ui_proof_rationale`.
+For UI-sensitive work, include compact `ui_proof_slots` with `slot_id`, optional `requirement_id`, `claim`, `route_state`, fixed evidence kinds (`code`, `test`, `runtime`, `delivery`, `human`), `minimum_observations`, `expected_artifact_types`, `validation_command`, `environment`, `viewport`, `manual_acceptance_required`, and `claim_limit`; otherwise set `no_ui_proof_rationale`.
 Do not create slots for backend-only, CLI-only, docs-only, or refactor-only work unless the plan claims a visible UI outcome. Evidence must later match claim, route/state, observation, artifact path, evidence kind, privacy metadata, result, and claim limit; local-only or unsafe artifacts cannot support public, publication, tracked, delivery, or release proof claims. Human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence.
+For live rendered UI proof, plan `agent-browser` as the default runtime evidence path and existing Playwright/package-script browser tests as the repeatable regression path when the repo already has them. If the runtime does not provide `agent-browser`, require the plan to state that availability constraint and name the closest project-native interactive browser fallback before narrowing the claim. The planner chooses the viewport set, but each slot must explain why the chosen viewport(s) are enough for the claim or narrow the claim limit; responsive claims need desktop/mobile or equivalent state coverage. Do not plan new browser infrastructure by default, and use Playwright scripting only for checks `agent-browser` cannot cover cleanly, such as JS-disabled, structured console, or multi-context verification.
 </ui_proof_planning>
 <goal_backward_planning>
 Plan backward from success criteria.

package/distilled/workflows/quick.md

@@ -118,9 +118,10 @@ Delegate to the planner role in quick mode.
 - No research phase, no ROADMAP requirements
 - Do NOT extract phase requirement IDs — there is no active phase
 - Derive must-haves directly from the task description
-- If the quick task is UI-sensitive, include proportional `ui_proof_slots` with slot_id, claim, route_state, required_evidence_kinds, minimum_observations, environment, viewport, manual_acceptance_required, and claim_limit; otherwise include a short `no_ui_proof_rationale`
+- If the quick task is UI-sensitive, include proportional `ui_proof_slots` with slot_id, claim, route_state, required_evidence_kinds, minimum_observations, expected_artifact_types, validation_command, environment, viewport, manual_acceptance_required, and claim_limit; otherwise include a short `no_ui_proof_rationale`
 - UI proof slots must be matchable to exact observed evidence later: claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. Discovery hints from source comments, AST/cAST, semantic search, or Semble-like retrieval do not satisfy proof.
 - Observed artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports are local-only/unsafe by default. Use `gsdd ui-proof validate <path>` or `gsdd health` when a bundle exists; add `--claim <...>` only for public, publication, tracked, delivery, or release proof use.
+- For live rendered UI proof, default to `agent-browser` snapshots/refs, interactions, screenshots, and relevant console/network observations. If unavailable, state the availability constraint and closest project-native interactive browser fallback before narrowing the claim. Existing Playwright/package-script browser tests remain the canonical repeatable regression path when present. The viewport set is plan-owned, but under-specified viewport coverage is weak proof; explain the chosen viewport(s) or narrow the claim limit.
 - Keep UI proof proportional: do not scaffold Playwright, Cypress, Cucumber, Storybook, CI, browser MCP, or visual-regression tooling by default
 - Ignore <planning_process> Step 1 requirement extraction; use inline goal-backward planning only
 - Target minimal context usage
@@ -160,7 +161,8 @@ Read `.planning/config.json`.
 - Mode: quick
 
 **Constraints:**
-- Check 5 dimensions only: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`
+- Check 5 dimensions by default: `requirement_coverage`, `task_completeness`, `dependency_correctness`, `scope_sanity`, `must_have_quality`
+- If the quick plan contains `ui_proof_slots` or a rendered UI claim, also check `closure_honesty` so weak UI proof slots block execution
 - Skip: `key_link_completeness`, `context_compliance`, `goal_achievement`, `approach_alignment`
 - Maximum 1 revision cycle (if blockers found, send back to planner once, then accept result)
 - Blocker threshold: only block on `task_completeness` or `scope_sanity` violations
@@ -268,6 +270,7 @@ Delegate to the executor role.
 - Do NOT update ROADMAP.md phase status or SPEC.md current state
 - Create summary at: `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`
 - If the quick plan defines `ui_proof_slots`, create or update `.planning/quick/$NEXT_NUM-$SLUG/UI-PROOF.md` with fenced JSON containing required top-level fields: `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`
+- For live UI proof, record `agent-browser` in `evidence_inputs.tools_used` when used, the exact commands or manual ref-based steps, screenshot/report artifact paths, and any relevant console/network observations. If `agent-browser` was unavailable, record that availability constraint and fallback tool explicitly. If existing Playwright tests supplied regression evidence, record the package command and result separately from the `agent-browser` runtime observation.
 - Human approval for visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, or privacy publication does not replace required `code`, `test`, `runtime`, or `delivery` evidence
 
 **Output:** `.planning/quick/$NEXT_NUM-$SLUG/$NEXT_NUM-SUMMARY.md`

package/distilled/workflows/verify.md

@@ -129,8 +129,9 @@ Note: this step does NOT replace levels 1–3. An artifact can satisfy the evide
 </evidence_contract>
 
 <ui_proof_comparison>
-If the plan defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
+If the plan defines non-empty `ui_proof_slots`, compare planned UI proof against observed bundles before closure. Prefer `gsdd ui-proof compare <planned-slots-json> [observed-bundle-json ...]` when planned slots are available as JSON or fenced JSON; otherwise perform the same field-by-field comparison and record reduced assurance if no deterministic command could run. If the plan records only `no_ui_proof_rationale`, verify the rationale instead of requiring a bundle. Each observed bundle must include top-level `proof_bundle_version`, `scope`, `route_state`, `environment`, `viewport`, `evidence_inputs`, `commands_or_manual_steps`, `observations`, `artifacts`, `privacy`, `result`, and `claim_limits`.
 Classify each slot as exactly one of: `satisfied`, `partial`, `missing`, `waived`, `deferred`, or `not_applicable`. Waiver/deferment narrows the claim; it is not proof. Screenshots, traces, videos, reports, accessibility scans, Gherkin, visual diffs, and manual notes are artifact types or activities mapped onto existing evidence kinds, not new evidence kinds. Artifact count is never proof; each artifact must tie to the slot claim, route/state, observation, artifact path/link, privacy metadata, and claim limit.
+For live UI runtime proof, expect `agent-browser` as the default captured tool unless the observed bundle explains a project-native equivalent or an availability constraint. Do not fail solely because another browser tool was used, but downgrade vague proof that lacks exact route/state, planned viewport coverage or rationale, interactive steps/refs where relevant, screenshot/report artifacts, or relevant console/network observations. Existing Playwright tests count as canonical repeatable regression evidence, not a replacement for scoped runtime evidence when the slot requires `runtime`.
 Artifact privacy metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports default to local-only and unsafe unless sanitized. Run `gsdd ui-proof validate <path>` or treat `gsdd health` E10 as blocking; add `--claim <...>` when relying on the bundle for public, tracked, delivery, release, or publication proof. Visual taste, accessibility judgment, baseline acceptance, subjective polish/layout quality, and privacy publication require human evidence or explicit waiver; human approval does not replace required `code`, `test`, `runtime`, or `delivery` evidence. Source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval are discovery hints only.
 </ui_proof_comparison>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsdd-cli",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Workspine — a repo-native delivery spine for long-horizon AI-assisted work, with directly validated support for Claude Code, Codex CLI, and OpenCode, published as gsdd-cli.",
   "type": "module",
   "bin": {