create-harness-vibe-coding 0.8.8 → 0.8.10

package/templates/common/{scripts → Harness/scripts}/wf-update-check.mjs

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 /**
- * wf-update-check.mjs — Fast harness update comparison.
+ * wf-update-check.mjs - Fast harness update comparison.
  * Fetches remote checksums, compares locally, classifies all files instantly.
  * Only CONFLICT files need AI/user decision.
  *
  * Usage:
  *   node Harness/scripts/wf-update-check.mjs              # full dry-run plan
  *   node Harness/scripts/wf-update-check.mjs --json       # JSON output for AI consumption
+ *   node Harness/scripts/wf-update-check.mjs --json              # summary/counts + short agent hints only (token-safe)
+ *   node Harness/scripts/wf-update-check.mjs --json --full-plan  # also include full plan + conflict details (verbose)
  *   node Harness/scripts/wf-update-check.mjs --apply-safe # apply SAFE+NEW, leave CONFLICT for AI
  *   node Harness/scripts/wf-update-check.mjs --apply      # apply only when no CONFLICT exists
+ *
+ *   --full-plan and --verbose are aliases.
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, lstatSync } from 'fs';
@@ -19,9 +23,13 @@ import { fileURLToPath } from 'url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = process.env.WF_ROOT ? resolve(process.env.WF_ROOT) : resolve(__dirname, '..', '..');
 const VERSION_FILE = resolve(ROOT, 'Harness', '.harness-version');
-const DEFAULT_SOURCE_BASE = 'https://raw.githubusercontent.com/zingspark/create-harness-vibe-coding/main/templates/common/';
+const GITHUB_REPO = 'zingspark/create-harness-vibe-coding';
+const GITHUB_LATEST_STABLE = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+const RAW_GITHUB = `https://raw.githubusercontent.com/${GITHUB_REPO}`;
+const TEMPLATE_SUBPATH = 'templates/common/';
+const DEFAULT_SOURCE_BASE = `${RAW_GITHUB}/main/${TEMPLATE_SUBPATH}`;
 
-// ── Tier classification ──────────────────────────────────────────
+// Tier classification
 
 /** Files we NEVER overwrite or delete. */
 const PRESERVE_PATTERNS = [
@@ -52,10 +60,15 @@ const OPTIONAL_REGISTRATION_FILES = new Set([
   'Harness/README.md',
 ]);
 
-// ── Helpers ────────────────────────────────────────────────────────
+const BOOTSTRAP_ONLY_FILES = new Set([
+  'Harness/SETUP.md',
+]);
+
+// Helpers
 
 /** Reject paths that escape ROOT (traversal, absolute, .., etc.). */
 function safePath(file) {
+  if (/^[A-Za-z]:/.test(file)) return null;
   let normalized = file.replace(/\\/g, '/').replace(/^\/+/, '');
   if (/\/\//.test(normalized)) return null;
   if (normalized.split('/').some(p => p === '..')) return null;
@@ -132,7 +145,7 @@ function sha256(content) {
 function sha256File(path) {
   if (!existsSync(path)) return null;
   let content = readFileSync(path, 'utf-8');
-  // Normalize CRLF → LF
+  // Normalize CRLF to LF.
   content = content.replace(/\r\n/g, '\n');
   return sha256(content);
 }
@@ -142,16 +155,18 @@ function classify(file, localHash, storedHash) {
   for (const p of PRESERVE_PATTERNS) {
     if (p.test(file)) return 'PRESERVE';
   }
-  // MERGE — dual-purpose, check if user modified
+  // MERGE: dual-purpose, check if user modified.
   for (const p of MERGE_PATTERNS) {
     if (p.test(file)) {
       if (localHash === storedHash) return 'SAFE'; // unmodified, safe
       return 'CONFLICT'; // user modified, needs decision
     }
   }
-  // Everything else is SAFE runtime file
-  if (localHash === storedHash || localHash === null) return 'SAFE';
-  return 'CONFLICT'; // modified runtime file — unexpected
+  // Everything else is SAFE runtime file: always overwrite.
+  // Harness system files (scripts, skills, agents, commands, WF docs) are
+  // not user data; the template is authoritative. Only PRESERVE and MERGE
+  // files should ever require conflict resolution.
+  return 'SAFE';
 }
 
 async function fetchRemote(url, timeoutMs = 30000) {
@@ -170,7 +185,49 @@ async function fetchRemote(url, timeoutMs = 30000) {
   }
 }
 
-// ── Main ───────────────────────────────────────────────────────────
+// Main
+
+function isPrerelease(v) {
+  if (!v || typeof v !== 'string') return false;
+  return /-[0-9A-Za-z.-]+/.test(v.replace(/^[^0-9]*/, ''));
+}
+
+async function resolveStableSourceBase() {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 15000);
+    let res;
+    try {
+      res = await fetch(GITHUB_LATEST_STABLE, {
+        signal: controller.signal,
+        headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'harness-wf-update-check' },
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = JSON.parse(await res.text());
+    const tag = data && data.tag_name;
+    if (!tag || data.prerelease) return null;
+    const source = `${RAW_GITHUB}/${tag}/${TEMPLATE_SUBPATH}`;
+    const versionController = new AbortController();
+    const versionTimer = setTimeout(() => versionController.abort(), 15000);
+    try {
+      const versionRes = await fetch(source + '.harness-version', {
+        signal: versionController.signal,
+        headers: { 'User-Agent': 'harness-wf-update-check' },
+      });
+      if (!versionRes.ok) return null;
+      const raw = await versionRes.text();
+      if (isTemplate(raw)) return null;
+    } finally {
+      clearTimeout(versionTimer);
+    }
+    return source;
+  } catch {
+    return null;
+  }
+}
 
 async function main() {
   const args = process.argv.slice(2);
@@ -182,14 +239,32 @@ async function main() {
   const acceptMerged = readRepeatedFlagValues(args, '--accept-merged');
   const acceptTemplate = readRepeatedFlagValues(args, '--accept-template');
   const ignoreVersion = args.includes('--ignore-version') || args.includes('--force-check');
-  const sourceBase = normalizeSourceBase(readFlagValue(args, '--source-base') || process.env.WF_SOURCE_BASE || DEFAULT_SOURCE_BASE);
+  const explicitSource = readFlagValue(args, '--source-base') || process.env.WF_SOURCE_BASE;
+  let sourceBase = normalizeSourceBase(explicitSource || DEFAULT_SOURCE_BASE);
+  let stableTagResolved = false;
+  if (!explicitSource) {
+    const resolved = await resolveStableSourceBase();
+    if (resolved) {
+      sourceBase = normalizeSourceBase(resolved);
+      stableTagResolved = true;
+    }
+  }
 
   // 1. Read local state
   if (!existsSync(VERSION_FILE)) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'error', message: 'Local Harness/.harness-version not found.' }));
+      console.log(JSON.stringify({
+        status: 'error',
+        message: 'Local Harness/.harness-version not found. Is Harness installed?',
+        recovery: 'If this is an old Harness install that predates .harness-version, do not reinstall blindly. Restore Harness/.harness-version from backup if available. If the updater script is also missing, run from the project root: npx create-harness-vibe-coding@latest <name> . -y --on-conflict skip --json to restore missing updater infrastructure without overwriting user files.',
+      }));
     } else {
       console.error('ERROR: Harness/.harness-version not found. Is Harness installed?');
+      console.error('  If this is an old Harness install without version tracking, do not reinstall blindly.');
+      console.error('  Restore Harness/.harness-version from backup if available.');
+      console.error('  If the updater script is also missing, recover with:');
+      console.error('    npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip --json');
+      console.error('  This restores missing updater infrastructure without overwriting user data.');
     }
     process.exitCode = 1;
     return;
@@ -200,10 +275,16 @@ async function main() {
     localVersion = JSON.parse(readFileSync(VERSION_FILE, 'utf-8'));
   } catch (e) {
     if (jsonOut) {
-      console.log(JSON.stringify({ status: 'error', message: 'Failed to parse Harness/.harness-version: ' + e.message }));
+      console.log(JSON.stringify({
+        status: 'error',
+        message: 'Failed to parse Harness/.harness-version: ' + e.message,
+        recovery: 'The .harness-version file may be corrupted. Do not overwrite user files. Back up or move the corrupted Harness/.harness-version before manual recovery. If the updater script is also missing, run from the project root: npx create-harness-vibe-coding@latest <name> . -y --on-conflict skip --json to restore missing updater infrastructure.',
+      }));
     } else {
       console.error('ERROR: Failed to parse Harness/.harness-version:', e.message);
-      console.error('  The file may be corrupted. If this is an old project, try reinstalling the harness.');
+      console.error('  The file may be corrupted. Back up or move Harness/.harness-version before manual recovery.');
+      console.error('  If the updater script is also missing, recover with:');
+      console.error('    npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip --json');
     }
     process.exitCode = 1;
     return;
@@ -229,9 +310,9 @@ async function main() {
       if (jsonOut) {
         console.log(JSON.stringify({ status: 'template-remote', message: 'Remote .harness-version has not been generated yet.' }));
       } else {
-        console.log('⚠ Remote .harness-version is a template (contains {{placeholders}}).');
+        console.log('WARN: Remote .harness-version is a template (contains {{placeholders}}).');
         console.log('  The generate step has not been run on the remote repo. No update possible.');
-        console.log('  This is expected during development — the update mechanism works once the remote is live.');
+        console.log('  This is expected during development; the update mechanism works once the remote is live.');
       }
       process.exitCode = 1;
       return;
@@ -248,10 +329,10 @@ async function main() {
     return;
   }
 
-  // Compare versions — warn if remote is older (downgrade prevention)
+  // Compare versions and prevent downgrades from explicit custom sources.
   function parseSemver(v) {
     if (!v || typeof v !== 'string') return [0, 0, 0];
-    return v.replace(/^[^0-9]*/, '').split('-')[0].split('.').map(Number);
+    return v.replace(/^[^0-9]*/, '').split('.').slice(0, 3).map(n => Number(n) || 0);
   }
   function cmpSemver(a, b) {
     const va = parseSemver(a), vb = parseSemver(b);
@@ -261,27 +342,38 @@ async function main() {
 
   const localGen = localVersion.generator || '0.0.0';
   const remoteGen = remoteVersion.generator || '0.0.0';
+
+  if (!ignoreVersion && isPrerelease(remoteGen)) {
+    if (jsonOut) {
+      console.log(JSON.stringify({ status: 'up-to-date', version: localGen, remote: remoteGen, sourceBase }));
+    } else {
+      console.log(`Already up to date (v${localGen}). Remote ${remoteGen} is a prerelease and is ignored.`);
+    }
+    return;
+  }
+
   const versionCmp = cmpSemver(remoteGen, localGen);
 
   if (!ignoreVersion && versionCmp <= 0) {
+    const reportDowngrade = !stableTagResolved;
     if (jsonOut) {
       console.log(JSON.stringify({
-        status: versionCmp < 0 ? 'downgrade-refused' : 'up-to-date',
+        status: (versionCmp < 0 && reportDowngrade) ? 'downgrade-refused' : 'up-to-date',
         version: localGen,
         remote: remoteGen,
         sourceBase,
       }));
-    } else if (versionCmp < 0) {
-      console.log(`⚠ Remote (v${remoteGen}) is OLDER than local (v${localGen}). Downgrade refused.`);
+    } else if (versionCmp < 0 && reportDowngrade) {
+      console.log(`WARN: Remote (v${remoteGen}) is OLDER than local (v${localGen}). Downgrade refused.`);
     } else {
-      console.log(`✅ Already up to date (v${localGen})`);
+      console.log(`Already up to date (v${localGen})`);
     }
-    if (versionCmp < 0) process.exitCode = 1;
+    if (versionCmp < 0 && reportDowngrade) process.exitCode = 1;
     return;
   }
 
   if (ignoreVersion) {
-    if (!jsonOut) console.log('🔧 Version check bypassed (--ignore-version). Comparing files anyway.');
+    if (!jsonOut) console.log('Version check bypassed (--ignore-version). Comparing files anyway.');
   }
 
   const remoteChecksums = remoteVersion.checksums || {};
@@ -320,16 +412,26 @@ async function main() {
   }
 
   function buildJsonPlan() {
+    const verbose = args.includes('--verbose') || args.includes('--full-plan');
     return {
       updated: plan.updated.map(withRemoteMeta),
       created: plan.created.map(withRemoteMeta),
       adopted: plan.adopted.map(withRemoteMeta),
-      conflict: plan.conflict.map(withConflictActions),
+      conflict: verbose ? plan.conflict.map(withConflictActions) : plan.conflict.map(withConflictActions).slice(0, 5),
+      conflictTruncated: !verbose && plan.conflict.length > 5 ? plan.conflict.length - 5 : undefined,
       skipped: plan.skipped.map(withRemoteMeta),
     };
   }
 
   function buildAgentHints(jsonPlan) {
+    // Token-safe by default: omit the conflict array; full list available via --json --verbose (or --full-plan)
+    const verbose = args.includes('--verbose') || args.includes('--full-plan');
+    const maxConflictDetails = verbose ? Infinity : 5;
+    const totalConflicts = plan.conflict.length;
+    const conflicts = jsonPlan.conflict.slice(0, maxConflictDetails);
+    const truncated = totalConflicts > maxConflictDetails
+      ? totalConflicts - maxConflictDetails
+      : 0;
     return {
       mode: 'script-first-ai-conflicts',
       dryRunJsonCommand: 'node Harness/scripts/wf-update-check.mjs --json',
@@ -338,8 +440,10 @@ async function main() {
       finalizeCommand: 'node Harness/scripts/wf-update-check.mjs --finalize',
       partialUpdate: localVersion.partialUpdate || null,
       acceptedConflicts: localVersion.acceptedConflicts || {},
-      aiMergeRequired: jsonPlan.conflict,
-      aiMergeRequiredCount: jsonPlan.conflict.length,
+      // aiMergeRequired array is attached only in verbose mode to keep default output token-safe.
+      ...(verbose ? { aiMergeRequired: conflicts } : {}),
+      aiMergeRequiredCount: totalConflicts,
+      aiMergeRequiredTruncated: truncated > 0 ? truncated : undefined,
       conflictPolicy: 'Use the script for SAFE/NEW/adopted files. For each CONFLICT file, compare local content with templateHint/remoteUrl, then record the decision with --accept-local, --accept-merged, or --accept-template. Do not hand-edit Harness/.harness-version.',
       postUpdateCommands: [
         'node Harness/scripts/validate-harness.mjs',
@@ -438,8 +542,13 @@ async function main() {
       continue;
     }
 
+    if (BOOTSTRAP_ONLY_FILES.has(canonical) && localHash === null) {
+      plan.skipped.push({ file, reason: 'bootstrap-only file already removed locally' });
+      continue;
+    }
+
     if (!storedHash) {
-      // New file from remote — if local file exists, it's a CONFLICT
+      // New file from remote: if local file exists, it is a CONFLICT.
       if (localHash) {
         if (localHash === remoteHash) {
           plan.adopted.push({ file, localHash, remoteHash, reason: 'new remote file already matches local file' });
@@ -452,10 +561,10 @@ async function main() {
         plan.conflict.push({ file, localHash, storedHash: 'none', remoteHash, reason: 'new remote file conflicts with existing local file' });
         continue;
       }
-      // New file — still respect PRESERVE classification
+      // New file: still respect PRESERVE classification.
       const tier = classify(canonical, null, null);
       if (tier === 'PRESERVE') {
-        plan.skipped.push({ file, reason: 'PRESERVE — new file would overwrite user data' });
+        plan.skipped.push({ file, reason: 'PRESERVE: new file would overwrite user data' });
       } else {
         plan.created.push({ file, remoteHash });
       }
@@ -486,7 +595,7 @@ async function main() {
     const tier = classify(canonical, localHash, storedHash);
 
     if (tier === 'PRESERVE') {
-      plan.skipped.push({ file, reason: 'PRESERVE — user data' });
+      plan.skipped.push({ file, reason: 'PRESERVE: user data' });
     } else if (tier === 'SAFE') {
       if (localHash === remoteHash) {
         plan.skipped.push({ file, reason: 'already current' });
@@ -512,6 +621,7 @@ async function main() {
 
   // 3. Output
   if (jsonOut) {
+    const verbose = args.includes('--verbose') || args.includes('--full-plan');
     const jsonPlan = buildJsonPlan();
     console.log(JSON.stringify({
       status: localVersion.partialUpdate ? 'partial-update' : 'update-available',
@@ -525,20 +635,21 @@ async function main() {
       adopted: plan.adopted.length,
       conflict: plan.conflict.length,
       skipped: plan.skipped.length,
-      plan: jsonPlan,
+      // Token-safe by default: attach the full plan only when --verbose / --full-plan is passed.
+      ...(verbose ? { plan: jsonPlan } : {}),
       agent: buildAgentHints(jsonPlan),
     }, null, 2));
     return;
   }
 
-  console.log(`\n🔄 Update: v${localGen} → v${remoteGen}`);
+  console.log(`\nUpdate: v${localGen} -> v${remoteGen}`);
   console.log(`   ${plan.updated.length} safe update, ${plan.created.length} new, ${plan.conflict.length} conflict, ${plan.skipped.length} skipped\n`);
 
   // Show conflicts (these need AI/user decision)
   if (plan.conflict.length > 0) {
-    console.log('⚠ CONFLICTS (need your decision):');
+    console.log('CONFLICTS (need your decision):');
     for (const c of plan.conflict) {
-      console.log(`   📄 ${c.file}  [${c.reason}]`);
+      console.log(`   ! ${c.file}  [${c.reason}]`);
     }
     if (plan.updated.length + plan.created.length > 0) {
       console.log('   Tip: run --apply-safe to apply SAFE/NEW files first, then merge conflicts.');
@@ -548,17 +659,17 @@ async function main() {
 
   // Show what will be auto-updated
   if (plan.updated.length + plan.created.length > 0) {
-    console.log('✅ AUTO (safe to apply):');
-    for (const u of plan.updated) console.log(`   ↑ ${u.file}`);
+    console.log('AUTO (safe to apply):');
+    for (const u of plan.updated) console.log(`   ^ ${u.file}`);
     for (const c of plan.created) console.log(`   + ${c.file}`);
     console.log('');
   }
 
   // 4. Apply if requested
   if (apply || applySafe) {
-    // Refuse to apply when conflicts exist — must resolve first
+    // Refuse to apply when conflicts exist; must resolve first.
     if (apply && !applySafe && plan.conflict.length > 0) {
-      console.log(`❌ Cannot apply: ${plan.conflict.length} conflicts must be resolved first.`);
+      console.log(`Cannot apply: ${plan.conflict.length} conflicts must be resolved first.`);
       console.log('   Run --apply-safe to apply SAFE/NEW files first, or resolve conflicts manually then re-run --apply.');
       process.exitCode = 1;
       return plan;
@@ -574,23 +685,23 @@ async function main() {
     for (const u of plan.updated) {
       try {
         const dest = safePath(u.file);
-        if (!dest) { console.error(`   ✗ Traversal rejected: ${u.file}`); failed++; continue; }
-        // Symlink rejection — don't follow symlinks
+        if (!dest) { console.error(`   x Traversal rejected: ${u.file}`); failed++; continue; }
+        // Symlink rejection: do not follow symlinks.
         if (lexists(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   ✗ Symlink rejected: ${u.file}`); failed++; continue; } } catch (_) {}
+          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${u.file}`); failed++; continue; } } catch (_) {}
         }
         const content = await fetchRemote(sourceBase + remotePath(u.file));
         const normalized = content.replace(/\r\n/g, '\n');
         const fetchedHash = sha256(normalized);
         if (fetchedHash !== u.remoteHash) {
-          console.error(`   ✗ Hash mismatch: ${u.file}`);
+          console.error(`   x Hash mismatch: ${u.file}`);
           failed++; continue;
         }
         mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, normalized, 'utf-8');
         applied++;
       } catch (e) {
-        console.error(`   ✗ Failed: ${u.file} — ${e.message}`);
+        console.error(`   x Failed: ${u.file} - ${e.message}`);
         failed++;
       }
     }
@@ -598,25 +709,25 @@ async function main() {
     for (const c of plan.created) {
       try {
         const dest = safePath(c.file);
-        if (!dest) { console.error(`   ✗ Traversal rejected: ${c.file}`); failed++; continue; }
+        if (!dest) { console.error(`   x Traversal rejected: ${c.file}`); failed++; continue; }
         // TOCTOU: recheck file didn't appear since planning
         if (lexists(dest)) {
-          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   ✗ Symlink rejected: ${c.file}`); failed++; continue; } } catch (_) {}
-          console.error(`   ✗ File created since plan: ${c.file} — treating as CONFLICT`);
+          try { if (lstatSync(dest).isSymbolicLink()) { console.error(`   x Symlink rejected: ${c.file}`); failed++; continue; } } catch (_) {}
+          console.error(`   x File created since plan: ${c.file} - treating as CONFLICT`);
           failed++; continue;
         }
         const content = await fetchRemote(sourceBase + remotePath(c.file));
         const normalized = content.replace(/\r\n/g, '\n');
         const fetchedHash = sha256(normalized);
         if (fetchedHash !== c.remoteHash) {
-          console.error(`   ✗ Hash mismatch: ${c.file}`);
+          console.error(`   x Hash mismatch: ${c.file}`);
           failed++; continue;
         }
         mkdirSync(dirname(dest), { recursive: true });
         writeFileSync(dest, normalized, 'utf-8');
         applied++;
       } catch (e) {
-        console.error(`   ✗ Failed: ${c.file} — ${e.message}`);
+        console.error(`   x Failed: ${c.file} - ${e.message}`);
         failed++;
       }
     }
@@ -643,12 +754,12 @@ async function main() {
       }
       writeFileSync(VERSION_FILE, JSON.stringify(localVersion, null, 2) + '\n', 'utf-8');
       if (plan.conflict.length === 0) {
-        console.log(`✅ Applied ${applied} files. Version updated to ${remoteVersion.generator}.`);
+        console.log(`Applied ${applied} files. Version updated to ${remoteVersion.generator}.`);
       } else {
-        console.log(`✅ Applied ${applied} SAFE/NEW files. Version remains ${localGen}; ${plan.conflict.length} conflicts still need merge.`);
+        console.log(`Applied ${applied} SAFE/NEW files. Version remains ${localGen}; ${plan.conflict.length} conflicts still need merge.`);
       }
     } else {
-      console.log(`❌ ${failed} failures. NO files were version-tracked. Fix and re-run.`);
+      console.log(`${failed} failures. NO files were version-tracked. Fix and re-run.`);
       process.exitCode = 1;
     }
   }

package/templates/common/Harness/subagents.md

@@ -2,7 +2,7 @@
 
 Purpose: coordinate subagents for speed without losing control of scope, evidence, or integration.
 
-Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or `/wf`.
+Use this file when work needs multiple roles, parallel reading, independent review, broad context, repeated failures, or explicit `/wf` / `/wf-max` invocation.
 
 project files are the only durable communication channel; chat/subagent transcript state is non-authoritative. Important assumptions, decisions, blockers, evidence, and handoffs must be written to `Harness/tasks/<task-id>/PROGRESS.md` and `Harness/tasks/<task-id>/PLAN.md`, the current feature doc, `Harness/MEMORY.md`, or `Harness/memory/*` as appropriate.
 
@@ -43,20 +43,22 @@ Subagents provide bounded work. They do not own final scope, architecture, relea
 
 Use the installed roster under `.claude/agents/` before inventing ad hoc roles.
 
-| Agent | Default Use |
-| --- | --- |
-| `planner` | decompose goals, map unknowns, define success criteria and write sets |
-| `researcher` | local/external ecosystem context, comparable projects, current facts |
-| `docs-researcher` | official docs, SDK/API behavior, browser/tool constraints |
-| `architect` | boundaries, interface decoupling, state ownership, data flow, migration risk |
-| `test-writer` | failing tests, manual check contracts, browser/API evidence plan |
-| `implementer` | bounded code or doc changes after the second plan |
-| `reviewer` | spec compliance, code quality, maintainability, security, missing tests |
-| `debugger` | reproduced failures, root cause isolation, smallest safe fix |
-| `verifier` | command execution, real browser/API checks, final evidence |
-| `reflector` | closeout synthesis, unresolved-risk check, acceptance gate verdict |
-| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout |
-| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout |
+| Agent | Default Use | Model Tier |
+| --- | --- | --- |
+| `planner` | decompose goals, map unknowns, define success criteria and write sets | standard |
+| `researcher` | local/external ecosystem context, comparable projects, current facts | standard |
+| `docs-researcher` | official docs, SDK/API behavior, browser/tool constraints | standard |
+| `architect` | boundaries, interface decoupling, state ownership, data flow, migration risk | standard |
+| `test-writer` | failing tests, manual check contracts, browser/API evidence plan | standard |
+| `implementer` | bounded code or doc changes after the second plan | standard |
+| `reviewer` | spec compliance, code quality, maintainability, security, missing tests | standard |
+| `debugger` | reproduced failures, root cause isolation, smallest safe fix | standard |
+| `verifier` | command execution, real browser/API checks, final evidence | standard or small-fast |
+| `reflector` | closeout synthesis, unresolved-risk check, acceptance gate verdict | standard |
+| `task-scribe` | task state, heartbeat, dispatch ledger, evidence pointers — NEVER source code | small-fast (haiku) |
+| `codebase-explorer` | scoped read-only source exploration, file discovery, symbol tracing | small-fast (haiku) |
+| `context-master` | analyze context usage, recommend compression at ~85% window, extract durable session knowledge during closeout | small-fast (haiku) |
+| `memory-master` | write/consolidate memory entries, dedup, cross-project extraction; dispatched on repeated failures, user corrections, and WF closeout | standard |
 
 ## Acceptance Role Passes
 
@@ -80,8 +82,10 @@ Hard rule: implementer may not be the independent validator for the same AC ID.
 
 ## WF Default Fan-Out
 
-Explicit `/wf`, `wf mode`, `workflow mode`, or `wk mode` requires complete
-role-chain coverage from `.claude/agents/` before closeout: plan,
+Explicit `/wf`, `$wf`, or `/skills wf` requires tier-specific role coverage per `Harness/WF.md`.
+WF-Light: planner + test-writer + implementer + verifier.
+WF-Standard: adds research/docs + one review lens.
+WF-Full: complete role-chain coverage from `.claude/agents/` before closeout: plan,
 research/docs research as needed, architecture, test, implement, independent
 validation, cross-review, reflector, and accept.
 
@@ -102,7 +106,7 @@ Then add phase-specific agents:
 - `context-master` before closeout for knowledge extraction
 - `memory-master` after repeated failures and during closeout for consolidation
 
-Collaboration mode is determined by concrete conditions, not a fixed ratio. See `Harness/WF.md#Complete Role Chain Requirement` for the full decision tree. Summary: explicit WF/WK mode always uses the complete role chain. 3+ files or cross-layer work uses multi-agent orchestration. 1-2 local files, well-understood, not in WF mode can be solo. Repeated failure stops solo work and switches to multi-agent.
+Collaboration mode is determined by WF tier and concrete conditions, not a fixed ratio. See `Harness/WF.md` for the tier decision guide. Summary: WF-Light uses minimal roles. WF-Standard uses moderate roles with one review lens. WF-Full always uses the complete role chain. Non-WF complex work may still use subagents and planning without entering any WF mode. Repeated failure after two attempts escalates to next tier.
 
 ## Efficiency Ladder
 
@@ -115,22 +119,19 @@ Choose the cheapest coordination level that is safe.
 | Parallel read-only | broad reading, research, architecture, multiple independent failures | 2-3 read-only agents |
 | Serial build lane | normal feature or fix | acceptance/contract -> test-writer -> implementer -> verifier evidence -> cross-review -> reflector -> acceptance |
 | Isolated lanes | disjoint write sets or competing approaches | separate worktrees, then review and merge |
-| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf max: write-set coloring -> wave dispatch -> parallel review |
+| Max parallelism | 5+ disjoint files, fan-out benefit > coordination cost | /wf-max: write-set coloring -> wave dispatch -> parallel review |
 
 Max parallelism removes the Harness default cap, not the runtime's physical or
 account cap. For WF-MAX, record the current runtime budget, use native
 subagents first, close completed agents before declaring the pool exhausted,
-then overflow to the other CLI (`claude -p` or `codex exec`) with explicit
+then overflow to a peer CLI (`claude -p`, `codex exec`, or `opencode run --agent <role> --dir .`) with explicit
 dispatch packets. Generated Harness Codex config defaults to
 `agents.max_threads = 12` and `agents.max_depth = 1`; if that becomes the
 bottleneck, ask the user before raising `agents.max_threads` and keep
 `max_depth = 1` unless recursive delegation is explicitly approved. Do not rely
 on undocumented fork/derive bypasses as stable capacity.
 
-Default for automatic WF triggers: 3-5 active read-only agents before second
-planning. For explicit WF/WK mode, never use the solo pass; schedule the
-complete role chain and use bounded role passes as the recorded fallback when
-subagents are unavailable.
+Default for explicit WF invocation: tier-based. WF-Light: planner + test-writer + implementer + verifier (bounded passes acceptable). WF-Standard: adds research/docs + one independent review lens. WF-Full: complete role chain, use bounded role passes as the recorded fallback when subagents are unavailable.
 
 ## WF Orchestration Shape
 
@@ -148,10 +149,10 @@ controller intake
 -> close with evidence
 ```
 
-Use this shape for `/wf`, long tasks, multi-file changes, architecture work, migrations, browser/API behavior, or repeated failures.
+Use this shape for explicit `/wf`, `/wf-max`, or non-WF complex work with subagents.
 
 ```text
-/wf max orchestration shape:
+/wf-max orchestration shape:
 controller intake
 -> wave 0: max-parallel exploration (4-14 read-only agents)
 -> E-GATE: Exploration Gate - all questions answered, findings synthesized (per WF-MAX.md)
@@ -167,14 +168,14 @@ controller intake
 
 ## Dispatch Pack
 
-Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`.
+Use the canonical dispatch input and handoff format in `Harness/dispatch.md`. Every subagent dispatch must be self-contained - inject only the docs selected by `Harness/README.md` and `Harness/context-loading.md`. On session start, the controller reads `Harness/tasks/<task-id>/STATE.json` per [WF-STATE.md](WF-STATE.md) to resume the dispatch ledger and ready queue.
 
 ## Parallelism Rules
 
 - Read-only agents may run in parallel.
 - Writing agents run serially unless write sets are disjoint and the controller has chosen an isolated worktree.
 - Reviewers may run in parallel after implementation, but spec compliance is evaluated before code-quality approval.
-- Subagents are readers and reporters. They return findings and PLAN patch suggestions. Only the controller (main agent) commits state changes to task files.
+- Subagents are readers and reporters. They return findings and PLAN patch suggestions. Only the controller (main agent) or task-scribe commits state changes to task files. Production source agents (implementer, debugger, test-writer) never write task state unless explicitly dispatched as task-scribe.
 - Do not let two agents edit `Harness/tasks/<task-id>/PROGRESS.md`, `Harness/tasks/<task-id>/PLAN.md`, `Harness/MEMORY.md`, or `Harness/memory/*` concurrently. The controller writes durable state.
 - If two agents disagree, the controller records the conflict in `Harness/tasks/<task-id>/PLAN.md` and chooses the smallest reversible next step.
 
@@ -191,6 +192,13 @@ matrix from running behavior and evidence, not from the implementer's summary.
 
 If either reviewer finds issues, the implementer or debugger fixes them and the same gate runs again. Do not move to final acceptance with open critical/high findings or without reflector PASS.
 
+For `/wf-review`, use the installed `reviewer` role before inventing any
+ad hoc review prompt. If no peer CLI is available, dispatch `reviewer` as an
+independent same-runtime subagent context; for broad WF-MAX review, dispatch
+`review-manager` when the runtime supports nested reviewer fan-out. Reviewer
+agents report suggestions only. The controller accepts, rejects, or escalates
+each finding and owns the final decision.
+
 ## Subagent Status Handling
 
 | Status | Controller Action |

package/templates/common/Harness/tasks/_template/PLAN.md

@@ -35,6 +35,11 @@ Forbidden:
 -
 - Truth files (PRD, ACs, UI/API contracts, test plan, validation report) unless a Change Request is recorded.
 
+## Memory Preflight
+
+- Memory preflight: done | exempt | blocked
+- Memory hints: none | <file/path + reason>
+
 ## Context
 
 - Loaded:

package/templates/common/Harness/tasks/_template/STATE.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "taskId": "task-example",
+  "status": "active",
+  "mode": "direct",
+  "tier": "none",
+  "phase": "intake",
+  "gate": null,
+  "updatedAt": "2026-07-16T00:00:00.000Z",
+  "activeQuestion": null,
+  "nextAction": "Define goal and acceptance criteria",
+  "acceptance": [],
+  "queues": {
+    "ready": [],
+    "running": [],
+    "blocked": [],
+    "done": []
+  },
+  "dispatchLedger": [],
+  "decisions": [],
+  "risks": [],
+  "artifacts": []
+}