create-harness-vibe-coding 0.8.19 → 0.9.3

package/templates/common/Harness/scripts/a2a-terminal.mjs

@@ -51,7 +51,7 @@ function appendJsonl(filePath, row) {
 function allSessionDirs(projectRoot) {
   const tasksRoot = path.join(projectRoot, 'Harness', 'tasks');
   let tasks = [];
-  try { tasks = fs.readdirSync(tasksRoot, { withFileTypes: true }); } catch { return []; }
+  try { tasks = fs.readdirSync(tasksRoot, { withFileTypes: true }); } catch { tasks = []; }
   const out = [];
   for (const task of tasks) {
     if (!task.isDirectory() || task.name.startsWith('_')) continue;
@@ -62,6 +62,12 @@ function allSessionDirs(projectRoot) {
       if (session.isDirectory()) out.push({ taskId: task.name, sessionId: session.name, dir: path.join(sessionsRoot, session.name) });
     }
   }
+  const a2aSessionsRoot = path.join(projectRoot, 'Harness', 'a2a', 'sessions');
+  let a2aSessions = [];
+  try { a2aSessions = fs.readdirSync(a2aSessionsRoot, { withFileTypes: true }); } catch { a2aSessions = []; }
+  for (const session of a2aSessions) {
+    if (session.isDirectory()) out.push({ taskId: null, sessionId: session.name, dir: path.join(a2aSessionsRoot, session.name) });
+  }
   return out;
 }
 
@@ -112,7 +118,9 @@ function globEvents(projectRoot, flags) {
   const rows = [];
   for (const session of allSessionDirs(projectRoot)) {
     for (const filename of ['events.jsonl', 'terminal.jsonl', 'input-requests.jsonl']) {
-      const rel = `Harness/tasks/${session.taskId}/sessions/${session.sessionId}/${filename}`;
+      const rel = session.taskId
+        ? `Harness/tasks/${session.taskId}/sessions/${session.sessionId}/${filename}`
+        : `Harness/a2a/sessions/${session.sessionId}/${filename}`;
       if (!regex.test(rel)) continue;
       for (const row of readJsonl(path.join(session.dir, filename))) {
         const tsMs = row.ts ? new Date(row.ts).getTime() : 0;
@@ -136,7 +144,7 @@ function postInput(urlText, token, sessionId, text) {
       headers: {
         'Content-Type': 'application/json',
         'Content-Length': Buffer.byteLength(body),
-        Authorization: `Bearer ${token}`,
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
       },
     }, (res) => {
       let data = '';
@@ -157,7 +165,7 @@ async function sendInput(projectRoot, flags) {
   const text = flags.text || '';
   const url = flags.url || process.env.WF_UI_URL;
   const token = flags.token || process.env.WF_UI_TOKEN;
-  if (url && token) return postInput(url, token, sessionId, text);
+  if (url) return postInput(url, token, sessionId, text);
 
   const found = findSession(projectRoot, sessionId);
   if (!found) throw new Error(`Session not found: ${sessionId}`);

package/templates/common/Harness/scripts/context-budget.mjs

@@ -9,10 +9,14 @@ const root = rootArgIndex !== -1 && process.argv[rootArgIndex + 1]
   : process.cwd();
 const json = args.has('--json');
 
+// maxBytes baselines track the current generated doc sizes (measured via
+// --json at the last re-baseline) plus ~10% headroom. Growth is intentional
+// as registry/manual discovery content is added; re-baseline by updating the
+// constants when a route is deliberately extended.
 const routes = [
   {
     id: 'thin-startup',
-    maxBytes: 12500,
+    maxBytes: 16000,
     paths: [
       'CLAUDE.md',
       'Harness/memory/startup-hints.md',
@@ -20,7 +24,7 @@ const routes = [
   },
   {
     id: 'wf-router-prefix',
-    maxBytes: 43000,
+    maxBytes: 50000,
     paths: [
       'CLAUDE.md',
       'Harness/MEMORY.md',
@@ -29,7 +33,7 @@ const routes = [
   },
   {
     id: 'wf-light-prefix',
-    maxBytes: 58000,
+    maxBytes: 66500,
     paths: [
       'CLAUDE.md',
       'Harness/MEMORY.md',

package/templates/common/Harness/scripts/lib/memory-context.mjs

@@ -0,0 +1,400 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  scopedGlobalRoot,
+  scopedPath,
+  scopedProject,
+  scopedTaskDirectory,
+} from './path-scope.mjs';
+
+const MEMORY_MARKER = /^\s*<!--\s*harness-memory:\s*(\{.*\})\s*-->\s*$/i;
+const WHEN_BULLET = /^\s*-\s+When\s+(.+?):\s+(.+)$/i;
+const VALID_SCOPES = new Set(['project', 'global', 'task']);
+const VALID_KINDS = new Set(['method', 'preference']);
+const VALID_STATUSES = new Set(['active', 'inactive', 'superseded']);
+
+export function projectRoot(value) {
+  return scopedProject(value, { label: '--project' });
+}
+
+function readJsonInput(value, root = null) {
+  if (!value) throw new Error('--input JSON is required');
+  const candidate = root && !path.isAbsolute(String(value)) ? path.resolve(root, String(value)) : String(value);
+  const inputFile = fs.existsSync(candidate) && fs.statSync(candidate).isFile() ? path.resolve(candidate) : null;
+  if (inputFile && root) scopedPath(root, inputFile, { mustExist: true, label: '--input' });
+  const raw = inputFile ? fs.readFileSync(inputFile, 'utf8') : value;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Invalid JSON input: ${error.message}`);
+  }
+}
+
+function walkMarkdown(root, dir, result = []) {
+  if (!fs.existsSync(dir)) return result;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const file = path.join(dir, entry.name);
+    if (entry.isDirectory()) walkMarkdown(root, file, result);
+    else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) {
+      result.push(scopedPath(root, file, { mustExist: true, label: 'Memory file' }));
+    }
+  }
+  return result;
+}
+
+function safeRelative(root, file) {
+  return path.relative(root, file).replaceAll('\\', '/');
+}
+
+function parseBullet(line) {
+  const match = line.match(WHEN_BULLET);
+  if (!match) return null;
+  let body = match[2].trim();
+  let avoid = '';
+  let signals = [];
+  const avoidMatch = body.match(/\s+Avoid\s*:\s*(.*?)(?=\s+Signals\s*:|$)/i);
+  if (avoidMatch) {
+    avoid = avoidMatch[1].trim().replace(/[.]$/, '');
+    body = body.replace(avoidMatch[0], '').trim();
+  }
+  const signalsMatch = body.match(/\s+Signals\s*:\s*(.*)$/i);
+  if (signalsMatch) {
+    signals = signalsMatch[1].replace(/[.]$/, '').split(',').map(s => s.trim()).filter(Boolean);
+    body = body.replace(signalsMatch[0], '').trim();
+  }
+  return { when: match[1].trim(), rule: body.replace(/[.]$/, ''), avoid, signals };
+}
+
+function parseEntries(root, files) {
+  const entries = [];
+  for (const file of files) {
+    const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+    let pending = null;
+    let pendingMarkerLine = null;
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      const marker = line.match(MEMORY_MARKER);
+      if (marker) {
+        try { pending = JSON.parse(marker[1]); pendingMarkerLine = index; } catch { pending = null; pendingMarkerLine = null; }
+        continue;
+      }
+      const bullet = parseBullet(line);
+      if (!bullet) {
+        pending = null;
+        pendingMarkerLine = null;
+        continue;
+      }
+      const metadata = pending && typeof pending === 'object' ? { ...pending } : null;
+      const value = metadata ? { ...bullet, ...metadata } : { ...bullet };
+      const id = String(value.id || `${safeRelative(root, file)}:${index + 1}`);
+      entries.push({
+        ...value,
+        metadataValue: metadata,
+        id,
+        path: safeRelative(root, file),
+        line: index + 1,
+        metadata: Boolean(metadata),
+        raw: line,
+        markerLine: metadata ? pendingMarkerLine : null,
+        file,
+        sourceBytes: Buffer.byteLength(metadata
+          ? `${lines[index - 1] || ''}\n${line}\n`
+          : `${line}\n`, 'utf8'),
+      });
+      pending = null;
+      pendingMarkerLine = null;
+    }
+  }
+  return entries;
+}
+
+function statusReason(entry) {
+  if (entry.status === 'inactive') return 'inactive memory entry';
+  if (entry.status === 'superseded') {
+    return entry.supersededBy
+      ? `superseded by ${entry.supersededBy}`
+      : 'superseded memory entry';
+  }
+  if (entry.recheckAfter) {
+    const time = Date.parse(entry.recheckAfter);
+    if (Number.isFinite(time) && time <= Date.now()) {
+      return `recheckAfter ${entry.recheckAfter} has passed; verification required`;
+    }
+  }
+  return null;
+}
+
+function scopeMatches(entry, scope, taskId) {
+  if (scope === 'task') {
+    if (entry.scope && entry.scope !== 'task') return false;
+    return !taskId || entry.path.includes(`/tasks/${taskId}/`) || entry.path.includes(`tasks/${taskId}/`);
+  }
+  if (!entry.scope) return scope === 'project';
+  return entry.scope === scope;
+}
+
+function explain(entry, terms) {
+  const matches = terms.filter(term => {
+    const haystack = `${entry.when} ${entry.rule} ${entry.avoid || ''} ${(entry.signals || []).join(' ')}`.toLowerCase();
+    return haystack.includes(term);
+  });
+  const parts = [entry.metadata ? 'metadata-backed' : 'legacy entry without harness-memory metadata'];
+  if (matches.length) parts.push(`matched ${matches.join(', ')}`);
+  if (entry.conflictsWith) parts.push(`conflictsWith ${[].concat(entry.conflictsWith).join(', ')}`);
+  if (entry.recheckAfter) parts.push(`recheckAfter ${entry.recheckAfter}`);
+  return parts.join('; ');
+}
+
+export function queryMemory({ root, globalRoot = null, text = '', scope = 'project', taskId, topK = 5, budgetBytes = 8192 }) {
+  if (!VALID_SCOPES.has(scope)) throw new Error(`Invalid scope "${scope}". Valid: project, global, task`);
+  const storageRoot = scope === 'global' ? scopedGlobalRoot(globalRoot, root) : root;
+  const memoryDir = scopedPath(storageRoot, path.join(storageRoot, 'Harness', 'memory'), { label: 'Harness/memory' });
+  const taskDir = scopedPath(root, path.join(root, 'Harness', 'tasks'), { mustExist: true, label: 'Harness/tasks' });
+  if (scope === 'task' && taskId) scopedTaskDirectory(root, taskId);
+  const dirs = scope === 'task' ? [taskDir] : [memoryDir];
+  const files = dirs.flatMap(dir => walkMarkdown(scope === 'task' ? root : storageRoot, dir));
+  const entries = parseEntries(scope === 'task' ? root : storageRoot, files);
+  const terms = String(text).toLowerCase().split(/\s+/).map(s => s.trim()).filter(Boolean);
+  const skipped = [];
+  const candidates = [];
+  for (const entry of entries) {
+    if (!scopeMatches(entry, scope, taskId)) {
+      skipped.push({ id: entry.id, reason: `scope ${entry.scope || 'project'} is not applicable to ${scope}` });
+      continue;
+    }
+    const inactiveReason = statusReason(entry);
+    if (inactiveReason) {
+      skipped.push({ id: entry.id, reason: inactiveReason });
+      continue;
+    }
+    const haystack = `${entry.when} ${entry.rule} ${entry.avoid || ''} ${(entry.signals || []).join(' ')}`.toLowerCase();
+    const matched = terms.length === 0 || terms.every(term => haystack.includes(term)) || terms.some(term => haystack.includes(term));
+    if (!matched) continue;
+    const score = terms.reduce((sum, term) => sum + (haystack.includes(term) ? 1 : 0), 0);
+    candidates.push({ entry, score });
+  }
+  candidates.sort((a, b) => b.score - a.score || a.entry.path.localeCompare(b.entry.path) || a.entry.line - b.entry.line);
+  const limit = nonNegativeInteger(budgetBytes, '--budget-bytes', 8192);
+  const count = nonNegativeInteger(topK, '--top-k', 5);
+  let usedBytes = 0;
+  const hits = [];
+  for (const { entry, score } of candidates) {
+    if (hits.length >= count) {
+      skipped.push({ id: entry.id, reason: `top-k limit ${count} reached` });
+      continue;
+    }
+    if (usedBytes + entry.sourceBytes > limit) {
+      skipped.push({ id: entry.id, reason: `byte budget ${limit} exceeded` });
+      continue;
+    }
+    usedBytes += entry.sourceBytes;
+    hits.push({
+      id: entry.id,
+      rule: String(entry.rule || ''),
+      reason: explain(entry, terms),
+      path: entry.path,
+      score,
+      status: entry.status || 'unknown',
+      verified: entry.metadata && validateCandidate(entry.metadataValue).valid
+        && entry.verification?.status === 'passed',
+      ...(entry.conflictsWith ? { conflictsWith: entry.conflictsWith } : {}),
+      ...(entry.recheckAfter ? { recheckAfter: entry.recheckAfter } : {}),
+    });
+  }
+  const boundedSkipped = boundSkipped(skipped, limit);
+  const skippedBytes = Buffer.byteLength(JSON.stringify(boundedSkipped), 'utf8');
+  const entryBytes = usedBytes;
+  const contentBytes = entryBytes + skippedBytes;
+  return {
+    hits,
+    skipped: boundedSkipped,
+    budget: {
+      limitBytes: limit,
+      // usedBytes is the charged portion of hits plus the bounded skipped
+      // summary; envelope metadata is reported separately.
+      usedBytes: Math.min(limit, contentBytes),
+      entryBytes,
+      contentBytes,
+      skippedBytes,
+      metadataBytes: Buffer.byteLength(JSON.stringify({ hits: [], skipped: [], budget: { limitBytes: limit, usedBytes: 0 } }), 'utf8'),
+      truncated: contentBytes > limit,
+    },
+  };
+}
+
+function nonNegativeInteger(value, field, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  if (!/^\d+$/.test(String(value))) throw new Error(`${field} must be a non-negative integer`);
+  const result = Number(value);
+  if (!Number.isSafeInteger(result)) throw new Error(`${field} is out of range`);
+  return result;
+}
+
+function boundSkipped(items, limit) {
+  const maxBytes = Math.max(96, Math.min(2048, limit || 256));
+  const output = [];
+  let bytes = 0;
+  for (const item of items) {
+    const next = {
+      id: String(item.id || '').slice(0, 120),
+      reason: String(item.reason || '').slice(0, 120),
+    };
+    const nextBytes = Buffer.byteLength(JSON.stringify(next), 'utf8') + (output.length ? 1 : 0);
+    if (output.length >= 8 || bytes + nextBytes > maxBytes) break;
+    output.push(next);
+    bytes += nextBytes;
+  }
+  const remaining = items.length - output.length;
+  if (remaining > 0) output.push({
+    id: '__skipped__',
+    count: remaining,
+    summary: `${remaining} skipped entries omitted from the response summary`,
+    truncated: true,
+  });
+  return output;
+}
+
+function stringField(value, field, errors) {
+  if (typeof value !== 'string' || !value.trim()) errors.push(`${field} must be a non-empty string`);
+}
+
+export function validateCandidate(candidate) {
+  const errors = [];
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    return { valid: false, errors: ['candidate must be a JSON object'] };
+  }
+  for (const field of ['id', 'kind', 'scope', 'when', 'rule', 'avoid', 'status']) stringField(candidate[field], field, errors);
+  if (!VALID_KINDS.has(candidate.kind)) errors.push('kind must be method or preference');
+  if (!VALID_SCOPES.has(candidate.scope)) errors.push('scope must be project, global, or task');
+  if (!VALID_STATUSES.has(candidate.status)) errors.push('status must be active, inactive, or superseded');
+  if (!Array.isArray(candidate.signals)) errors.push('signals must be an array');
+  if (!Array.isArray(candidate.evidenceRefs)) errors.push('evidenceRefs must be an array');
+  if (candidate.kind === 'method') {
+    if (!Array.isArray(candidate.evidenceRefs) || candidate.evidenceRefs.length === 0) errors.push('method requires evidenceRefs');
+    if (!candidate.counterexample || typeof candidate.counterexample !== 'object') errors.push('method requires counterexample');
+    else {
+      stringField(candidate.counterexample.scenario, 'counterexample.scenario', errors);
+      stringField(candidate.counterexample.outcome, 'counterexample.outcome', errors);
+    }
+    if (!candidate.verification || typeof candidate.verification !== 'object') errors.push('method requires verification');
+    else {
+      if (candidate.verification.status !== 'passed') errors.push('verification.status must be passed');
+      stringField(candidate.verification.method, 'verification.method', errors);
+      stringField(candidate.verification.evidenceRef, 'verification.evidenceRef', errors);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${stable(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+function relation(candidate) {
+  const values = [candidate.supersedes, candidate.supersedesId, candidate.supersedesIds]
+    .flatMap(value => Array.isArray(value) ? value : value ? [value] : [])
+    .map(String);
+  return new Set(values);
+}
+
+function metadataLine(candidate) {
+  return `<!-- harness-memory: ${JSON.stringify(candidate)} -->`;
+}
+
+function block(candidate) {
+  const avoid = candidate.avoid ? ` Avoid: ${candidate.avoid}.` : '';
+  const signals = candidate.signals?.length ? ` Signals: ${candidate.signals.join(', ')}.` : '';
+  return `${metadataLine(candidate)}\n- When ${candidate.when}: ${candidate.rule}.${avoid}${signals}\n`;
+}
+
+function replaceMetadataAt(file, lineNumber, next) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  const index = lineNumber - 1;
+  if (index < 0 || index >= lines.length) throw new Error(`Metadata line no longer exists: ${file}:${lineNumber}`);
+  lines[index] = metadataLine(next);
+  fs.writeFileSync(file, lines.join('\n'), 'utf8');
+}
+
+function appendAtomic(file, text) {
+  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  const prefix = current && !current.endsWith('\n') ? '\n' : '';
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, current + prefix + text, 'utf8');
+}
+
+function allEntries(root) {
+  const dirs = [scopedPath(root, path.join(root, 'Harness', 'memory'), { label: 'Harness/memory' })];
+  return parseEntries(root, dirs.flatMap(dir => walkMarkdown(root, dir)));
+}
+
+export function applyCandidate({ root, globalRoot = null, candidate, apply = false }) {
+  const validation = validateCandidate(candidate);
+  if (!validation.valid) return { ok: false, errors: validation.errors, dryRun: !apply };
+  const storageRoot = candidate.scope === 'global' ? scopedGlobalRoot(globalRoot, root) : root;
+  if (!apply) return { ok: false, dryRun: true, errors: ['Dry run only. Re-run with --apply to write memory.'] };
+  const memoryDir = scopedPath(storageRoot, path.join(storageRoot, 'Harness', 'memory'), { label: 'Memory storage' });
+  const targetName = candidate.kind === 'preference' ? 'user-corrections-preferences.md' : 'agent-lessons-patterns.md';
+  const target = scopedPath(storageRoot, path.join(memoryDir, targetName), { label: 'Memory target' });
+  const entries = allEntries(storageRoot);
+  const same = entries.find(entry => entry.id === candidate.id);
+  if (same) {
+    if (same.metadataValue && stable(same.metadataValue) === stable(candidate)) return { ok: true, action: 'duplicate', id: candidate.id, path: same.path };
+    if (!relation(candidate).has(candidate.id)) {
+      return { ok: false, errors: [`Conflict for memory id ${candidate.id}; provide an explicit supersedes relation.`] };
+    }
+    const next = { ...candidate };
+    replaceMetadataAt(same.file, same.markerLine + 1, next);
+    return { ok: true, action: 'updated', id: candidate.id, path: same.path };
+  }
+  const conflicts = entries.filter(entry => entry.metadata && entry.status !== 'superseded'
+    && entry.when?.toLowerCase() === candidate.when.toLowerCase() && entry.rule !== candidate.rule);
+  const supersedes = relation(candidate);
+  const uncovered = conflicts.filter(entry => !supersedes.has(entry.id));
+  if (uncovered.length) {
+    return { ok: false, errors: [`Conflict with ${uncovered.map(entry => entry.id).join(', ')}; provide supersedes.`] };
+  }
+  for (const entry of conflicts.filter(item => supersedes.has(item.id))) {
+    const next = { ...entry };
+    delete next.file; delete next.raw; delete next.markerLine; delete next.line; delete next.path; delete next.metadata; delete next.sourceBytes; delete next.metadataValue;
+    next.status = 'superseded';
+    next.supersededBy = candidate.id;
+    replaceMetadataAt(entry.file, entry.markerLine + 1, next);
+  }
+  appendAtomic(target, block(candidate));
+  return { ok: true, action: 'created', id: candidate.id, path: safeRelative(storageRoot, target) };
+}
+
+export function setMemoryStatus({ root, id, status, supersededBy, apply = false }) {
+  if (!id) return { ok: false, errors: ['--id is required'], dryRun: !apply };
+  if (!VALID_STATUSES.has(status)) return { ok: false, errors: ['status must be inactive, superseded, or active'], dryRun: !apply };
+  const entries = allEntries(root).filter(entry => entry.id === id);
+  if (!entries.length) return { ok: false, errors: [`Memory id not found: ${id}`], dryRun: !apply };
+  if (!apply) return { ok: false, dryRun: true, errors: ['Dry run only. Re-run with --apply to write memory.'] };
+  for (const entry of entries) {
+    const next = { ...entry };
+    for (const field of ['file', 'raw', 'markerLine', 'line', 'path', 'metadata', 'sourceBytes', 'metadataValue']) delete next[field];
+    next.status = status;
+    if (status === 'superseded' && supersededBy) next.supersededBy = supersededBy;
+    if (status === 'active') delete next.supersededBy;
+    replaceMetadataAt(entry.file, entry.markerLine + 1, next);
+  }
+  return { ok: true, action: 'status-updated', id, status, count: entries.length };
+}
+
+export function writeFeedback({ root, taskId, entry, outcome, reason, apply = false }) {
+  if (!taskId || !entry || !reason) return { ok: false, errors: ['--task, --entry, and --reason are required'], dryRun: !apply };
+  if (!['useful', 'unused', 'incorrect'].includes(outcome)) return { ok: false, errors: ['outcome must be useful, unused, or incorrect'], dryRun: !apply };
+  let taskDir;
+  try { taskDir = scopedTaskDirectory(root, taskId); }
+  catch (error) { return { ok: false, errors: [error.message], dryRun: !apply }; }
+  const target = scopedPath(root, path.join(taskDir, 'evidence', 'memory-feedback.md'), { label: 'Feedback target' });
+  if (!apply) return { ok: false, dryRun: true, errors: ['Dry run only. Re-run with --apply to write task-local evidence.'] };
+  const safeReason = String(reason).replace(/[\r\n]+/g, ' ').trim();
+  appendAtomic(target, `## Memory feedback: ${entry}\n- Outcome: ${outcome}\n- Reason: ${safeReason}\n`);
+  return { ok: true, action: 'feedback-recorded', taskId, entry, path: safeRelative(root, target) };
+}
+
+export function readInput(value, root = null) { return readJsonInput(value, root); }
+export { VALID_KINDS, VALID_SCOPES, VALID_STATUSES };

package/templates/common/Harness/scripts/lib/path-scope.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function isWithin(root, candidate, allowRoot = false) {
+  const relative = path.relative(root, candidate);
+  return (allowRoot && relative === '') || (relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function realpath(value, label) {
+  try { return fs.realpathSync(value); }
+  catch (error) { throw new Error(`${label || 'Path'} cannot be resolved: ${error.message}`); }
+}
+
+// Check lexical containment first, then anchor the check to the real project
+// root. For a not-yet-created output, resolve its nearest existing parent so
+// a symlinked parent cannot redirect the write outside the allowed root.
+export function scopedPath(root, candidate, { allowRoot = false, mustExist = false, label = 'Path' } = {}) {
+  const lexicalRoot = path.resolve(String(root));
+  const lexicalCandidate = path.resolve(String(candidate));
+  if (!isWithin(lexicalRoot, lexicalCandidate, allowRoot)) {
+    throw new Error(`${label} escapes allowed root: ${lexicalCandidate}`);
+  }
+  if (mustExist && !fs.existsSync(lexicalCandidate)) {
+    throw new Error(`${label} does not exist: ${lexicalCandidate}`);
+  }
+  const realRoot = realpath(lexicalRoot, 'Allowed root');
+  let realCandidate;
+  if (fs.existsSync(lexicalCandidate)) {
+    realCandidate = realpath(lexicalCandidate, label);
+  } else {
+    let cursor = lexicalCandidate;
+    const suffix = [];
+    while (!fs.existsSync(cursor)) {
+      const parent = path.dirname(cursor);
+      if (parent === cursor) throw new Error(`${label} has no existing parent: ${lexicalCandidate}`);
+      suffix.unshift(path.basename(cursor));
+      cursor = parent;
+    }
+    realCandidate = path.join(realpath(cursor, label), ...suffix);
+  }
+  if (!isWithin(realRoot, realCandidate, allowRoot)) {
+    throw new Error(`${label} resolves outside allowed root: ${realCandidate}`);
+  }
+  return lexicalCandidate;
+}
+
+export function scopedProject(value, { label = 'Project root' } = {}) {
+  if (!value || !path.isAbsolute(String(value))) throw new Error(`${label} must be an absolute path`);
+  const root = path.resolve(String(value));
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`${label} does not exist: ${root}`);
+  scopedPath(root, root, { allowRoot: true, mustExist: true, label });
+  return root;
+}
+
+export function scopedTaskDirectory(root, taskId, { requireState = true } = {}) {
+  if (!taskId || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(String(taskId))
+    || new Set(['_template', '_archive', 'continuous']).has(String(taskId))) {
+    throw new Error(`Invalid task id "${taskId || ''}"; path traversal is not allowed`);
+  }
+  const tasks = scopedPath(root, path.join(root, 'Harness', 'tasks'), { mustExist: true, label: 'Harness/tasks' });
+  const taskDir = scopedPath(tasks, path.join(tasks, String(taskId)), { mustExist: true, label: 'Task directory' });
+  if (!fs.statSync(taskDir).isDirectory()) throw new Error(`Task is not a directory: ${taskId}`);
+  if (requireState) scopedPath(tasks, path.join(taskDir, 'STATE.json'), { mustExist: true, label: 'Task STATE.json' });
+  return taskDir;
+}
+
+export function scopedGlobalRoot(value, projectRoot) {
+  const global = scopedProject(value, { label: '--global-root' });
+  const globalReal = realpath(global, '--global-root');
+  const projectReal = projectRoot ? realpath(projectRoot, '--project') : null;
+  if (projectReal && (isWithin(projectReal, globalReal, true) || isWithin(globalReal, projectReal, true))) {
+    throw new Error('--global-root must be a different isolated root from --project');
+  }
+  return global;
+}
+
+export { isWithin };

package/templates/common/Harness/scripts/lib/research-policy.mjs

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { scopedPath, scopedProject, scopedTaskDirectory } from './path-scope.mjs';
+
+const TRIGGERS = new Map([
+  ['capability-gap', 'A capability gap should be checked against current primary sources.'],
+  ['volatile-api', 'API behavior or version information may have changed.'],
+  ['user-request', 'The user explicitly requested external verification.'],
+  ['repeated-failure', 'Repeated failure is a signal to inspect current guidance and known fixes.'],
+  ['benchmark-gap', 'A benchmark gap needs an evidence-backed comparison before changing the harness.'],
+]);
+const DECISIONS = new Set(['adopt', 'adapt', 'reject']);
+const SOURCE_TYPES = new Set(['official', 'author']);
+
+export function projectRoot(value) {
+  return scopedProject(value, { label: '--project' });
+}
+
+function readJsonInput(value, root = null) {
+  if (!value) throw new Error('--input JSON is required');
+  const candidate = root && !path.isAbsolute(String(value)) ? path.resolve(root, String(value)) : String(value);
+  const inputFile = fs.existsSync(candidate) && fs.statSync(candidate).isFile() ? path.resolve(candidate) : null;
+  if (inputFile && root) scopedPath(root, inputFile, { mustExist: true, label: '--input' });
+  const raw = inputFile ? fs.readFileSync(inputFile, 'utf8') : value;
+  try { return JSON.parse(raw); } catch (error) { throw new Error(`Invalid JSON input: ${error.message}`); }
+}
+
+export function decide({ trigger, taskType = 'chore' }) {
+  const reasons = [];
+  if (trigger) {
+    const values = (Array.isArray(trigger) ? trigger : [trigger])
+      .flatMap(value => String(value).split(',')).map(value => value.trim()).filter(Boolean);
+    for (const value of values) {
+      if (!TRIGGERS.has(value)) throw new Error(`Invalid trigger "${value}". Valid: ${[...TRIGGERS.keys()].join(', ')}`);
+      reasons.push(TRIGGERS.get(value));
+    }
+  }
+  return { search: reasons.length > 0, reasons, addDependency: false, taskType };
+}
+
+export function validateReference(value) {
+  const errors = [];
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return { valid: false, errors: ['reference must be a JSON object'] };
+  for (const field of ['url', 'title', 'version', 'license', 'reason', 'checkedAt']) {
+    if (typeof value[field] !== 'string' || !value[field].trim()) errors.push(`${field} must be a non-empty string`);
+  }
+  try {
+    const url = new URL(value.url);
+    if (!['http:', 'https:'].includes(url.protocol)) errors.push('url must use http or https');
+  } catch { errors.push('url must be an absolute http(s) URL'); }
+  if (!SOURCE_TYPES.has(value.sourceType)) errors.push('sourceType must be official or author');
+  if (!DECISIONS.has(value.decision)) errors.push('decision must be adopt, adapt, or reject');
+  if (!Array.isArray(value.acIds)) errors.push('acIds must be an array');
+  for (const field of ['counterexample', 'recheckTrigger', 'recheckAfter']) {
+    if (value[field] !== undefined && (typeof value[field] !== 'string' || !value[field].trim())) {
+      errors.push(`${field} must be a non-empty string`);
+    }
+  }
+  if (value.decision === 'adopt' && !String(value.license || '').trim()) errors.push('adopting a code dependency requires a license');
+  if (value.checkedAt && Number.isNaN(Date.parse(value.checkedAt))) errors.push('checkedAt must be an ISO date');
+  return { valid: errors.length === 0, errors };
+}
+
+export function recordReference({ root, taskId, reference, apply = false }) {
+  const validation = validateReference(reference);
+  if (!validation.valid) return { ok: false, errors: validation.errors, dryRun: !apply };
+  if (!taskId) return { ok: false, errors: ['--task is required'], dryRun: !apply };
+  let taskDir;
+  // Legacy capsules may predate STATE.json; the task id and canonical capsule
+  // directory are still checked, and REFERENCES.md is the record target.
+  try { taskDir = scopedTaskDirectory(root, taskId, { requireState: false }); }
+  catch (error) { return { ok: false, errors: [error.message], dryRun: !apply }; }
+  const target = scopedPath(root, path.join(taskDir, 'REFERENCES.md'), { label: 'References target' });
+  if (!fs.existsSync(target)) return { ok: false, errors: [`Task references not found: ${taskId}`], dryRun: !apply };
+  const current = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '# Research references\n';
+  if (!apply) return { ok: false, dryRun: true, errors: ['Dry run only. Re-run with --apply to write references.'] };
+  if (current.includes(reference.url)) return { ok: true, action: 'duplicate', taskId, path: path.relative(root, target).replaceAll('\\', '/') };
+  const acIds = reference.acIds.length ? reference.acIds.join(', ') : 'none';
+  const block = [
+    `\n## ${reference.title}`,
+    `- URL: ${reference.url}`,
+    `- Source type: ${reference.sourceType}`,
+    `- Version: ${reference.version}`,
+    `- License: ${reference.license}`,
+    `- Decision: ${reference.decision}`,
+    `- Reason: ${String(reference.reason).replace(/[\r\n]+/g, ' ').trim()}`,
+    `- AC IDs: ${acIds}`,
+    `- Checked at: ${reference.checkedAt}`,
+    ...(reference.counterexample ? [`- Counterexample: ${String(reference.counterexample).replace(/[\r\n]+/g, ' ').trim()}`] : []),
+    ...((reference.recheckTrigger || reference.recheckAfter) ? [`- Recheck trigger: ${String(reference.recheckTrigger || reference.recheckAfter).replace(/[\r\n]+/g, ' ').trim()}`] : []),
+    '',
+  ].join('\n');
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, current + (current.endsWith('\n') ? '' : '\n') + block, 'utf8');
+  return { ok: true, action: 'recorded', taskId, path: path.relative(root, target).replaceAll('\\', '/') };
+}
+
+export function readInput(value, root = null) { return readJsonInput(value, root); }
+export { TRIGGERS, DECISIONS, SOURCE_TYPES };