create-harness-vibe-coding 0.8.16 → 0.8.18

package/templates/common/Harness/scripts/validate-harness.mjs

@@ -15,6 +15,33 @@ Literal explanatory {{...}} text is allowed.`);
   process.exit(0);
 }
 
+let commandSurfaceLoadError = null;
+
+function loadCommandSurface() {
+  const rel = path.join(root, 'Harness', 'specs', 'runtime', 'command-surface.json');
+  try {
+    const parsed = JSON.parse(fs.readFileSync(rel, 'utf8'));
+    if (!parsed || parsed.schemaVersion !== 1 || !Array.isArray(parsed.commands)) {
+      commandSurfaceLoadError = 'Harness/specs/runtime/command-surface.json must have schemaVersion 1 and commands[]';
+      return { commands: [] };
+    }
+    return parsed;
+  } catch (err) {
+    commandSurfaceLoadError = `Harness/specs/runtime/command-surface.json is not valid JSON: ${err.message}`;
+    return { commands: [] };
+  }
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort();
+}
+
+const commandSurface = loadCommandSurface();
+const commandDefinitions = commandSurface.commands;
+const commandSkillNames = commandDefinitions
+  .filter(command => command.surfaces?.claudeSkill || command.surfaces?.codexSkill)
+  .map(command => command.id);
+
 const commonAgents = [
   'task-scribe',
   'codebase-explorer',
@@ -37,33 +64,26 @@ const commonAgents = [
 ];
 
 const commonSkills = [
-  'wf',
   'tdd',
-  'wf-update',
-  'wf-max',
-  'wf-review',
-  'wf-learn',
   'subagent-orchestrator',
-  'wf-readme',
   'wf-agents-docs',
-  'wf-remove',
-  'wf-auto',
-  'wf-auto-spark',
+  ...commandSkillNames,
 ];
 
-const opencodeWorkflowCommands = [
-  'wf',
-  'wf-max',
-  'wf-auto',
-  'wf-auto-spark',
-  'wf-learn',
-  'wf-review',
-  'wf-readme',
-  'wf-remove',
-];
+const workflowCommands = commandDefinitions
+  .filter(command => command.classification === 'workflow' && command.surfaces?.claudeCommand)
+  .map(command => command.id);
+
+const directCommands = commandDefinitions
+  .filter(command => command.classification === 'direct')
+  .map(command => command.id);
+
+const opencodeWorkflowCommands = commandDefinitions
+  .filter(command => command.classification === 'workflow' && command.surfaces?.opencodeCommand)
+  .map(command => command.id);
 
 const cacheDisciplinedSkills = commonSkills.filter(skill => (
-  skill === 'subagent-orchestrator' || skill.startsWith('wf')
+  skill === 'subagent-orchestrator' || skill === 'wf-agents-docs' || workflowCommands.includes(skill)
 ));
 
 const memoryFiles = [
@@ -95,13 +115,15 @@ const required = [
   'Harness/templates/VALIDATION_REPORT.template.md',
   ...memoryFiles,
   '.codex/config.toml',
+  '.codex/hooks.json',
   'opencode.json',
   '.claude/settings.json',
-  '.claude/commands/wf-help.md',
-  '.claude/commands/wf-update.md',
-  '.opencode/commands/wf-help.md',
-  '.opencode/commands/wf-update.md',
-  ...opencodeWorkflowCommands.map(command => `.opencode/commands/${command}.md`),
+  ...commandDefinitions
+    .filter(command => command.surfaces?.claudeCommand)
+    .map(command => `.claude/commands/${command.id}.md`),
+  ...commandDefinitions
+    .filter(command => command.surfaces?.opencodeCommand)
+    .map(command => `.opencode/commands/${command.id}.md`),
   '.opencode/plugins/harness-wf-status.mjs',
   '.claude/rules/ecc/common.md',
   ...commonAgents.map(agent => `.claude/agents/${agent}.md`),
@@ -117,6 +139,7 @@ const required = [
   'Harness/specs/runtime/dispatch.md',
   'Harness/specs/guides/extension.md',
   'Harness/specs/runtime/context-loading.md',
+  'Harness/specs/runtime/command-surface.json',
   'Harness/ownership.manifest.json',
   'Harness/specs/workflows/WF-KERNEL.md',
   'Harness/specs/runtime/agent-workflow.md',
@@ -129,6 +152,7 @@ const required = [
   'Harness/scripts/wf-update-check.mjs',
   'Harness/scripts/wf-remove.mjs',
   'Harness/scripts/scan-clean.mjs',
+  'Harness/scripts/task-state.mjs',
   'Harness/scripts/archive-tasks.mjs',
   'Harness/specs/workflows/WF-STATE.md',
   'Harness/specs/protocols/TASK_ARCHIVE.md',
@@ -196,6 +220,48 @@ function read(rel) {
   return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
 }
 
+function readJson(rel) {
+  const body = read(rel);
+  if (!body) return null;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+
+function sameResolvedPath(a, b) {
+  if (!a || !b) return false;
+  const resolvedA = path.resolve(a);
+  const resolvedB = path.resolve(b);
+  return process.platform === 'win32'
+    ? resolvedA.toLowerCase() === resolvedB.toLowerCase()
+    : resolvedA === resolvedB;
+}
+
+function isGlobalRuntimeProjectStatePath(rel) {
+  return rel === 'Harness/PROGRESS.md'
+    || rel === 'Harness/tasks'
+    || rel.startsWith('Harness/tasks/')
+    || rel === 'Harness/research'
+    || rel.startsWith('Harness/research/')
+    || rel === 'Harness/project'
+    || rel.startsWith('Harness/project/');
+}
+
+function validateRequiredFiles(files, label = 'file') {
+  for (const rel of files) {
+    if (!fs.existsSync(path.join(root, rel))) {
+      errors.push(`missing required ${label}: ${rel}`);
+    }
+  }
+}
+
+function resolveMetadataPath(value) {
+  if (!value || typeof value !== 'string') return '';
+  return path.isAbsolute(value) ? value : path.resolve(root, value);
+}
+
 function requireText(rel, text, label = text) {
   const body = read(rel);
   if (body && !body.includes(text)) errors.push(`${rel} missing ${label}`);
@@ -206,6 +272,173 @@ function forbidText(rel, text, label = text) {
   if (body && body.includes(text)) errors.push(`${rel} contains forbidden ${label}`);
 }
 
+const installMetadata = readJson('Harness/.harness-version');
+const isGlobalInstall = installMetadata?.installScope === 'global';
+const isGlobalRuntimeRoot = isGlobalInstall && sameResolvedPath(root, installMetadata.globalDir);
+const isGlobalProjectBridge = isGlobalInstall && !isGlobalRuntimeRoot;
+
+function finishValidation() {
+  if (errors.length) {
+    console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);
+    for (const error of errors) console.error(`- ${error}`);
+    process.exit(1);
+  }
+
+  console.log(`Harness validation passed${strict ? ' (strict)' : ''}.`);
+  if (!strict) {
+    console.log('Tip: run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap to check unresolved project placeholders.');
+  }
+}
+
+function validateHostGlobalTargets() {
+  if (!isGlobalInstall) return;
+
+  if (installMetadata?.copyMode !== 'copy') {
+    errors.push('Harness/.harness-version global install metadata must use copyMode "copy"');
+  }
+
+  const hostGlobal = installMetadata?.hostGlobal;
+  if (!hostGlobal || hostGlobal.copyMode !== 'copy' || !hostGlobal.targets || typeof hostGlobal.targets !== 'object') {
+    errors.push('Harness/.harness-version missing hostGlobal copy targets');
+    return;
+  }
+
+  const minimumFiles = {
+    claude: ['commands/wf.md', 'skills/wf/SKILL.md'],
+    codex: ['skills/wf/SKILL.md'],
+    opencode: ['commands/wf.md'],
+  };
+
+  for (const [host, requiredFiles] of Object.entries(minimumFiles)) {
+    const target = hostGlobal.targets[host];
+    if (!target || typeof target !== 'object') {
+      errors.push(`Harness/.harness-version missing hostGlobal target: ${host}`);
+      continue;
+    }
+
+    const hostRoot = resolveMetadataPath(target.root);
+    if (!hostRoot) {
+      errors.push(`Harness/.harness-version hostGlobal ${host} missing root`);
+      continue;
+    }
+
+    const files = Array.isArray(target.files) ? target.files : [];
+    for (const requiredFile of requiredFiles) {
+      if (!files.includes(requiredFile)) {
+        errors.push(`Harness/.harness-version hostGlobal ${host} missing required file target: ${requiredFile}`);
+      }
+    }
+
+    for (const file of files) {
+      if (typeof file !== 'string' || path.isAbsolute(file) || file.split('/').includes('..')) {
+        errors.push(`Harness/.harness-version hostGlobal ${host} has invalid relative file target: ${String(file)}`);
+        continue;
+      }
+      const filePath = path.join(hostRoot, ...file.split('/'));
+      let stat;
+      try {
+        stat = fs.lstatSync(filePath);
+        if (stat.isSymbolicLink()) {
+          errors.push(`host-global ${host} copied file is a symlink, not a real copy: ${file}`);
+          continue;
+        }
+        if (!stat.isFile()) {
+          errors.push(`host-global ${host} copied file is not a regular file: ${file}`);
+          continue;
+        }
+      } catch {
+        errors.push(`missing host-global ${host} copied file: ${file}`);
+        continue;
+      }
+    }
+  }
+}
+
+function validateGlobalRuntimeRoot() {
+  validateCommandSurface();
+  validateRequiredFiles(required.filter(rel => !isGlobalRuntimeProjectStatePath(rel)), 'global-runtime file');
+
+  for (const rel of ['Harness/PROGRESS.md', 'Harness/tasks', 'Harness/research', 'Harness/project']) {
+    if (fs.existsSync(path.join(root, rel))) {
+      errors.push(`global runtime must not contain project-local state: ${rel}`);
+    }
+  }
+
+  if (installMetadata?.projectState?.tasks !== 'Harness/tasks/') {
+    errors.push('Harness/.harness-version global runtime metadata must keep projectState.tasks project-local');
+  }
+  if (installMetadata?.projectState?.progress !== 'Harness/PROGRESS.md') {
+    errors.push('Harness/.harness-version global runtime metadata must keep projectState.progress project-local');
+  }
+  if (installMetadata?.settingsScopes?.precedence?.join('>') !== 'project>global') {
+    errors.push('Harness/.harness-version global runtime metadata must define project>global settings precedence');
+  }
+
+  validateHostGlobalTargets();
+  requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Project/Global Settings Boundary', 'project/global settings boundary section');
+  requireText('Harness/specs/guides/SETUP.md', 'copy Claude Code, Codex, and OpenCode command/skill surfaces', 'setup three-host global copy');
+
+  finishValidation();
+  process.exit(0);
+}
+
+function validateGlobalProjectBridge() {
+  const bridgeRequired = [
+    'AGENTS.md',
+    'CLAUDE.md',
+    'Harness/README.md',
+    'Harness/MEMORY.md',
+    'Harness/settings.json',
+    'Harness/specs/guides/SETUP.md',
+    'Harness/.harness-version',
+    'Harness/PROGRESS.md',
+    'Harness/research/README.md',
+    'Harness/research/PRD.md',
+    'Harness/research/research-results.md',
+    'Harness/project/architecture.md',
+    ...memoryFiles,
+  ];
+
+  for (const rel of bridgeRequired) {
+    if (!fs.existsSync(path.join(root, rel))) {
+      errors.push(`missing required global-project-bridge file: ${rel}`);
+    }
+  }
+
+  const taskTemplateDir = path.join(root, 'Harness', 'tasks', '_template');
+  if (!fs.existsSync(taskTemplateDir)) {
+    errors.push('missing directory: Harness/tasks/_template/');
+  } else {
+    for (const f of ['PROGRESS.md', 'PLAN.md']) {
+      if (!fs.existsSync(path.join(taskTemplateDir, f))) {
+        errors.push(`missing task template file: Harness/tasks/_template/${f}`);
+      }
+    }
+  }
+
+  requireText('CLAUDE.md', 'global Harness runtime', 'global runtime bridge pointer');
+  requireText('Harness/README.md', 'Never discover task context from the global runtime', 'project-local task authority');
+  requireText('Harness/specs/guides/SETUP.md', 'Read the full setup guide from', 'global setup bridge pointer');
+  requireText('Harness/MEMORY.md', 'Global memory lives under', 'global memory bridge pointer');
+  validateHostGlobalTargets();
+
+  finishValidation();
+  process.exit(0);
+}
+
+function activeToml(rel) {
+  return read(rel)
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'))
+    .join('\n');
+}
+
+function forbidActiveToml(rel, pattern, label) {
+  const body = activeToml(rel);
+  if (body && pattern.test(body)) errors.push(`${rel} contains active forbidden ${label}`);
+}
+
 function frontmatterField(text, field) {
   const match = text.match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
   return match ? match[1].trim() : '';
@@ -234,6 +467,35 @@ function listMarkdownFiles(rel) {
 const TASK_NAME_RE = /^task-[a-z]+(-[a-z0-9]+){1,4}$/;
 const TASK_NAME_MAX = 46; // "task-" (5) + ≤40 chars body + 1 safety = 46
 const TASK_RESERVED = new Set(['_template', 'auto', '_archive']);
+const TASK_SAFE_ARCHIVE_STATUSES = new Set(['complete', 'verified', 'archived', 'abandoned', 'obsolete', 'done', 'closed', 'closeout']);
+const TASK_NEVER_ARCHIVE_STATUSES = new Set(['active', 'blocked', 'in_progress', 'running', 'pending', 'needs-user-decision']);
+const TASK_PHASE_ALIASES = new Map([
+  ['implementation', 'implement'],
+  ['build', 'implement'],
+  ['validation', 'verify'],
+  ['complete', 'verified'],
+  ['done', 'verified'],
+  ['closed', 'closeout'],
+]);
+const TASK_STATUS_ALIASES = new Map([
+  ['in-progress', 'in_progress'],
+  ['inprogress', 'in_progress'],
+  ['needs_user_decision', 'needs-user-decision'],
+  ['needs-user', 'needs-user-decision'],
+]);
+const TASK_VALID_PHASES = new Set([
+  'intake', 'clarify', 'requirements', 'prd', 'acceptance', 'plan', 'explore',
+  'implement', 'verify', 'review', 'fix', 'reflect', 'closeout', 'blocked',
+  'archived', 'verified',
+]);
+const TASK_VALID_STATUSES = new Set([...TASK_SAFE_ARCHIVE_STATUSES, ...TASK_NEVER_ARCHIVE_STATUSES, 'skipped', 'failed']);
+const VALID_TASK_CAPSULE_POLICIES = new Set([
+  'none',
+  'required',
+  'auto-capsule-required',
+  'use-current-or-create-when-needed',
+  'creates-or-updates',
+]);
 
 function validateTaskName(name, strict) {
   if (TASK_RESERVED.has(name)) return null;
@@ -250,6 +512,57 @@ function validateTaskName(name, strict) {
   return null;
 }
 
+function normalizeTaskToken(value, validSet, aliasMap) {
+  if (value === null || value === undefined) return '';
+  const raw = String(value).trim().toLowerCase();
+  if (!raw) return '';
+  const compact = raw.replace(/\s+/g, '-');
+  const direct = aliasMap.get(compact) || compact;
+  if (validSet.has(direct)) return direct;
+  const tokens = raw
+    .replace(/[`*_()[\]{}:]/g, ' ')
+    .replace(/[^a-z0-9_-]+/g, ' ')
+    .split(/\s+/)
+    .map(token => token.trim())
+    .filter(Boolean);
+  for (const token of tokens) {
+    const canonical = aliasMap.get(token) || token;
+    if (validSet.has(canonical)) return canonical;
+  }
+  return '';
+}
+
+function normalizeTaskStatus(value) {
+  return normalizeTaskToken(value, TASK_VALID_STATUSES, TASK_STATUS_ALIASES);
+}
+
+function normalizeTaskPhase(value) {
+  return normalizeTaskToken(value, TASK_VALID_PHASES, TASK_PHASE_ALIASES);
+}
+
+function taskStateIssue(message) {
+  if (strict) errors.push(message);
+  else console.warn(`Warning: ${message}`);
+}
+
+function parseRootTaskProgress(text) {
+  const activeMatch = text.match(/## Active Task\s*\r?\n+(?:\s*\r?\n)?\s*-\s*([^\r\n]+)/);
+  const rawActive = activeMatch ? activeMatch[1].trim() : '';
+  const activeTask = rawActive && !/^none$/i.test(rawActive) ? rawActive : null;
+  const rows = [];
+  const taskIndexMatch = text.match(/## Task Index\s*\r?\n([\s\S]*?)(?=\r?\n## |\s*$)/);
+  if (taskIndexMatch) {
+    for (const line of taskIndexMatch[1].split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('|')) continue;
+      if (/^\|\s*-+/.test(trimmed) || /^\|\s*ID\s*\|/i.test(trimmed)) continue;
+      const cells = trimmed.split('|').slice(1, -1).map(cell => cell.trim());
+      if (cells.length >= 4 && cells[0]) rows.push({ id: cells[0], phase: cells[2] });
+    }
+  }
+  return { activeTask, rows };
+}
+
 function unresolvedTemplatePlaceholders(text) {
   const placeholders = [];
   const pattern = /\{\{([^{}\r\n]+)\}\}/g;
@@ -291,13 +604,12 @@ function registeredWorkflowFiles(...texts) {
 
 function listedWorkflowCommands(...texts) {
   const commands = new Set();
-  const pattern = /`\/(wf(?:-[a-z0-9]+)?)(?:\s+[^`]*)?`/g;
+  const pattern = /`\/(wf(?:-[a-z0-9]+)*)(?:\s+[^`]*)?`/g;
 
   for (const text of texts) {
     for (const match of text.matchAll(pattern)) {
       const command = `/${match[1]}`;
       if (command === '/wf-help') continue;
-      if (command === '/wf-browser') continue; // optional workflow, not a required skill
       commands.add(command);
     }
   }
@@ -305,12 +617,153 @@ function listedWorkflowCommands(...texts) {
   return [...commands].sort();
 }
 
-for (const rel of required) {
-  if (!fs.existsSync(path.join(root, rel))) {
-    errors.push(`missing required file: ${rel}`);
+function extractStringArray(text, name) {
+  const match = text.match(new RegExp(`const ${name} = \\[([\\s\\S]*?)\\];`));
+  if (!match) return null;
+  return new Set([...match[1].matchAll(/'([^']+)'/g)].map(item => item[1]));
+}
+
+function expectedCommandAliases(id) {
+  return [`/${id}`, `$${id}`, `/skills ${id}`];
+}
+
+function validateCommandSurface() {
+  if (commandSurfaceLoadError) {
+    errors.push(commandSurfaceLoadError);
+    return;
+  }
+
+  const seen = new Set();
+  const claudeRouter = read('CLAUDE.md');
+  const readmeRouter = read('Harness/README.md');
+  const ecc = read('.claude/rules/ecc/common.md');
+  const eccExemptionLine = ecc.split(/\r?\n/).find(line => line.includes('excluding')) || '';
+  const claudeHelp = read('.claude/commands/wf-help.md');
+  const opencodeHelp = read('.opencode/commands/wf-help.md');
+  const removeScript = read('Harness/scripts/wf-remove.mjs');
+  const removeSkillRegistry = extractStringArray(removeScript, 'BUILT_IN_SKILL_NAMES');
+  const removeCommandRegistry = extractStringArray(removeScript, 'BUILT_IN_COMMAND_NAMES');
+  const cleanupDirs = extractStringArray(removeScript, 'CLEANUP_DIRS');
+
+  if (!removeSkillRegistry) errors.push('Harness/scripts/wf-remove.mjs missing BUILT_IN_SKILL_NAMES registry');
+  if (!removeCommandRegistry) errors.push('Harness/scripts/wf-remove.mjs missing BUILT_IN_COMMAND_NAMES registry');
+  if (!cleanupDirs) errors.push('Harness/scripts/wf-remove.mjs missing CLEANUP_DIRS registry');
+
+  for (const command of commandDefinitions) {
+    const id = command?.id;
+    const surfaces = command?.surfaces || {};
+    if (!id || !/^wf(?:-[a-z0-9]+)*$/.test(id)) {
+      errors.push(`command-surface has invalid command id: ${JSON.stringify(id)}`);
+      continue;
+    }
+    if (seen.has(id)) errors.push(`command-surface duplicate command id: ${id}`);
+    seen.add(id);
+
+    if (!['direct', 'workflow'].includes(command.classification)) {
+      errors.push(`command-surface ${id} has invalid classification: ${JSON.stringify(command.classification)}`);
+    }
+    if (command.entersWf !== (command.classification === 'workflow')) {
+      errors.push(`command-surface ${id} entersWf must match classification`);
+    }
+
+    for (const alias of expectedCommandAliases(id)) {
+      if (!Array.isArray(command.aliases) || !command.aliases.includes(alias)) {
+        errors.push(`command-surface ${id} missing alias ${alias}`);
+      }
+    }
+
+    const claudeCommand = `.claude/commands/${id}.md`;
+    const opencodeCommand = `.opencode/commands/${id}.md`;
+    const claudeSkill = `.claude/skills/${id}/SKILL.md`;
+    const codexSkill = `.agents/skills/${id}/SKILL.md`;
+
+    if (surfaces.claudeCommand && !fs.existsSync(path.join(root, claudeCommand))) {
+      errors.push(`command-surface ${id} missing Claude command: ${claudeCommand}`);
+    }
+    if (surfaces.opencodeCommand && !fs.existsSync(path.join(root, opencodeCommand))) {
+      errors.push(`command-surface ${id} missing OpenCode command: ${opencodeCommand}`);
+    }
+    if (surfaces.claudeSkill && !fs.existsSync(path.join(root, claudeSkill))) {
+      errors.push(`command-surface ${id} missing Claude skill: ${claudeSkill}`);
+    }
+    if (surfaces.codexSkill && !fs.existsSync(path.join(root, codexSkill))) {
+      errors.push(`command-surface ${id} missing Codex skill: ${codexSkill}`);
+    }
+    if (surfaces.helpRow) {
+      const rowMarker = `| \`/${id}`;
+      if (!claudeHelp.includes(rowMarker)) errors.push(`.claude/commands/wf-help.md missing command-surface help row for /${id}`);
+      if (!opencodeHelp.includes(rowMarker)) errors.push(`.opencode/commands/wf-help.md missing command-surface help row for /${id}`);
+    }
+
+    if (command.classification === 'direct') {
+      for (const alias of command.aliases || []) {
+        if (!claudeRouter.includes(`\`${alias}\``)) errors.push(`CLAUDE.md missing direct/compat alias ${alias}`);
+        if (!readmeRouter.includes(alias)) errors.push(`Harness/README.md missing direct/compat alias ${alias}`);
+        if (!eccExemptionLine.includes(`\`${alias}\``)) errors.push(`.claude/rules/ecc/common.md missing ECC direct command exemption ${alias}`);
+      }
+      for (const rel of [claudeCommand, opencodeCommand]) {
+        const text = read(rel);
+        if (text && id !== 'wf-help') {
+          if (!/direct command/i.test(text)) errors.push(`${rel} missing DIRECT command classification`);
+          if (!text.includes('Do not invoke a skill')) errors.push(`${rel} missing direct no-skill boundary`);
+        }
+      }
+    }
+
+    if (command.classification === 'workflow') {
+      for (const alias of command.aliases || []) {
+        if (eccExemptionLine.includes(`\`${alias}\``)) {
+          errors.push(`.claude/rules/ecc/common.md incorrectly exempts workflow command ${alias}`);
+        }
+      }
+      for (const rel of [claudeCommand, opencodeCommand]) {
+        const text = read(rel);
+        if (!text) continue;
+        if (!text.includes('workflow command')) errors.push(`${rel} missing workflow command classification`);
+        if (!text.includes('Harness/MEMORY.md')) errors.push(`${rel} missing workflow router load`);
+      }
+    }
+
+    if (['wf', 'wf-max', 'wf-command-create'].includes(id)) {
+      const text = `${read(claudeCommand)}\n${read(claudeSkill)}`;
+      if (!text.includes('task capsule')) errors.push(`${id} missing required task capsule instruction`);
+      if (!text.includes('task-<verb>-<noun>')) errors.push(`${id} missing task id convention`);
+    }
+
+    if (surfaces.claudeSkill || surfaces.codexSkill) {
+      if (removeSkillRegistry && !removeSkillRegistry.has(id)) {
+        errors.push(`Harness/scripts/wf-remove.mjs BUILT_IN_SKILL_NAMES missing ${id}`);
+      }
+      if (cleanupDirs) {
+        if (!cleanupDirs.has(`.claude/skills/${id}`)) errors.push(`Harness/scripts/wf-remove.mjs CLEANUP_DIRS missing .claude/skills/${id}`);
+        if (!cleanupDirs.has(`.agents/skills/${id}`)) errors.push(`Harness/scripts/wf-remove.mjs CLEANUP_DIRS missing .agents/skills/${id}`);
+      }
+    }
+    if ((surfaces.claudeCommand || surfaces.opencodeCommand) && removeCommandRegistry && !removeCommandRegistry.has(id)) {
+      errors.push(`Harness/scripts/wf-remove.mjs BUILT_IN_COMMAND_NAMES missing ${id}`);
+    }
+  }
+
+  // Validate taskCapsulePolicy enum
+  for (const cmd of commandDefinitions) {
+    if (!cmd.taskCapsulePolicy || !VALID_TASK_CAPSULE_POLICIES.has(cmd.taskCapsulePolicy)) {
+      errors.push(`command-surface ${cmd.id}: invalid taskCapsulePolicy "${cmd.taskCapsulePolicy}". Valid: ${[...VALID_TASK_CAPSULE_POLICIES].join(', ')}`);
+    }
   }
 }
 
+if (isGlobalRuntimeRoot) {
+  validateGlobalRuntimeRoot();
+}
+
+if (isGlobalProjectBridge) {
+  validateGlobalProjectBridge();
+}
+
+validateCommandSurface();
+
+validateRequiredFiles(required);
+
 for (const rel of legacyRootSpecDocs) {
   if (fs.existsSync(path.join(root, rel))) {
     errors.push(`legacy root Harness spec doc should be migrated to Harness/specs/**: ${rel}`);
@@ -433,6 +886,14 @@ requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Memory Candidate Dete
 requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'explicit user preference', 'explicit user preference immediate write rule');
 requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Memory Routing (L3)', 'memory routing section');
 requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Scenario pack', 'route scoring scenario pack');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Project/Global Memory Boundary', 'project/global memory boundary section');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Harness/tasks/` and `Harness/PROGRESS.md` are always project-local', 'global install keeps task state project-local');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Project memory lives in `Harness/memory/`', 'project memory scope rule');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Global memory must never store project task state', 'global memory task-state exclusion');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Project/Global Settings Boundary', 'project/global settings boundary section');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Project settings live in `Harness/settings.json` and override global settings', 'project settings override global settings');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'copied, not symlinked, into Claude Code, Codex, and OpenCode', 'host-global copy mode');
+requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'Existing user-authored config, command, skill, or agent files are user-owned', 'user-owned host file rule');
 requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'same tool or command pattern fails 3+ times', 'tool reflection trigger');
 requireText('Harness/specs/protocols/MEMORY_PROTOCOL.md', 'user corrects the same assumption or preference 2+ times', 'user correction reflection trigger');
 requireText('CLAUDE.md', 'startup-hints.md', 'CLAUDE startup-hints routing');
@@ -463,7 +924,7 @@ requireText('CLAUDE.md', 'Keep intermediate user updates to 1-2 short sentences'
 requireText('.claude/rules/ecc/common.md', '## Low-Noise Progress', 'ECC low-noise progress section');
 requireText('.claude/rules/ecc/common.md', "Match the user's language for user-facing prose", 'ECC user-facing language match rule');
 requireText('.claude/rules/ecc/common.md', 'Do not recap plans, paste logs, or narrate obvious file reads', 'ECC low-noise no-recap rule');
-requireText('.claude/rules/ecc/common.md', 'excluding `/wf-help` and `/wf-update`', 'ECC direct command exemption');
+requireText('Harness/specs/runtime/command-surface.json', '"wf-command-create"', 'command surface registry wf-command-create entry');
 requireText('Harness/README.md', 'Load By Task', 'Harness task router');
 requireText('Harness/README.md', 'Need context/cache/token efficiency', 'cache/token router row');
 requireText('Harness/specs/runtime/context-loading.md', 'Context Tiers', 'context tier load budget section');
@@ -485,6 +946,12 @@ requireText('Harness/specs/runtime/subagents.md', 'Cache-first discipline', 'sub
 forbidText('CLAUDE.md', 'Harness/specs/guides/SETUP.md', 'CLAUDE.md SETUP reference');
 forbidText('CLAUDE.md', 'follow it before normal project work', 'installed-project SETUP hot-path routing');
 requireText('Harness/specs/guides/SETUP.md', 'Harness/specs/protocols/MEMORY_PROTOCOL.md', 'setup memory protocol reference');
+requireText('Harness/specs/guides/SETUP.md', '--install-scope project', 'setup project install scope');
+requireText('Harness/specs/guides/SETUP.md', '--install-scope global', 'setup global install scope');
+requireText('Harness/specs/guides/SETUP.md', '--global-dir <dir>', 'setup global dir flag');
+requireText('Harness/specs/guides/SETUP.md', '--host-global-dir <dir>', 'setup host-global dir flag');
+requireText('Harness/specs/guides/SETUP.md', 'copy Claude Code, Codex, and OpenCode command/skill surfaces', 'setup three-host global copy');
+requireText('Harness/specs/guides/SETUP.md', 'Project settings in `Harness/settings.json` override global settings defaults', 'setup settings precedence');
 requireText('Harness/specs/guides/SETUP.md', 'no startup dependency on this setup reference', 'SETUP startup boundary');
 forbidText('Harness/specs/guides/SETUP.md', 'bootstrap contract line', 'stale SETUP-to-CLAUDE bootstrap contract');
 forbidText('Harness/specs/runtime/context-loading.md', 'Always keep:', 'ambiguous always-load context rule');
@@ -582,7 +1049,7 @@ for (const command of listedWorkflowCommands(docsReadme, read('.claude/commands/
 
 for (const workflowFile of registeredWorkflowFiles(docsReadme, memory)) {
   if (!fs.existsSync(path.join(root, workflowFile))) {
-    // Optional workflows (browser-e2e, ts-react-frontend, etc.) may not be installed
+    // Optional workflows (ts-react-frontend, ui-ux-review, etc.) may not be installed
     continue;
   }
 }
@@ -602,9 +1069,14 @@ function requireUiSelectorContract(rel) {
   }
 }
 
-requireUiSelectorContract('Harness/workflows/browser-e2e.md');
+requireUiSelectorContract('.claude/skills/wf-browser/SKILL.md');
+requireUiSelectorContract('.agents/skills/wf-browser/SKILL.md');
 requireUiSelectorContract('Harness/workflows/ts-react-frontend.md');
 
+if (fs.existsSync(path.join(root, 'Harness/workflows/browser-e2e.md'))) {
+  errors.push('retired optional workflow must not exist: Harness/workflows/browser-e2e.md');
+}
+
 for (const skill of commonSkills) {
   const rel = `.claude/skills/${skill}/SKILL.md`;
   const text = read(rel);
@@ -784,28 +1256,56 @@ requireText('Harness/specs/workflows/WF-MAX.md', 'inherits the full', 'WF-MAX st
 requireText('Harness/specs/workflows/WF-MAX.md', 'Cross-CLI', 'WF-MAX cross-CLI overflow');
 requireText('Harness/specs/workflows/WF-MAX.md', 'claude -p', 'WF-MAX Claude CLI overflow');
 requireText('Harness/specs/workflows/WF-MAX.md', 'codex exec', 'WF-MAX Codex CLI overflow');
-requireText('Harness/specs/workflows/WF-MAX.md', 'agents.max_threads', 'WF-MAX Codex max_threads config');
-requireText('Harness/specs/workflows/WF-MAX.md', 'agents.max_depth', 'WF-MAX Codex max_depth config');
-requireText('Harness/specs/workflows/WF-MAX.md', 'max_threads = 12', 'WF-MAX Codex scaffold max_threads default');
-requireText('Harness/specs/workflows/WF-MAX.md', 'max_depth = 1', 'WF-MAX Codex scaffold max_depth default');
-requireText('Harness/specs/workflows/WF-MAX.md', 'Ask the user before raising', 'WF-MAX asks before raising Codex thread cap');
+requireText('Harness/specs/workflows/WF-MAX.md', 'agents.max_threads', 'WF-MAX Codex legacy max_threads alias');
+requireText('Harness/specs/workflows/WF-MAX.md', 'max_concurrent_threads_per_session', 'WF-MAX Codex concurrent thread config');
+requireText('Harness/specs/workflows/WF-MAX.md', 'Mandatory Fan-Out Contract', 'WF-MAX mandatory fan-out attempt contract');
+requireText('Harness/specs/workflows/WF-MAX.md', 'fanoutAttempted: true', 'WF-MAX records fan-out attempt');
+requireText('Harness/specs/workflows/WF-MAX.md', 'Runtime Capacity Map', 'WF-MAX runtime capacity map');
+requireText('Harness/specs/workflows/WF-MAX.md', 'CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION', 'WF-MAX Claude Code subagent cap docs');
+requireText('Harness/specs/workflows/WF-MAX.md', 'CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS', 'WF-MAX Claude Code concurrent subagent cap docs');
+requireText('Harness/specs/workflows/WF-MAX.md', 'CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH', 'WF-MAX Claude Code spawn-depth cap docs');
+requireText('Harness/specs/workflows/WF-MAX.md', 'Do not scaffold Codex scalar agent caps', 'WF-MAX Codex config compatibility guard');
+requireText('Harness/specs/workflows/WF-MAX.md', 'subagent_depth = 2', 'WF-MAX OpenCode subagent depth default');
+requireText('Harness/specs/workflows/WF-MAX.md', 'asks the user before any project/global Codex config change', 'WF-MAX asks before changing Codex config');
 requireText('Harness/specs/workflows/WF-MAX.md', 'Close completed agents', 'WF-MAX close completed agents before overflow');
 requireText('Harness/specs/workflows/WF-MAX.md', 'Codex++', 'WF-MAX forbids relying on Codex++ as stable capacity');
 requireText('Harness/specs/workflows/WF-MAX.md', 'does not authorize CEO source edits', 'WF-MAX useful-degrade CEO source-edit boundary');
 requireText('Harness/specs/workflows/WF-MAX.md', '## Cross-Task Decisions', 'WF-MAX PROGRESS heading preservation');
-requireText('.claude/skills/wf-max/SKILL.md', 'agents.max_threads', 'wf-max skill Codex thread config');
-requireText('.claude/skills/wf-max/SKILL.md', 'max_threads = 12', 'wf-max skill Codex scaffold max_threads default');
+requireText('.claude/skills/wf-max/SKILL.md', 'agents.max_concurrent_threads_per_session', 'wf-max skill Codex thread config');
+requireText('.claude/skills/wf-max/SKILL.md', 'agents.max_threads', 'wf-max skill Codex legacy alias');
+requireText('.claude/skills/wf-max/SKILL.md', 'Do not scaffold scalar `[agents]` caps', 'wf-max skill Codex config compatibility guard');
+requireText('.claude/skills/wf-max/SKILL.md', 'CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION', 'wf-max skill Claude Code subagent cap');
+requireText('.claude/skills/wf-max/SKILL.md', 'CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS', 'wf-max skill Claude Code concurrent subagent cap');
+requireText('.claude/skills/wf-max/SKILL.md', 'CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH', 'wf-max skill Claude Code spawn-depth cap');
+requireText('.claude/skills/wf-max/SKILL.md', 'subagent_depth = 2', 'wf-max skill OpenCode subagent depth default');
 requireText('.claude/skills/wf-max/SKILL.md', 'ask the user before raising', 'wf-max skill asks before raising Codex thread cap');
 requireText('.claude/skills/wf-max/SKILL.md', 'Codex++', 'wf-max skill forbids Codex++ capacity assumption');
 requireText('.claude/skills/wf-max/SKILL.md', taskIdConvention, 'wf-max skill task-id naming convention');
 requireText('.agents/skills/wf-max/SKILL.md', taskIdConvention, 'Codex wf-max skill task-id naming convention');
 requireText('.claude/skills/wf-max/SKILL.md', 'does not authorize CEO source edits', 'wf-max skill useful-degrade CEO source-edit boundary');
 requireText('.claude/skills/wf-max/SKILL.md', '## Cross-Task Decisions', 'wf-max skill PROGRESS heading preservation');
-requireText('.codex/config.toml', '[agents]', 'Codex agents config table');
-requireText('.codex/config.toml', 'max_threads = 12', 'Codex scaffold max_threads default');
-requireText('.codex/config.toml', 'max_depth = 1', 'Codex scaffold max_depth default');
+requireText('.codex/config.toml', 'intentionally avoids WF-MAX capacity defaults', 'Codex config compatibility note');
+forbidActiveToml('.codex/config.toml', /^\[agents\]$/m, 'Codex project config agents table');
+forbidActiveToml('.codex/config.toml', /^\s*max_concurrent_threads_per_session\s*=/m, 'Codex project config concurrent thread scalar');
+forbidActiveToml('.codex/config.toml', /^\s*max_depth\s*=/m, 'Codex project config max_depth scalar');
+forbidActiveToml('.codex/config.toml', /^\s*max_threads\s*=/m, 'Codex project config legacy max_threads scalar');
 requireText('opencode.json', '"$schema": "https://opencode.ai/config.json"', 'OpenCode config schema');
 requireText('opencode.json', '.claude/rules/ecc/common.md', 'OpenCode instructions reference to ECC rules');
+requireText('opencode.json', '"subagent_depth": 2', 'OpenCode WF-MAX subagent nesting depth');
+requireText('.opencode/commands/wf-max.md', 'MUST attempt native runtime subagent fan-out', 'OpenCode wf-max command fan-out attempt');
+requireText('.opencode/commands/wf-max.md', 'subagent_depth >= 2', 'OpenCode wf-max command subagent depth requirement');
+requireText('.opencode/commands/wf-max.md', 'fanoutAttempted: true', 'OpenCode wf-max command records fan-out attempt');
+requireText('.opencode/agents/explore-manager.md', 'task:', 'OpenCode explore-manager task permission');
+requireText('.opencode/agents/explore-manager.md', '"codebase-explorer": allow', 'OpenCode explore-manager child allowlist');
+requireText('.opencode/agents/explore-manager.md', '"git status*": allow', 'OpenCode explore-manager read-only git status');
+requireText('.opencode/agents/explore-manager.md', '"git diff*": allow', 'OpenCode explore-manager read-only git diff');
+forbidText('.opencode/agents/explore-manager.md', '"git *": allow', 'OpenCode explore-manager broad git permission');
+requireText('.opencode/agents/architect-manager.md', '"architect": allow', 'OpenCode architect-manager child allowlist');
+requireText('.opencode/agents/implement-manager.md', '"implementer": allow', 'OpenCode implement-manager child allowlist');
+forbidText('.opencode/agents/implement-manager.md', '"node *": allow', 'OpenCode implement-manager broad node permission');
+forbidText('.opencode/agents/implement-manager.md', '"npm *": allow', 'OpenCode implement-manager broad npm permission');
+requireText('.opencode/agents/review-manager.md', '"reviewer": allow', 'OpenCode review-manager child allowlist');
+forbidText('.opencode/agents/review-manager.md', '"node *": allow', 'OpenCode review-manager broad node permission');
 requireText('Harness/README.md', '/wf-max', 'wf max router alias');
 requireText('Harness/README.md', 'WF-MAX.md', 'WF-MAX router reference');
 requireText('Harness/README.md', 'ACCEPTANCE_PROTOCOL.md', 'acceptance protocol router reference');
@@ -893,13 +1393,14 @@ requireText('.claude/commands/wf-help.md', '| `/wf-help` |', 'wf-help command ro
 requireText('.claude/commands/wf-help.md', '| `/wf-max <task>` |', 'wf-help wf-max row');
 requireText('.claude/commands/wf-help.md', '| `/wf-auto` |', 'wf-help wf-auto row');
 requireText('.claude/commands/wf-help.md', '| `/wf-readme <task>` |', 'wf-help wf-readme row');
+forbidText('.claude/commands/wf-help.md', '.opencode/skills/', 'wf-help nonexistent OpenCode skills directory claim');
+forbidText('.opencode/commands/wf-help.md', '.opencode/skills/', 'OpenCode wf-help nonexistent skills directory claim');
 requireText('Harness/README.md', '## Direct Commands', 'direct commands section');
 requireText('Harness/README.md', '.claude/commands/wf-help.md', 'wf-help router reference');
 requireText('Harness/specs/workflows/WF-MAX.md', 'three-layer architecture', 'CLAUDE.md three-layer role architecture');
-requireText('Harness/README.md', 'no runtime hook state', 'CLAUDE no-hook role enforcement statement');
-requireText('Harness/README.md', 'no runtime hook state', 'README no-hook runtime statement');
-requireText('Harness/specs/workflows/WF-AUTO.md', 'WF-AUTO Hook Exception', 'wf-auto-only hook exception');
-requireText('Harness/specs/workflows/WF-AUTO.md', 'only `/wf-auto` may use a runtime hook', 'wf-auto-only hook boundary');
+requireText('Harness/README.md', 'role enforcement has no runtime hook state', 'CLAUDE no-hook role enforcement statement');
+requireText('Harness/specs/workflows/WF-AUTO.md', 'Runtime Hook Boundaries', 'runtime hook boundaries');
+requireText('Harness/specs/workflows/WF-AUTO.md', 'only `/wf-auto` may use a runtime hook to drive auto-optimization', 'wf-auto-only hook boundary');
 forbidText('CLAUDE.md', 'Enforced by hooks', 'WF-MAX hook enforcement claim');
 forbidText('Harness/specs/workflows/WF.md', 'MUST use at least 3 distinct role passes', 'old WF role-pass minimum');
 forbidText('Harness/specs/workflows/WF.md', 'at least three distinct role passes', 'old WF role-pass wording');
@@ -919,18 +1420,20 @@ const codexHookConfig = read('.codex/hooks.json');
 const claudeSettings = read('.claude/settings.json');
 requireText('.codex/hooks.json', '"SessionStart"', 'Codex startup-only update hook');
 requireText('.claude/settings.json', '"SessionStart"', 'Claude startup-only update hook');
-forbidText('.codex/hooks.json', 'UserPromptSubmit', 'Codex turn-by-turn update hook');
+forbidText('.codex/hooks.json', 'UserPromptSubmit', 'Codex turn-by-turn status hook');
+forbidText('.codex/hooks.json', '"Stop"', 'Codex stop status hook');
+forbidText('.codex/hooks.json', 'wf-status.mjs', 'removed Codex WF status script');
 forbidText('.claude/settings.json', 'UserPromptSubmit', 'Claude turn-by-turn update hook');
 requireText('.opencode/plugins/harness-wf-status.mjs', 'opencode.startup', 'OpenCode startup-only update check');
 forbidText('.opencode/plugins/harness-wf-status.mjs', "'chat.message'", 'OpenCode turn-by-turn update hook');
-if (codexHookConfig && !codexHookConfig.includes('wf-auto')) {
-  errors.push('.codex/hooks.json may only exist for a wf-auto hook configuration');
+if (codexHookConfig && !codexHookConfig.includes('wf-auto-update-prompt.mjs')) {
+  errors.push('.codex/hooks.json missing startup wf-auto update check');
 }
 if (claudeSettings.includes('"hooks"') && !claudeSettings.includes('wf-auto')) {
   errors.push('.claude/settings.json hooks may only be used for wf-auto');
 }
-if (read('.codex/config.toml').includes('hooks = true') && !codexHookConfig.includes('wf-auto')) {
-  errors.push('.codex/config.toml may enable hooks only with a wf-auto hook configuration');
+if (read('.codex/config.toml').includes('hooks = true') && !codexHookConfig.includes('wf-auto-update-prompt.mjs')) {
+  errors.push('.codex/config.toml may enable hooks only with a Harness hook configuration');
 }
 
 // AGENTS.md must be a thin shim — no Harness/WF-MAX/command table content
@@ -966,6 +1469,17 @@ requireText('.claude/skills/wf-auto/SKILL.md', 'Harness/tasks/auto/PROGRESS.md',
 requireText('.claude/skills/wf-auto/SKILL.md', 'evidence ledger path/summary', 'wf-auto skill return evidence ledger path');
 if (fs.existsSync(path.join(root, '.claude/skills/wf-browser/SKILL.md'))) {
   requireText('.claude/skills/wf-browser/SKILL.md', 'Cache Discipline', 'wf-browser skill cache discipline');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'Browser Evidence Contract', 'wf-browser browser evidence contract');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'Controllable UI Contract', 'wf-browser controllable UI contract');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'Browser Use CLI', 'wf-browser current Browser Use CLI guidance');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'browser-use --doctor', 'wf-browser Browser Use doctor command');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'browser-use skill', 'wf-browser Browser Use skill command');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'new_tab("https://example.com")', 'wf-browser Browser Use script-style example');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'capture_screenshot', 'wf-browser Browser Use screenshot helper');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'old `browser-use open/state/click/screenshot/input/wait` subcommands are removed', 'wf-browser removed old Browser Use subcommands');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'data-testid', 'wf-browser data-testid guidance');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'accessible labels/roles', 'wf-browser accessible selector guidance');
+  requireText('.claude/skills/wf-browser/SKILL.md', 'inputs, buttons, filters, rows, empty/error/loading states', 'wf-browser controllable UI coverage targets');
 }
 
 // Direct command checks
@@ -988,8 +1502,9 @@ for (const rel of ['.claude/commands/wf-update.md', '.opencode/commands/wf-updat
 requireText('Harness/scripts/wf-update-check.mjs', 'releaseHighlights', 'wf-update-check release highlights metadata');
 requireText('Harness/scripts/wf-update-check.mjs', 'updateReportRequired', 'wf-update-check user update report requirement');
 requireText('.claude/commands/wf-help.md', 'direct command', 'wf-help wf-update direct command classification');
-requireText('.claude/commands/wf-help.md', '/wf-browser', 'wf-help optional browser workflow row');
-requireText('.opencode/commands/wf-help.md', '/wf-browser', 'OpenCode wf-help optional browser workflow row');
+requireText('.claude/commands/wf-help.md', '$wf-help', 'wf-help Codex compatibility usage');
+requireText('.claude/commands/wf-help.md', '/wf-browser', 'wf-help built-in browser workflow row');
+requireText('.opencode/commands/wf-help.md', '/wf-browser', 'OpenCode wf-help built-in browser workflow row');
 
 // wf-update skill must NOT claim Claude Code /wf-update as a skill invocation
 // (allow mentions in the description/body that say "direct command" — those are correct)
@@ -1080,23 +1595,78 @@ requireText('CLAUDE.md', 'Harness/specs/workflows/WF-STATE.md', 'CLAUDE.md WF-ST
 requireText('CLAUDE.md', 'Harness/specs/protocols/TASK_ARCHIVE.md', 'CLAUDE.md TASK_ARCHIVE routing');
 requireText('Harness/README.md', 'WF-STATE.md', 'README WF-STATE routing');
 requireText('Harness/specs/protocols/TASK_ARCHIVE.md', 'archive-tasks.mjs', 'TASK_ARCHIVE script reference');
+requireText('Harness/specs/workflows/WF-STATE.md', 'task-state.mjs', 'WF-STATE task-state script contract');
+requireText('Harness/specs/protocols/TASK_ARCHIVE.md', 'task-state.mjs', 'TASK_ARCHIVE task-state script reference');
+
+// Task-state consistency: prompt text is not authoritative for machine state.
+const rootTaskProgress = parseRootTaskProgress(read('Harness/PROGRESS.md'));
+const outerTaskSet = new Set(taskDirs.filter(name => !TASK_RESERVED.has(name) && !name.startsWith('_')));
+const rootTaskRows = new Set(rootTaskProgress.rows.map(row => row.id));
+
+if (rootTaskProgress.activeTask && !outerTaskSet.has(rootTaskProgress.activeTask)) {
+  taskStateIssue(`Harness/PROGRESS.md Active Task "${rootTaskProgress.activeTask}" does not exist under Harness/tasks/`);
+}
+
+for (const row of rootTaskProgress.rows) {
+  if (!outerTaskSet.has(row.id)) {
+    taskStateIssue(`Harness/PROGRESS.md Task Index row has no outer task directory: ${row.id}`);
+  }
+  if (row.phase && !normalizeTaskPhase(row.phase)) {
+    taskStateIssue(`Harness/PROGRESS.md Task Index row has unknown phase for ${row.id}: ${row.phase}`);
+  }
+}
+
+const activeStateTasks = [];
+for (const taskDir of outerTaskSet) {
+  if (!rootTaskRows.has(taskDir)) {
+    taskStateIssue(`Harness/tasks/${taskDir}/ is missing from Harness/PROGRESS.md Task Index`);
+  }
+
+  const statePath = path.join(root, 'Harness', 'tasks', taskDir, 'STATE.json');
+  if (!fs.existsSync(statePath)) {
+    taskStateIssue(`Harness/tasks/${taskDir}/STATE.json is missing; run node Harness/scripts/task-state.mjs reconcile --apply`);
+    continue;
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+  } catch (err) {
+    taskStateIssue(`Harness/tasks/${taskDir}/STATE.json is invalid JSON: ${err.message}`);
+    continue;
+  }
+
+  if (state.taskId && state.taskId !== taskDir) {
+    taskStateIssue(`Harness/tasks/${taskDir}/STATE.json taskId "${state.taskId}" does not match directory`);
+  }
+  const status = normalizeTaskStatus(state.status);
+  const phase = normalizeTaskPhase(state.phase);
+  if (state.status && !status) {
+    taskStateIssue(`Harness/tasks/${taskDir}/STATE.json has unknown status "${state.status}"`);
+  }
+  if (state.phase && !phase) {
+    taskStateIssue(`Harness/tasks/${taskDir}/STATE.json has unknown phase "${state.phase}"`);
+  }
+  if (status === 'active') activeStateTasks.push(taskDir);
+  if (status === 'active' && taskDir !== rootTaskProgress.activeTask) {
+    taskStateIssue(`Harness/tasks/${taskDir}/STATE.json is active but Harness/PROGRESS.md Active Task is ${rootTaskProgress.activeTask || 'None'}; run node Harness/scripts/task-state.mjs reconcile --apply`);
+  }
+  if (taskDir === rootTaskProgress.activeTask && status && status !== 'active') {
+    taskStateIssue(`Harness/PROGRESS.md Active Task points to ${taskDir}, but STATE.json status is "${status}"; run node Harness/scripts/task-state.mjs reconcile --apply`);
+  }
+}
+
+if (activeStateTasks.length > 1) {
+  taskStateIssue(`Multiple STATE.json files are active: ${activeStateTasks.join(', ')}; run node Harness/scripts/task-state.mjs reconcile --apply`);
+}
 
 // Outer task capsule cap: keep Harness/tasks/ lean (see Harness/specs/protocols/TASK_ARCHIVE.md)
 const OUTER_TASK_CAP = 5;
 const outerTasks = taskDirs.filter(name => !TASK_RESERVED.has(name) && !name.startsWith('_'));
 if (outerTasks.length > OUTER_TASK_CAP) {
-  const capMsg = `Harness/tasks/ has ${outerTasks.length} outer task capsules (cap ${OUTER_TASK_CAP}); archive completed tasks with node Harness/scripts/archive-tasks.mjs --apply (see Harness/specs/protocols/TASK_ARCHIVE.md)`;
+  const capMsg = `Harness/tasks/ has ${outerTasks.length} outer task capsules (cap ${OUTER_TASK_CAP}); remind the user to run $wf-task-archive when they want to archive completed tasks (apply mode maps to node Harness/scripts/task-state.mjs archive --apply)`;
   if (strict) errors.push(capMsg);
   else console.warn(`Warning: ${capMsg}`);
 }
 
-if (errors.length) {
-  console.error(`Harness validation failed${strict ? ' (strict)' : ''}:`);
-  for (const error of errors) console.error(`- ${error}`);
-  process.exit(1);
-}
-
-console.log(`Harness validation passed${strict ? ' (strict)' : ''}.`);
-if (!strict) {
-  console.log('Tip: run `node Harness/scripts/validate-harness.mjs --strict` after bootstrap to check unresolved project placeholders.');
-}
+finishValidation();