gsdd-cli 0.21.0 → 0.23.0

package/bin/lib/init-flow.mjs

@@ -100,6 +100,7 @@ export function createCmdInit(ctx) {
       promptApi,
       preselectedConfig: interactiveSession.config,
     });
+    ensureGitignoreEntry(ctx.cwd, '.planning/.local/', '  - ensured .planning/.local/ is gitignored');
 
     if (briefSource) {
       cpSync(briefSource, join(ctx.planningDir, 'PROJECT_BRIEF.md'));
@@ -273,7 +274,7 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
   if (preselectedConfig) {
     writeFileSync(configFile, JSON.stringify(preselectedConfig, null, 2));
     console.log('  - saved .planning/config.json (guided wizard)\n');
-    if (!preselectedConfig.commitDocs) ensureGitignoreEntry(cwd);
+    if (!preselectedConfig.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
     return;
   }
 
@@ -281,7 +282,7 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
     const config = buildDefaultConfig({ autoAdvance: true });
     writeFileSync(configFile, JSON.stringify(config, null, 2));
     console.log('  - wrote .planning/config.json (auto defaults)\n');
-    if (!config.commitDocs) ensureGitignoreEntry(cwd);
+    if (!config.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
     return;
   }
 
@@ -289,7 +290,7 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
     const config = buildDefaultConfig({ autoAdvance: false });
     writeFileSync(configFile, JSON.stringify(config, null, 2));
     console.log('  - wrote .planning/config.json (non-interactive defaults)\n');
-    if (!config.commitDocs) ensureGitignoreEntry(cwd);
+    if (!config.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
     return;
   }
 
@@ -303,18 +304,17 @@ async function ensureConfig({ cwd, planningDir, isAuto, promptApi, preselectedCo
 
   writeFileSync(configFile, JSON.stringify(selected, null, 2));
   console.log('  - saved .planning/config.json (guided wizard)\n');
-  if (!selected.commitDocs) ensureGitignoreEntry(cwd);
+  if (!selected.commitDocs) ensureGitignoreEntry(cwd, '.planning/', '  - ensured .planning/ is gitignored');
 }
 
-function ensureGitignoreEntry(cwd) {
+function ensureGitignoreEntry(cwd, entry, message) {
   const gitignorePath = join(cwd, '.gitignore');
-  const entry = '.planning/';
   const hasGitignore = existsSync(gitignorePath);
   const current = hasGitignore ? readFileSync(gitignorePath, 'utf-8') : '';
   if (!current.split(/\r?\n/).includes(entry)) {
     const next = current.trimEnd() ? `${current.trimEnd()}\n${entry}\n` : `${entry}\n`;
     writeFileSync(gitignorePath, next);
-    console.log('  - ensured .planning/ is gitignored');
+    console.log(message);
   }
 }
 

package/bin/lib/init-runtime.mjs

@@ -192,6 +192,8 @@ Commands:
                               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
+  control-map [--json] [--with-ignored] [--annotations <path>]
+                              Report computed repo/worktree/planning state and local annotations
   help                        Show this summary
 
 Platforms (for --tools):
@@ -263,6 +265,7 @@ Advanced/internal helpers (kept available, but not the primary first-run user st
   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 and compare planned slots to observed bundles
+  control-map               Report computed repo/worktree/planning state and local annotations
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/rendering.mjs

@@ -7,6 +7,7 @@ const __dirname = dirname(__filename);
 const DISTILLED_DIR = join(__dirname, '..', '..', 'distilled');
 const HELPER_LIB_FILES = Object.freeze([
   'cli-utils.mjs',
+  'control-map.mjs',
   'evidence-contract.mjs',
   'file-ops.mjs',
   'lifecycle-preflight.mjs',
@@ -49,6 +50,7 @@ import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdPhaseStatus } from './lib/phase.mjs';
 import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
 import { cmdUiProof } from './lib/ui-proof.mjs';
+import { cmdControlMap } from './lib/control-map.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const COMMANDS = {
@@ -57,6 +59,7 @@ const COMMANDS = {
   'phase-status': cmdPhaseStatus,
   'session-fingerprint': cmdSessionFingerprint,
   'ui-proof': cmdUiProof,
+  'control-map': cmdControlMap,
 };
 
 function printHelp() {
@@ -78,6 +81,8 @@ function printHelp() {
     '                               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',
+    '  control-map [--json] [--with-ignored] [--annotations <path>]',
+    '                               Report computed repo/worktree/planning state and local annotations',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',

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) {
@@ -539,15 +633,30 @@ function compareSlotToBundle(slot, slotIdValue, observed) {
     }
   }
 
+  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 = [];
+  const errors = [...slotValidation.errors];
 
   for (const observed of bundles) {
     if (!observed.validation.valid) {
@@ -614,14 +723,16 @@ 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 };
@@ -688,7 +799,14 @@ export function parseUiProofSlotsContent(content, filePath = 'UI proof slots') {
     };
   }
 
-  return { slots, errors: [] };
+  const validation = validateUiProofSlots(slots);
+  return {
+    slots,
+    errors: validation.errors.map((error) => ({
+      ...error,
+      path: error.path === 'ui_proof_slots' ? filePath : `${filePath}.${error.path}`,
+    })),
+  };
 }
 
 export function readUiProofBundleFile(filePath) {
@@ -763,7 +881,12 @@ 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;
@@ -799,7 +922,7 @@ function cmdCompare(cwd, args) {
   }
 
   const comparison = planned.errors.length > 0
-    ? { status: 'missing', slots: [], errors: planned.errors }
+    ? { status: 'partial', slots: [], errors: planned.errors }
     : compareUiProofSlots(planned.slots, observedBundles);
 
   output({

package/distilled/DESIGN.md

@@ -73,6 +73,7 @@
 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)
+63. [Computed-First Control Map](#d63---computed-first-control-map)
 
 ---
 
@@ -2817,30 +2818,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 +2856,60 @@ 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.
+
+## D63 - Computed-First Control Map
+
+**Decision (2026-05-08):** Long-running multi-agent and multi-worktree control uses a computed-first `gsdd control-map` helper rather than a new lifecycle workflow or a vendor session parser. The helper computes repo/worktree/planning truth live and overlays optional local annotations only for intent that git cannot know.
+
+**Context:**
+- Gap I52 showed that ordinary `git status` can be clean while sibling worktrees, detached runtime worktrees, ignored/generated surfaces, snapshots, dirty local WIP, and cleanup obligations remain unexplained.
+- Gap I54 showed that repeated subagent swarms can become a substitute for shared state when there is no one-screen control map for active branches, ownership, proof state, and cleanup debt.
+- Current runtime research shows the only portable cross-vendor coordination layer is repo artifacts plus generated workflow entrypoints. Claude, OpenCode, Codex, Cursor, Copilot, and Gemini do not expose one uniform authoritative session/worktree store.
+- Current harness guidance favors structured handoff artifacts, worktree isolation, evaluator loops, approval gates around side effects, and browser/runtime evidence. Those ideas fit Workspine only if repo truth remains primary and vendor adapters stay thin.
+
+**Decision:**
+- Add `gsdd control-map [--json] [--with-ignored] [--annotations <path>]` to the main CLI and generated `.planning/bin/gsdd.mjs` helper runtime.
+- Compute authority from live git/worktree state first: canonical checkout, branch, HEAD, upstream divergence when comparable, tracked/untracked dirty buckets, optional ignored-path scans through `--with-ignored`, sibling git worktrees, detached/bare state, invalid git access, planning drift, checkpoint existence, lifecycle state, and repo-local runtime worktree directories.
+- Read optional annotations from `.planning/.local/control-map.annotations.json`. Annotations may record `runtime_owner`, intended scope, write set, cleanup state, proof state, next step, branch, and last known head.
+- Treat annotations as stale-checkable intent only. They never outrank repo truth, planning artifacts, or checkpoint reconciliation.
+- Keep transcript/session stores out of the helper. Vendor session evidence may support postmortems, but it is not live product truth.
+- Wire the control map into portable workflow behavior by having `progress`, `resume`, `pause`, `quick`, `plan`, and `execute` consult it when available. This is guidance plus deterministic helper output, not a new workflow lane.
+
+**Leverage:**
+- Lost: a pure zero-file model cannot preserve non-computable intent such as owner/runtime, intended scope, and cleanup obligation.
+- Kept: Workspine remains a lightweight repo-native spine; no new lifecycle workflow, no dashboard/control plane, no vendor session authority, and no change to the five evidence kinds.
+- Gained: agents can explain "clean" precisely across tracked, untracked, sibling, detached, stale, and annotated state by default, and across ignored/generated local surfaces when the caller requests the explicit `--with-ignored` scan before planning, execution, resume, cleanup, or milestone continuation.
+
+**Evidence:**
+- `bin/lib/control-map.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs`
+- `distilled/workflows/progress.md`, `resume.md`, `pause.md`, `quick.md`, `plan.md`, `execute.md`
+- `tests/gsdd.control-map.test.cjs`
+- `.internal-research/gaps.md` Gap I52 and Gap I54
+- `.internal-research/lessons-learned.md` entries on multi-worktree registry, clean-vs-editor-visible noise, checkpoint/worktree truth split, and subagent stop conditions
+- GSD comparison: upstream GSD preserves lifecycle rigor but does not define a vendor-agnostic computed worktree/control-map helper.
+- OpenSpec comparison: OpenSpec optimizes change-level speed and archive flow, but does not own long-running multi-worktree local-state reconciliation as a portable harness surface.
+- Harness sources: `https://www.anthropic.com/engineering/harness-design-long-running-apps`, `https://code.claude.com/docs/en/worktrees`, `https://developers.openai.com/codex/cloud`, `https://developers.openai.com/api/docs/guides/agents/orchestration`, `https://developers.openai.com/api/docs/guides/agents/guardrails-approvals`, `https://developers.openai.com/api/docs/guides/agent-evals`, `https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent`, `https://agent-browser.dev/sessions`, and `https://developer.chrome.com/docs/devtools/agents`.
+
+**Consequences:**
+- Future cleanup, resume, and parallel-worktree work should start from `gsdd control-map --json` rather than repeated ad hoc repo audits; use `--with-ignored` before making a clean-workspace claim that includes ignored or generated surfaces.
+- A future mutation command may update annotations, but the current helper intentionally stays computed/read-first and safe to call from status surfaces.
+- Future health or preflight hardening can consume the same helper output for stricter blocking, but must avoid turning local annotations into product truth.
 
 ---
 

package/distilled/EVIDENCE-INDEX.md

@@ -491,6 +491,29 @@
 - `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
+
+## D63 — Computed-First Control Map
+- `bin/lib/control-map.mjs`, `bin/gsdd.mjs`, `bin/lib/rendering.mjs`
+- `distilled/workflows/progress.md`, `resume.md`, `pause.md`, `quick.md`, `plan.md`, `execute.md`
+- `tests/gsdd.control-map.test.cjs`
+- `.internal-research/gaps.md` Gap I52 and Gap I54
+- `.internal-research/lessons-learned.md` multi-worktree registry, clean-vs-editor-visible noise, checkpoint/worktree truth split, and subagent stop-condition lessons
+- GSD comparison: upstream GSD lifecycle rigor does not include a vendor-agnostic computed worktree/control-map helper
+- OpenSpec comparison: OpenSpec change archive flow does not own long-running multi-worktree local-state reconciliation as a portable harness surface
+- Harness sources: https://www.anthropic.com/engineering/harness-design-long-running-apps, https://code.claude.com/docs/en/worktrees, https://developers.openai.com/codex/cloud, https://developers.openai.com/api/docs/guides/agents/orchestration, https://developers.openai.com/api/docs/guides/agents/guardrails-approvals, https://developers.openai.com/api/docs/guides/agent-evals, https://docs.github.com/en/copilot/concepts/agents/cloud-agent/about-cloud-agent, https://agent-browser.dev/sessions, https://developer.chrome.com/docs/devtools/agents
 
 ---
 

package/distilled/README.md

@@ -71,6 +71,14 @@ npx -y gsdd-cli init       -> bootstrap (create .planning/, copy templates, gene
 /gsdd-progress             -> show status, route to next action
 ```
 
+The main operator spine is four workflow moves after bootstrap: `new-project -> plan -> execute -> verify`. The other public workflow surfaces are support lanes for milestone closeout, quick work, progress, pause/resume, and brownfield orientation.
+
+Helper command for long-running sessions:
+
+```
+npx -y gsdd-cli control-map [--json] [--with-ignored] -> computed repo/worktree/planning state plus local annotations
+```
+
 ## Brownfield Entry Contract
 
 Use the same three-way routing everywhere:
@@ -101,6 +109,7 @@ Use the same three-way routing everywhere:
 Architecture notes:
 - `bin/gsdd.mjs` remains the thin generator entrypoint, while vendor-specific rendering lives in adapter modules.
 - Codex CLI uses the always-generated `.agents/skills/gsdd-*` surface as its entry path, relies on `.planning/bin/gsdd.mjs` for deterministic helper calls, and can add a native `.codex/agents/gsdd-plan-checker.toml` checker agent.
+- `control-map` is a helper command, not a lifecycle workflow: it computes repo/worktree/planning truth first and treats `.planning/.local/` annotations as local intent only.
 - Codex VS Code/app are separate surfaces from Codex CLI; do not claim the CLI proof for them unless they expose compatible skill discovery. Fallback is opening or pasting the generated `SKILL.md`.
 - `npx -y gsdd-cli health` now compares any installed generated runtime surfaces against current render output and routes repairs back through `npx -y gsdd-cli update`.
 - Portable lifecycle contracts now align to the roadmap template status grammar: `[ ]`, `[-]`, `[x]`.

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: