gsdd-cli 0.19.2 → 0.20.0

package/bin/lib/ui-proof.mjs

@@ -0,0 +1,467 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { isAbsolute, join, relative, resolve } from 'path';
+import { output } from './cli-utils.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
+
+const EVIDENCE_KINDS = Object.freeze(['code', 'test', 'runtime', 'delivery', 'human']);
+const COMPARISON_STATUSES = Object.freeze(['satisfied', 'partial', 'missing', 'waived', 'deferred', 'not_applicable']);
+const CLAIM_STATUSES = Object.freeze(['passed', 'failed', 'partial', 'waived', 'deferred', 'not_applicable']);
+const ARTIFACT_VISIBILITIES = Object.freeze(['local_only', 'repo_tracked', 'public']);
+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 REQUIRED_BUNDLE_FIELDS = Object.freeze([
+  'proof_bundle_version',
+  'scope',
+  'route_state',
+  'environment',
+  'viewport',
+  'evidence_inputs',
+  'commands_or_manual_steps',
+  'observations',
+  'artifacts',
+  'privacy',
+  'result',
+  'claim_limits',
+]);
+const REQUIRED_SCOPE_FIELDS = Object.freeze(['work_item', 'claim', 'requirement_ids', 'slot_ids']);
+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']);
+
+class UiProofError extends Error {}
+
+function fail(message) {
+  console.error(message);
+  throw new UiProofError(message);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasValue(value) {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'string') return value.trim() !== '';
+  if (Array.isArray(value)) return value.length > 0;
+  if (isPlainObject(value)) return Object.keys(value).length > 0;
+  return true;
+}
+
+function pathLabel(basePath, key) {
+  return basePath ? `${basePath}.${key}` : key;
+}
+
+function addError(errors, code, path, message, fix) {
+  errors.push({ code, path, message, fix });
+}
+
+function requireField(obj, field, path, errors) {
+  if (!isPlainObject(obj) || !hasValue(obj[field])) {
+    addError(errors, 'missing_required_field', pathLabel(path, field), `Missing required UI proof field: ${pathLabel(path, field)}`, 'Add the required field to the proof bundle metadata.');
+    return false;
+  }
+  return true;
+}
+
+function normalizeArray(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  return [];
+}
+
+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';
+  return explicit;
+}
+
+function isRawUiArtifact(artifact) {
+  return RAW_ARTIFACT_TYPES.includes(artifactType(artifact));
+}
+
+function collectClaimUses(bundle, options) {
+  const uses = new Set();
+  for (const value of normalizeArray(options.claimUse).concat(normalizeArray(options.claimUses))) {
+    uses.add(String(value).toLowerCase());
+  }
+
+  const explicitSources = [
+    bundle?.proof_claim,
+    bundle?.proof_claims,
+    bundle?.claim_context?.proof_use,
+    bundle?.claim_context?.proof_uses,
+    bundle?.publication?.intended_use,
+  ];
+  for (const source of explicitSources) {
+    for (const value of normalizeArray(source)) uses.add(String(value).toLowerCase());
+  }
+
+  return [...uses];
+}
+
+function validateClaimUses(bundle, options, errors) {
+  for (const value of collectClaimUses(bundle, options)) {
+    if (!CLAIM_USES.includes(value)) {
+      addError(errors, 'unsupported_claim_use', 'proof_claim', `Unsupported UI proof claim use: ${value}`, `Use only: ${CLAIM_USES.join(', ')}.`);
+    }
+  }
+}
+
+function hasPublicClaim(bundle, options) {
+  return collectClaimUses(bundle, options).some((value) => PUBLIC_CLAIM_USES.includes(value));
+}
+
+function validateObservationPrivacy(privacy, path, errors) {
+  for (const field of REQUIRED_PRIVACY_FIELDS) requireField(privacy, field, path, errors);
+  if (hasValue(privacy?.raw_artifacts_safe_to_publish) && typeof privacy.raw_artifacts_safe_to_publish !== 'boolean') {
+    addError(errors, 'invalid_raw_artifacts_safe_to_publish', `${path}.raw_artifacts_safe_to_publish`, 'raw_artifacts_safe_to_publish must be a boolean.', 'Use false unless all raw artifacts are explicitly safe to publish.');
+  }
+}
+
+function validateCommandsOrManualSteps(bundle, errors) {
+  for (const [index, step] of normalizeArray(bundle?.commands_or_manual_steps).entries()) {
+    const stepPath = `commands_or_manual_steps[${index}]`;
+    if (!isPlainObject(step)) {
+      addError(errors, 'invalid_proof_step', stepPath, 'UI proof command/manual step entry must be an object.', 'Record a command or manual_step plus its result.');
+      continue;
+    }
+    if (!hasValue(step.command) && !hasValue(step.manual_step)) {
+      addError(errors, 'missing_proof_step_action', stepPath, 'UI proof command/manual step must include command or manual_step.', 'Record the exact command or manual step used to generate the observation.');
+    }
+    if (!hasValue(step.result)) {
+      addError(errors, 'missing_proof_step_result', `${stepPath}.result`, 'UI proof command/manual step must include result.', `Record result using: ${CLAIM_STATUSES.join(', ')}.`);
+    } else if (!CLAIM_STATUSES.includes(step.result)) {
+      addError(errors, 'invalid_proof_step_result', `${stepPath}.result`, `Invalid UI proof command/manual step result: ${step.result}`, `Use only: ${CLAIM_STATUSES.join(', ')}.`);
+    }
+  }
+}
+
+function validateObservations(bundle, errors) {
+  for (const [index, observation] of normalizeArray(bundle?.observations).entries()) {
+    const observationPath = `observations[${index}]`;
+    if (!isPlainObject(observation)) {
+      addError(errors, 'invalid_observation', observationPath, 'UI proof observation entry must be an object.', 'Record observation metadata with claim, route_state, evidence_kind, artifact_refs, privacy, result, and claim_limit.');
+      continue;
+    }
+    for (const field of REQUIRED_OBSERVATION_FIELDS) requireField(observation, field, observationPath, errors);
+    if (hasValue(observation.evidence_kind) && !EVIDENCE_KINDS.includes(observation.evidence_kind)) {
+      addError(errors, 'unsupported_evidence_kind', `${observationPath}.evidence_kind`, `Unsupported UI proof observation evidence kind: ${observation.evidence_kind}`, `Use only: ${EVIDENCE_KINDS.join(', ')}.`);
+    }
+    if (hasValue(observation.result) && !CLAIM_STATUSES.includes(observation.result)) {
+      addError(errors, 'invalid_observation_result', `${observationPath}.result`, `Invalid UI proof observation result: ${observation.result}`, `Use only: ${CLAIM_STATUSES.join(', ')}.`);
+    }
+    validateObservationPrivacy(observation.privacy, `${observationPath}.privacy`, errors);
+  }
+}
+
+function validateEvidenceKinds(bundle, errors) {
+  const kinds = normalizeArray(bundle?.evidence_inputs?.kinds);
+  if (kinds.length === 0) {
+    addError(errors, 'missing_evidence_kinds', 'evidence_inputs.kinds', 'Missing UI proof evidence kinds.', 'Record at least one fixed evidence kind: code, test, runtime, delivery, or human.');
+  }
+  for (const [index, kind] of kinds.entries()) {
+    if (!EVIDENCE_KINDS.includes(kind)) {
+      addError(errors, 'unsupported_evidence_kind', `evidence_inputs.kinds[${index}]`, `Unsupported UI proof evidence kind: ${kind}`, `Use only: ${EVIDENCE_KINDS.join(', ')}.`);
+    }
+  }
+}
+
+function validateResult(bundle, errors) {
+  if (!isPlainObject(bundle?.result)) return;
+  if (!hasValue(bundle.result.claim_status)) {
+    addError(errors, 'missing_claim_status', 'result.claim_status', 'Missing UI proof result claim status.', `Record claim_status using: ${CLAIM_STATUSES.join(', ')}.`);
+  } else if (!CLAIM_STATUSES.includes(bundle.result.claim_status)) {
+    addError(errors, 'invalid_claim_status', 'result.claim_status', `Invalid UI proof claim status: ${bundle.result.claim_status}`, `Use only: ${CLAIM_STATUSES.join(', ')}.`);
+  }
+}
+
+function validateComparisonStatuses(bundle, errors) {
+  const statuses = bundle?.result?.comparison_status_by_slot;
+  if (!isPlainObject(statuses)) {
+    addError(errors, 'missing_comparison_statuses', 'result.comparison_status_by_slot', 'Missing UI proof comparison statuses by slot.', `Record one status per slot using: ${COMPARISON_STATUSES.join(', ')}.`);
+    return;
+  }
+  const slotIds = normalizeArray(bundle?.scope?.slot_ids);
+  const slotSet = new Set(slotIds);
+  for (const slotId of slotIds) {
+    if (!hasValue(statuses[slotId])) {
+      addError(errors, 'missing_comparison_status', `result.comparison_status_by_slot.${slotId}`, `Missing UI proof comparison status for slot: ${slotId}`, `Record one status per slot using: ${COMPARISON_STATUSES.join(', ')}.`);
+    }
+  }
+  for (const [slot, status] of Object.entries(statuses)) {
+    if (slotSet.size > 0 && !slotSet.has(slot)) {
+      addError(errors, 'unknown_comparison_slot', `result.comparison_status_by_slot.${slot}`, `UI proof comparison status references undeclared slot: ${slot}`, 'Use only slot IDs declared in scope.slot_ids.');
+    }
+    if (!COMPARISON_STATUSES.includes(status)) {
+      addError(errors, 'invalid_comparison_status', `result.comparison_status_by_slot.${slot}`, `Invalid UI proof comparison status: ${status}`, `Use only: ${COMPARISON_STATUSES.join(', ')}.`);
+    }
+  }
+}
+
+function validateClaimLimits(bundle, errors) {
+  const claimLimits = normalizeArray(bundle?.claim_limits);
+  if (claimLimits.length === 0) {
+    addError(errors, 'missing_claim_limits', 'claim_limits', 'Missing UI proof claim limits.', 'Add at least one claim limit that narrows what this proof does not prove.');
+  }
+}
+
+function artifactReference(artifact) {
+  if (!isPlainObject(artifact)) return null;
+  if (typeof artifact.path === 'string' && artifact.path.trim()) return artifact.path.trim();
+  if (typeof artifact.url === 'string' && artifact.url.trim()) return artifact.url.trim();
+  return null;
+}
+
+function validateArtifactReferenceSafety(ref, path, errors) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(ref)) {
+    if (!/^https?:\/\//i.test(ref)) {
+      addError(errors, 'invalid_artifact_ref_location', path, `UI proof artifact reference uses an unsupported URL scheme: ${ref}`, 'Use a workspace-relative path or an http(s) URL; do not reference local file URLs.');
+    }
+    return;
+  }
+  if (ref.startsWith('//') || isAbsolute(ref) || ref.split(/[\\/]+/).includes('..')) {
+    addError(errors, 'invalid_artifact_ref_location', path, `UI proof artifact reference must stay workspace-relative: ${ref}`, 'Use a relative path under the workspace, or an http(s) URL for external sanitized evidence.');
+  }
+}
+
+function isSanitizedSensitivity(value) {
+  return typeof value === 'string' && /(^|[_\s-])(sanitized|public_safe|public-safe)($|[_\s-])/.test(value.toLowerCase());
+}
+
+function validateArtifacts(bundle, errors, publicClaim) {
+  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.');
+    return new Set();
+  }
+
+  const artifactRefs = new Set();
+  for (const [index, artifact] of artifacts.entries()) {
+    const artifactPath = `artifacts[${index}]`;
+    if (!isPlainObject(artifact)) {
+      addError(errors, 'invalid_artifact', artifactPath, 'UI proof artifact entry must be an object.', 'Record path/type plus privacy metadata for each artifact.');
+      continue;
+    }
+    const ref = artifactReference(artifact);
+    if (!ref) {
+      addError(errors, 'missing_artifact_ref', artifactPath, 'UI proof artifact must include path or url.', 'Reference raw UI artifacts by path or URL; do not inline them.');
+    } else {
+      validateArtifactReferenceSafety(ref, artifactPath, errors);
+      artifactRefs.add(ref);
+    }
+    for (const field of REQUIRED_ARTIFACT_FIELDS) {
+      requireField(artifact, field, artifactPath, errors);
+    }
+    if (hasValue(artifact.visibility) && !ARTIFACT_VISIBILITIES.includes(artifact.visibility)) {
+      addError(errors, 'invalid_visibility', `${artifactPath}.visibility`, `Invalid UI proof artifact visibility: ${artifact.visibility}`, `Use only: ${ARTIFACT_VISIBILITIES.join(', ')}.`);
+    }
+    if (hasValue(artifact.safe_to_publish) && typeof artifact.safe_to_publish !== 'boolean') {
+      addError(errors, 'invalid_safe_to_publish', `${artifactPath}.safe_to_publish`, 'safe_to_publish must be a boolean.', 'Use true only after explicit safe-to-publish classification; otherwise use false.');
+    }
+    if (isRawUiArtifact(artifact) && artifact.visibility !== 'local_only' && artifact.safe_to_publish !== true) {
+      addError(errors, 'unsafe_raw_artifact', artifactPath, 'Raw UI artifacts are local-only by default unless explicitly classified safe to publish.', 'Set visibility: local_only and safe_to_publish: false, or document sanitized public-safe classification.');
+    }
+    if (publicClaim && (artifact.visibility === 'local_only' || artifact.safe_to_publish !== true)) {
+      addError(errors, 'unsafe_public_proof_claim', artifactPath, 'Public/tracked/delivery UI proof claims cannot rely on local-only or unsafe artifacts.', 'Use local-only claim language, or provide sanitized artifacts with safe_to_publish: true and non-local visibility.');
+    }
+    if (publicClaim && isRawUiArtifact(artifact) && !isSanitizedSensitivity(artifact.sensitivity)) {
+      addError(errors, 'unsafe_public_artifact_sensitivity', `${artifactPath}.sensitivity`, 'Public/tracked/delivery raw UI proof artifacts must be classified sanitized.', 'Set sensitivity to a sanitized/public-safe classification after explicit review, or narrow the proof claim.');
+    }
+  }
+  return artifactRefs;
+}
+
+function validatePrivacy(bundle, errors, publicClaim) {
+  validateObservationPrivacy(bundle.privacy, 'privacy', errors);
+  if (publicClaim && bundle.privacy?.raw_artifacts_safe_to_publish !== true) {
+    addError(errors, 'unsafe_public_proof_privacy', 'privacy.raw_artifacts_safe_to_publish', 'Public/tracked/delivery UI proof claims require bundle privacy metadata to classify raw artifacts safe to publish.', 'Use local-only claim language, or set raw_artifacts_safe_to_publish: true after sanitized/public-safe review.');
+  }
+}
+
+function validatePublicObservationPrivacy(bundle, errors, publicClaim) {
+  if (!publicClaim) return;
+  for (const [index, observation] of normalizeArray(bundle?.observations).entries()) {
+    if (!isPlainObject(observation)) continue;
+    if (observation.privacy?.raw_artifacts_safe_to_publish !== true) {
+      addError(errors, 'unsafe_public_observation_privacy', `observations[${index}].privacy.raw_artifacts_safe_to_publish`, 'Public/tracked/delivery UI proof claims require observation privacy metadata to classify raw artifacts safe to publish.', 'Use local-only claim language, or set raw_artifacts_safe_to_publish: true after sanitized/public-safe review.');
+    }
+  }
+}
+
+function validateObservationArtifactRefs(bundle, artifactRefs, errors) {
+  for (const [index, observation] of normalizeArray(bundle?.observations).entries()) {
+    if (!isPlainObject(observation)) continue;
+    for (const [refIndex, ref] of normalizeArray(observation.artifact_refs).entries()) {
+      if (!artifactRefs.has(ref)) {
+        addError(errors, 'unknown_artifact_ref', `observations[${index}].artifact_refs[${refIndex}]`, `Observation references undeclared UI proof artifact: ${ref}`, 'Add the artifact to artifacts[] or correct the observation artifact reference.');
+      }
+    }
+  }
+}
+
+export function validateUiProofBundle(bundle, options = {}) {
+  const errors = [];
+  const warnings = [];
+
+  if (!isPlainObject(bundle)) {
+    addError(errors, 'invalid_bundle', '', 'UI proof bundle must be an object.', 'Provide structured UI proof metadata.');
+    return { valid: false, errors, warnings };
+  }
+
+  for (const field of REQUIRED_BUNDLE_FIELDS) requireField(bundle, field, '', errors);
+  for (const field of REQUIRED_SCOPE_FIELDS) requireField(bundle.scope, field, 'scope', errors);
+  const publicClaim = hasPublicClaim(bundle, options);
+  validateClaimUses(bundle, options, errors);
+  validateEvidenceKinds(bundle, errors);
+  validateCommandsOrManualSteps(bundle, errors);
+  validateObservations(bundle, errors);
+  validateResult(bundle, errors);
+  validateComparisonStatuses(bundle, errors);
+  validateClaimLimits(bundle, errors);
+  validatePrivacy(bundle, errors, publicClaim);
+  validatePublicObservationPrivacy(bundle, errors, publicClaim);
+  const artifactRefs = validateArtifacts(bundle, errors, publicClaim);
+  validateObservationArtifactRefs(bundle, artifactRefs, errors);
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export function parseUiProofBundleContent(content, filePath = 'UI proof bundle') {
+  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.' }] };
+  }
+
+  const jsonCandidates = [trimmed];
+  const fenceMatches = [...trimmed.matchAll(/```(?:json|ui-proof-json)?\s*([\s\S]*?)```/gi)];
+  for (const match of fenceMatches) jsonCandidates.push(match[1].trim());
+
+  for (const candidate of jsonCandidates) {
+    try {
+      return { bundle: 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.' }],
+  };
+}
+
+export function readUiProofBundleFile(filePath) {
+  return parseUiProofBundleContent(readFileSync(filePath, 'utf-8'), filePath);
+}
+
+function walkForUiProofFiles(dir, results) {
+  if (!existsSync(dir)) return;
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      walkForUiProofFiles(fullPath, results);
+      continue;
+    }
+    const name = entry.toLowerCase();
+    if (['ui-proof.json', 'ui-proof.md', 'proof-bundle.json'].includes(name)) {
+      results.add(fullPath);
+    }
+  }
+}
+
+export function findUiProofBundleFiles(planningDir) {
+  const results = new Set();
+  for (const relativePath of [
+    'UI-PROOF.json',
+    'ui-proof.json',
+    'ui-proof.md',
+    'ui-proof/UI-PROOF.json',
+    'ui-proof/proof-bundle.json',
+    'brownfield-change/UI-PROOF.json',
+  ]) {
+    const fullPath = join(planningDir, relativePath);
+    if (existsSync(fullPath)) results.add(fullPath);
+  }
+  for (const relativeDir of ['phases', 'quick', 'brownfield-change']) {
+    walkForUiProofFiles(join(planningDir, relativeDir), results);
+  }
+  return [...results].sort();
+}
+
+function resolveWorkspacePath(cwd, target) {
+  const workspaceRoot = resolve(cwd);
+  const resolved = resolve(workspaceRoot, target);
+  const rel = relative(workspaceRoot, resolved);
+  if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) return resolved;
+  fail(`Path must stay inside the workspace: ${target}`);
+}
+
+function parseClaimUse(args) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg !== '--claim') fail('Usage: gsdd ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]');
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) fail('Usage: gsdd ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]');
+    values.push(...value.split(',').map((entry) => entry.trim()).filter(Boolean));
+    index += 1;
+  }
+  for (const value of values) {
+    if (!PUBLIC_CLAIM_USES.includes(value)) fail(`Unsupported UI proof claim use: ${value}`);
+  }
+  return values;
+}
+
+function cmdValidate(cwd, args) {
+  const [targetArg, ...flags] = args;
+  if (!targetArg) fail('Usage: gsdd ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]');
+  const target = resolveWorkspacePath(cwd, targetArg);
+  if (!existsSync(target) || statSync(target).isDirectory()) fail(`UI proof bundle file does not exist: ${targetArg}`);
+
+  const parsed = readUiProofBundleFile(target);
+  const validation = parsed.errors.length > 0
+    ? { valid: false, errors: parsed.errors, warnings: [] }
+    : validateUiProofBundle(parsed.bundle, { claimUses: parseClaimUse(flags) });
+
+  output({ operation: 'ui-proof validate', target: targetArg, valid: validation.valid, errors: validation.errors, warnings: validation.warnings });
+  if (!validation.valid) process.exitCode = 1;
+}
+
+export function cmdUiProof(...args) {
+  const { args: normalizedArgs, workspaceRoot, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const [operation, ...rest] = normalizedArgs;
+  try {
+    switch (operation) {
+      case 'validate':
+        cmdValidate(workspaceRoot, rest);
+        return;
+      default:
+        fail('Usage: gsdd ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]');
+    }
+  } catch (error) {
+    if (error instanceof UiProofError) {
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}
+
+export {
+  ARTIFACT_VISIBILITIES as UI_PROOF_ARTIFACT_VISIBILITIES,
+  COMPARISON_STATUSES as UI_PROOF_COMPARISON_STATUSES,
+  EVIDENCE_KINDS as UI_PROOF_EVIDENCE_KINDS,
+  RAW_ARTIFACT_TYPES as UI_PROOF_RAW_ARTIFACT_TYPES,
+};

package/distilled/DESIGN.md

@@ -71,6 +71,8 @@
 58. [Local Workflow Helper Launcher](#d58---local-workflow-helper-launcher)
 59. [Continuity Authority And Planning-State Drift](#d59---continuity-authority-and-planning-state-drift)
 60. [Release Closeout Contract](#d60---release-closeout-contract)
+61. [Deliberate Subagent Contract](#d61---deliberate-subagent-contract)
+62. [Repo-Native UI Proof Contract](#d62---repo-native-ui-proof-contract)
 
 ---
 
@@ -285,11 +287,11 @@ This hardening pass also clarified a reusable architectural rule: strict portabl
 
 | researchDepth | Synthesizer behavior                                                                                                                                                                              |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fast`        | Orchestrator writes SUMMARY.md inline from the 4 x 3-5 sentence summaries it holds in context. No delegate spawned.                                                                               |
+| `fast`        | Orchestrator writes SUMMARY.md inline from the 4 human-read structured summaries it holds in context. No delegate spawned.                                                                         |
 | `balanced`    | ResearchSynthesizer delegate spawned. Reads 4 full research files. Cross-references build order constraints, pitfall-to-phase mappings, feature-architecture conflicts that short summaries omit. |
 | `deep`        | Same as balanced but researchers produce longer output (more material for synthesizer to cross-reference).                                                                                        |
 
-**Why conditional:** The synthesizer's value is in cross-referencing specific data across research dimensions. When `researchDepth=fast`, researchers produce 3-5 sentence summaries only -- there's nothing substantive to cross-reference. Spawning a synthesizer to reformat 4 short paragraphs wastes a context window and an agent hop.
+**Why conditional:** The synthesizer's value is in cross-referencing specific data across research dimensions. When `researchDepth=fast`, researchers return compact summaries and the full research files remain available on disk; spawning a synthesizer to reformat shallow inputs wastes a context window and an agent hop.
 
 **Evidence:**
 
@@ -442,7 +444,7 @@ Codex CLI is skills-first because the terminal CLI supports repository skills di
 
 **GSDD:** Makes this explicit as a design rule.
 
-**The rule:** Delegates write full documents to disk. They return 3-5 sentence summaries to the orchestrator. The orchestrator never receives document contents in its conversation context.
+**The rule:** Delegates write full documents to disk. They return bounded summaries to the orchestrator: routing summaries use 100-200 tokens, human-read summaries use 300-500 tokens, and agent-mediated discussion summaries use 500-800 tokens. The orchestrator never receives document contents in its conversation context.
 
 **Why this matters:**
 
@@ -452,7 +454,7 @@ Codex CLI is skills-first because the terminal CLI supports repository skills di
 
 **Implementation:**
 
-- Each delegate's instructions end with: "Return a 3-5 sentence summary of key findings. Do NOT return the full document contents."
+- Each delegate's instructions identify the correct summary tier and keep full document contents on disk instead of echoing them into orchestrator context.
 - Output templates in `.planning/templates/research/` and `.planning/templates/codebase/` define the on-disk format.
 - The synthesizer reads all 4 research files from disk -- it is the only agent that sees full research content.
 
@@ -955,8 +957,9 @@ Implementation lives under `bin/lib/`:
 | E5 | ERROR | `.planning/templates/delegates/` missing or empty |
 | E6 | ERROR | `.planning/templates/research/` missing or empty |
 | E7 | ERROR | `.planning/templates/codebase/` missing or empty |
-| E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`) |
+| E8 | ERROR | `.planning/templates/` missing critical root files (`spec.md`, `roadmap.md`, `auth-matrix.md`, `ui-proof.md`) |
 | E9 | ERROR | `.planning/templates/brownfield-change/` missing or missing critical files (`CHANGE.md`, `HANDOFF.md`, `VERIFICATION.md`) |
+| E10 | ERROR | Known UI proof bundle metadata is unparseable or fails deterministic privacy/claim validation |
 | W1 | WARN | `generation-manifest.json` missing |
 | W2 | WARN | Manifest-tracked installed templates/helpers modified locally (hash mismatch vs manifest) |
 | W3 | WARN | Manifest-tracked installed templates/helpers missing from disk but listed in manifest |
@@ -1356,7 +1359,7 @@ Combined, these three workflows provided genuine leverage: the planner could not
 
 **GSDD decision:** Recover the discuss-phase leverage as a single role (`agents/approach-explorer.md`) embedded in the plan workflow, with a hybrid interaction architecture:
 
-1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed ~1000-token structured summary. Only summaries enter the conversation context, not raw file reads.
+1. **Primary path (inline + research subagents):** Conversation runs in the plan workflow's main context (required for user interactivity). For each technical gray area, a read-only research subagent spawns, reads codebase/docs, and returns a compressed 500-800 token structured summary. Only summaries enter the conversation context, not raw file reads.
 
 2. **Native agent optimization:** Runtimes with interactive subagent support (Claude Code with `AskUserQuestion`, Codex interactive agents, OpenCode `mode: agent`) can run the full exploration as a native agent. Falls back to the inline primary path if unavailable.
 
@@ -1389,7 +1392,7 @@ The approach explorer needs two capabilities with opposite context requirements:
 - **Conversation** needs the main context (for user interaction)
 - **Research** generates thousands of tokens of raw content the conversation doesn't need
 
-Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`<research_subagent_prompt>` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: ~1000 tokens orchestration + ~4000 tokens research summaries (4 areas × ~1000) + ~4000 tokens conversation + ~500 tokens APPROACH.md = ~9500 tokens. The 1000-token budget (matching Anthropic CE's recommended floor) gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent.
+Isolating research in subagents and returning compressed summaries follows the Compress and Isolate patterns from context engineering literature. The research subagent prompt template lives in the role contract (`<research_subagent_prompt>` section of `agents/approach-explorer.md`) — co-located with the algorithm it serves, and referenced by the portable workflow rather than inlined. The main context budget stays manageable: about 1000 tokens orchestration, up to 3200 tokens research summaries (4 areas x 800), about 4000 tokens conversation, and about 500 tokens APPROACH.md. The 500-800 token agent-mediated discussion tier gives research subagents room for the structured format (Name/Pro/Con/Source) plus recommendation reasoning, source verification, and enough project-specific context that the main agent can handle follow-up questions without re-querying the subagent.
 
 **Evidence:**
 
@@ -2776,6 +2779,84 @@ Posture compatibility is part of that closeout contract: `repo_closeout` and `ru
 - `complete-milestone` now fails closed before archive writes when the passed audit omits or contradicts the release claim contract.
 - Public claims are scoped to tracked public or repo-visible proof, while GitHub Releases, tags, package publication, and release automation remain deferred until explicitly planned.
 
+## D61 - Deliberate Subagent Contract
+
+**Decision (2026-04-28):** Subagents are deliberate isolation tools, not hidden implementation orchestration. Workspine should use them for research, review, mapping, synthesis, and integration checking when the work is read-only or artifact-backed, while implementation remains sequential unless an approved plan explicitly owns disjoint write sets.
+
+**Context:**
+- Phase 50 found that existing subagent wording was over-strong in some planning and role surfaces while summary-size guidance had drifted across 3-5 sentence, 300-500 token, and 1000-token variants.
+- Phase 46 research supported parallel agents for breadth-first research, but warned that coding writes need stronger coordination before parallel PR or multi-worktree orchestration is safe.
+- Phase 53 approach alignment confirmed the conservative boundary: allow read-heavy and artifact-backed delegation, forbid hidden implementation orchestration, keep roadmapper role-only/direct invocation, and do not claim broad S3/S5 closure or native runtime parity.
+
+**Decision:**
+- Allowed subagent use: research, review, mapping, synthesis, and integration checks when they are read-only or when the subagent writes/updates its own bounded durable artifact.
+- Return discipline: routing summaries use 100-200 tokens, human-read summaries use 300-500 tokens, agent-mediated discussion summaries use 500-800 tokens, and full details live in durable documents on disk.
+- Forbidden by default: hidden implementation orchestration, agent teams, parallel PR flows, multi-worktree coding, and overlapping implementation writes without explicit write-set ownership in the approved plan.
+- Roadmapper remains role-only/direct invocation in Phase 53. Roadmap creation is sequential and coverage-sensitive, writes `.planning/ROADMAP.md`, and does not yet have a proven thin-wrapper delegate use case.
+- S3 and S5 remain deferred. This decision narrows the practical Workspine subagent contract but does not close broad subagent orchestration parity or adapter research gaps.
+
+**Leverage:**
+- Lost: less flexibility for future agents to add delegates by symmetry or treat missing delegates as accidental gaps.
+- Kept: the two-layer role/delegate architecture, summaries-up/documents-to-disk, repo-native workflow state, lifecycle preflight, and write-set constraints.
+- Gained: a durable conservative rule that tells agents when subagents earn their keep and when they create hidden orchestration risk.
+
+**Evidence:**
+- `agents/README.md`
+- `agents/DISTILLATION.md`
+- `distilled/templates/delegates/`
+- `distilled/workflows/map-codebase.md`
+- `distilled/workflows/new-project.md`
+- GSD comparison source: `get-shit-done/workflows/new-project.md` and mapper/research workflows use `Task()` subagents heavily, but GSDD keeps the portable core single-agent-safe and only preserves subagent use where isolation, artifact persistence, or fresh-context review pays for the complexity.
+
+**Consequences:**
+- Future role, delegate, and workflow wording must distinguish read-only/artifact-backed delegation from implementation write ownership.
+- A roadmapper delegate must not appear by symmetry; it needs a future explicit design decision and regression updates.
+- Generated runtime freshness may propagate this wording, but generated freshness is not runtime parity proof.
+
+---
+
+## 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`.
+
+**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.
+
+**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.
+- 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.
+- 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.
+
+**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.
+
+**Evidence:**
+- `distilled/templates/ui-proof.md`
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/verify.md`
+- `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`
+- 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.
+
+**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.
+
+---
+
 ## Maintenance
 
 This document is updated when:

package/distilled/EVIDENCE-INDEX.md

@@ -478,6 +478,20 @@
 - `distilled/DESIGN.md` D50 and D59
 - `tests/phase.test.cjs`, `tests/gsdd.guards.test.cjs`, `tests/gsdd.scenarios.test.cjs`
 
+## D61 — Deliberate Subagent Contract
+- `agents/README.md`, `agents/DISTILLATION.md`, `agents/approach-explorer.md`, `agents/planner.md`, `agents/roadmapper.md`
+- `distilled/templates/delegates/approach-explorer.md`, `distilled/templates/delegates/plan-checker.md`
+- `distilled/workflows/audit-milestone.md`, `distilled/workflows/map-codebase.md`, `distilled/workflows/new-project.md`, `distilled/workflows/plan.md`
+- GSD comparison source: `get-shit-done/workflows/new-project.md`
+- `tests/gsdd.guards.test.cjs`, `tests/gsdd.invariants.test.cjs`
+
+## D62 — Repo-Native UI Proof Contract
+- `distilled/templates/ui-proof.md`
+- `distilled/workflows/plan.md`, `distilled/workflows/execute.md`, `distilled/workflows/quick.md`, `distilled/workflows/verify.md`
+- `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`
+
 ---
 
 ## Maintenance

package/distilled/templates/delegates/approach-explorer.md

@@ -25,4 +25,4 @@ Classify each gray area before acting on it:
 
 Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template.
 
-Return structured summary: gray areas explored, decisions captured, assumptions validated/corrected, deferred ideas, path to APPROACH.md.
+Return only a structured summary: gray areas explored, decisions captured, assumptions validated/corrected, deferred ideas, and path to APPROACH.md. Full decision detail belongs in the APPROACH.md artifact, not in the orchestrator context.