@manhd_d/ai-harness 0.0.0-stage → 0.6.0

package/cli/adapters.js

@@ -0,0 +1,149 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, readJson, manifest, HarnessError, check, loadLock, encode, digest } from './harness.js';
+import { scoreDataset } from '../scripts/score-eval.js';
+
+import { loadAdapter, requireThat, object } from './adapter-schema.js';
+import { loadCapability } from './capabilities.js';
+import { casesFrom, checksFrom } from './evaluation-contract.js';
+export { loadAdapter } from './adapter-schema.js';
+
+export function listAdapters(source) {
+  return { status: 'ok', adapters: manifest(source).adapters.map(id => {
+    const a = loadAdapter(source, id);
+    return { id, description: a.description, module_version: a.module_version ?? null, skills: a.skills, detection: a.detection };
+  }) };
+}
+
+function exists(root, file) { return fs.existsSync(safe(root, file)); }
+function probe(root, file) {
+  const filename = safe(root, file);
+  if (!fs.existsSync(filename)) return null;
+  requireThat(fs.statSync(filename).size <= 1024 * 1024, `Detection file exceeds 1 MiB: ${file}`);
+  return fs.readFileSync(filename, 'utf8');
+}
+export function detect(root, source) {
+  const matches = [];
+  for (const id of manifest(source).adapters) {
+    const a = loadAdapter(source, id), evidence = [];
+    for (const rule of a.detection) {
+      const body = probe(root, rule.file);
+      if (body === null) continue;
+      let found;
+      if (rule.kind === 'dependencies') {
+        let pkg; try { pkg = JSON.parse(body); } catch { throw new HarnessError(`Invalid JSON during detection: ${rule.file}`); }
+        requireThat(object(pkg), `Invalid package metadata: ${rule.file}`);
+        const deps = new Set();
+        for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+          if (pkg[field] === undefined) continue;
+          requireThat(object(pkg[field]), `Invalid ${field}: ${rule.file}`);
+          for (const key of Object.keys(pkg[field])) deps.add(key);
+        }
+        found = rule.values.filter(v => deps.has(v));
+      } else found = rule.values.filter(v => body.includes(v));
+      if (found.length) evidence.push({ file: rule.file, kind: rule.kind, matched: found });
+    }
+    if (evidence.length) matches.push({ id, evidence });
+  }
+  // Astro can use @astrojs/react islands (react-dom dependency) without being a
+  // React/Next.js application. Suppress that heuristic-only overlap unless Next
+  // itself is present. Explicit adapter selection remains unrestricted.
+  const astroDetected = matches.some(match => match.id === 'astro');
+  const filtered = matches.filter(match => !(astroDetected && match.id === 'react-nextjs'
+    && !match.evidence.some(row => row.matched.includes('next'))));
+  return { status: 'ok', adapters: filtered.map(m => m.id).sort(), matches: filtered,
+    note: 'Heuristic, current target only; review evidence. No recursive monorepo scan or application execution.' };
+}
+
+function installedAdapters(root) {
+  const result = check(root);
+  requireThat(result.status === 'ok', 'Fix installation drift before reading capabilities');
+  const lock = loadLock(root), source = path.join(root, '.harness');
+  // Require capability files to be covered by the installed lock, not merely present nearby.
+  const adapters = lock.adapters.map(id => {
+    requireThat(Object.hasOwn(lock.files, `.harness/adapters/${id}/adapter.yaml`), `Adapter ${id} needs aih update to enable capabilities`);
+    const a = loadAdapter(source, id);
+    for (const file of [a.verification, a.evaluation, ...a.rules, ...a.skills.map(s => `skills/${s}/SKILL.md`)]) {
+      requireThat(Object.hasOwn(lock.files, `.harness/adapters/${id}/${file}`), `Capability is not locked: ${id}/${file}`);
+    }
+    return a;
+  });
+  return { adapters, lock };
+}
+
+const SCOPES = new Set(['adapters', 'capabilities', 'core', 'all']);
+function installedEvaluations(root, scope) {
+  requireThat(SCOPES.has(scope), `Invalid evaluation scope: ${scope}`);
+  const { adapters, lock } = installedAdapters(root);
+  const source = path.join(root, '.harness');
+  const include = part => part === scope || scope === 'all';
+  const capabilities = [];
+  if (include('capabilities')) {
+    for (const id of lock.capabilities ?? []) {
+      const name = `.harness/capabilities/${id}/capability.json`;
+      requireThat(Object.hasOwn(lock.files, name), `Capability is not locked: ${id}`);
+      const c = loadCapability(source, id);
+      for (const file of [c.verification, c.evaluation].filter(Boolean)) {
+        requireThat(Object.hasOwn(lock.files, `.harness/capabilities/${id}/${file}`),
+          `Capability is not locked: ${id}/${file}`);
+      }
+      capabilities.push(c);
+    }
+  }
+  let core = { checks: [], cases: [] }, composition = [];
+  if (include('core')) {
+    for (const relative of ['core/checks/verification.json', 'core/evals/cases.json', 'core/evals/composition.json']) {
+      requireThat(Object.hasOwn(lock.files, `.harness/${relative}`), 'Core evaluation assets missing; run aih update');
+    }
+    core = { checks: checksFrom(source, 'core/checks/verification.json'), cases: casesFrom(source, 'core/evals/cases.json') };
+    const manifest = readJson(safe(source, 'core/evals/composition.json'));
+    requireThat(manifest?.schema_version === 1 && Array.isArray(manifest.cases), 'Invalid composition dataset');
+    const selected = new Set([...lock.adapters.map(x => `adapter:${x}`), ...(lock.capabilities ?? []).map(x => `capability:${x}`)]);
+    const ids = new Set();
+    for (const row of manifest.cases) {
+      requireThat(typeof row.id === 'string' && /^[a-z][a-z0-9-]*$/.test(row.id) && !ids.has(row.id)
+        && Array.isArray(row.requires) && row.requires.length > 0 && new Set(row.requires).size === row.requires.length
+        && row.requires.every(ref => typeof ref === 'string' && /^(adapter|capability):[a-z][a-z0-9-]*$/.test(ref))
+        && typeof row.prompt === 'string' && row.prompt.trim()
+        && Array.isArray(row.criteria) && row.criteria.length > 0 && row.criteria.every(x => typeof x === 'string' && x.trim())
+        && typeof row.critical === 'boolean', `Invalid composition scenario: ${row.id}`);
+      ids.add(row.id);
+      if (row.requires.every(x => selected.has(x))) {
+        const { requires, ...scenario } = row;
+        composition.push(scenario);
+      }
+    }
+  }
+  return { adapters: include('adapters') ? adapters : [], capabilities, core, composition, lock };
+}
+export function verify(root, scope = 'adapters') {
+  const { adapters, capabilities, core, lock } = installedEvaluations(root, scope);
+  const checks = [
+    ...adapters.flatMap(a => a.checks.map(c => ({ adapter: a.id, ...c }))),
+    ...capabilities.flatMap(c => c.checks.map(check => ({ capability: c.id, ...check }))),
+    ...core.checks.map(c => ({ core: true, ...c })),
+  ];
+  return { status: 'planned', version: lock.version, scope, executed: false,
+    checks: checks.map(c => ({ ...c,
+      applicability: c.when_file === null ? 'review-required' : exists(root, c.when_file) ? 'candidate' : 'not-detected' })),
+    note: 'Advisory plan only; commands are NOT executed and manual gates require human evidence.' };
+}
+
+export function evaluate(root, reportPath, scope = 'adapters') {
+  const { adapters, capabilities, core, composition, lock } = installedEvaluations(root, scope);
+  const dataset = { schema_version: 1, cases: [
+    ...adapters.flatMap(a => a.cases.map(c => ({ ...c, id: `${a.id}/${c.id}` }))),
+    ...capabilities.flatMap(c => c.cases.map(row => ({ ...row, id: `capability/${c.id}/${row.id}` }))),
+    ...core.cases.map(c => ({ ...c, id: `core/${c.id}` })),
+    ...composition.map(c => ({ ...c, id: `composition/${c.id}` })),
+  ] };
+  requireThat(dataset.cases.length > 0, 'Select at least one adapter or capability to evaluate, or use --scope core/all');
+  const bytes = encode(dataset), hash = digest(bytes);
+  if (!reportPath) return { status: 'planned', scope, dataset, report: { schema_version: 1,
+    metadata: { model: '', harness_commit: '', dataset_sha256: hash, bundle_sha256: lock.bundle_sha256, reviewer: '', run_id: '', parameters: '' },
+    results: dataset.cases.map(c => ({ id: c.id, scores: c.criteria.map(() => null), evidence: '' })) },
+    note: 'Unscored template; run a real model separately and record reviewer evidence. No model is invoked.' };
+  const report = readJson(path.resolve(reportPath));
+  requireThat(report?.metadata?.bundle_sha256 === lock.bundle_sha256, 'Evaluation report belongs to a different installed bundle');
+  return { ...scoreDataset(report, bytes), version: lock.version, scope, dataset_sha256: hash };
+}

package/cli/capabilities.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import { manifest, readJson, safe, SLUG, HarnessError, payload } from './files.js';
+import { validateContract } from './module-contract.js';
+import { checksFrom, casesFrom } from './evaluation-contract.js';
+
+const validName = name => typeof name === 'string' && SLUG.test(name);
+const fail = message => { throw new HarnessError(message); };
+const exact = (value, fields) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).sort().join(',') === [...fields].sort().join(',');
+const unique = values => new Set(values).size === values.length;
+
+function skillMetadata(body, name) {
+  const front = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(body);
+  if (!front || !front[1].split(/\r?\n/).includes(`name: ${name}`)) fail(`Invalid skill metadata: ${name}`);
+  const description = front[1].split(/\r?\n/).find(line => line.startsWith('description: '))?.slice(13)?.trim();
+  if (!description) fail(`Missing skill description: ${name}`);
+  for (const heading of ['## Input', '## Procedure', '## Output', '## Constraints']) {
+    if (!body.includes(heading)) fail(`Missing ${heading} in skill: ${name}`);
+  }
+  return { name, description };
+}
+
+export function loadCapability(source, id) {
+  if (!validName(id)) fail('Invalid capability ID');
+  const prefix = `capabilities/${id}/`;
+  const meta = readJson(safe(source, prefix + 'capability.json'));
+  // Schema 1 supports optional role and template lists; legacy UI/UX stays valid.
+  const required = ['schema_version', 'id', 'description', 'skills', 'workflows'];
+  const allowed = new Set([...required, 'agents', 'templates', 'module_version', 'requires', 'recommends', 'conflicts', 'compatible_adapters', 'verification', 'evaluation']);
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)
+      || required.some(k => !Object.hasOwn(meta, k))
+      || Object.keys(meta).some(k => !allowed.has(k))
+      || meta.schema_version !== 1 || meta.id !== id
+      || typeof meta.description !== 'string' || !meta.description.trim()) fail(`Invalid capability: ${id}`);
+  validateContract(meta, 'capability', id);
+  if (!Array.isArray(meta.skills) || !meta.skills.length || !unique(meta.skills)
+      || !meta.skills.every(name => validName(name) && name.startsWith(`harness-${id}-`))) fail(`Invalid capability skills: ${id}`);
+  if (!Array.isArray(meta.workflows) || !meta.workflows.length || !unique(meta.workflows)
+      || !meta.workflows.every(p => /^workflows\/[a-z][a-z0-9-]*\.md$/.test(p))) fail(`Invalid capability workflows: ${id}`);
+  for (const name of meta.skills) {
+    skillMetadata(fs.readFileSync(safe(source, prefix + `skills/${name}/SKILL.md`), 'utf8'), name);
+  }
+  for (const workflow of meta.workflows) {
+    if (!fs.readFileSync(safe(source, prefix + workflow), 'utf8').trim()) fail(`Empty capability workflow: ${id}/${workflow}`);
+  }
+  for (const [kind, pattern] of [
+    ['agents', new RegExp('^agents/[a-z][a-z0-9-]*[.]md$')],
+    ['templates', new RegExp('^templates/[a-z][a-z0-9-]*[.]md$')],
+  ]) {
+    const entries = meta[kind] ?? [];
+    if (!Array.isArray(entries) || !unique(entries) || !entries.every(p => typeof p === 'string' && pattern.test(p))) fail(`Invalid capability ${kind}: ${id}`);
+    for (const file of entries) {
+      const body = fs.readFileSync(safe(source, prefix + file), 'utf8');
+      if (!body.trim()) fail(`Empty capability ${kind}: ${id}/${file}`);
+      if (kind === 'agents' && !['## Inputs', '## Outputs', '## Permissions and limits', '## Handoff'].every(h => body.includes(h))) {
+        fail(`Invalid capability agent contract: ${id}/${file}`);
+      }
+    }
+  }
+  // Optional capability verification/evaluation, installed as locked data.
+  if (meta.verification !== undefined && meta.verification !== 'checks/verification.json') fail(`Invalid capability verification: ${id}`);
+  if (meta.evaluation !== undefined && meta.evaluation !== 'evals/cases.json') fail(`Invalid capability evaluation: ${id}`);
+  const checks = meta.verification ? checksFrom(source, prefix + meta.verification) : [];
+  const cases = meta.evaluation ? casesFrom(source, prefix + meta.evaluation) : [];
+  return { ...meta, agents: meta.agents ?? [], templates: meta.templates ?? [], checks, cases };
+}
+
+export function listCapabilities(source) {
+  return (manifest(source).capabilities ?? []).map(id => {
+    const { description, skills, workflows, agents, templates, module_version, verification, evaluation } = loadCapability(source, id);
+    return { id, description, skills, workflows, agents, templates, module_version: module_version ?? null, verification: verification ?? null, evaluation: evaluation ?? null };
+  });
+}
+
+// Progressive disclosure: return metadata only; never include skill bodies in a catalog.
+export function skillCatalog(root, lock) {
+  const skills = Object.keys(lock.files).filter(p => /^\.agents\/skills\/harness-[a-z0-9-]+\/SKILL\.md$/.test(p)).sort()
+    .map(p => {
+      const name = p.split('/')[2];
+      const contents = payload(root, p).toString('utf8');
+      return { ...skillMetadata(contents, name), path: p };
+    });
+  return { status: 'ok', version: lock.version, skills, note: 'Descriptions only. Use aih skill <name> to fetch full instructions when relevant.' };
+}
+
+export function readSkill(root, lock, name) {
+  if (!validName(name) || !name.startsWith('harness-')) fail('Invalid skill name');
+  const relative = `.agents/skills/${name}/SKILL.md`;
+  if (!Object.hasOwn(lock.files, relative)) fail(`Skill is not installed: ${name}`);
+  const content = payload(root, relative).toString('utf8');
+  skillMetadata(content, name);
+  return { status: 'ok', name, path: relative, content };
+}

package/cli/composition.js

@@ -0,0 +1,96 @@
+import { manifest, validateAdapters, validateCapabilities, HarnessError } from './files.js';
+import { loadAdapter } from './adapter-schema.js';
+import { loadCapability } from './capabilities.js';
+import { moduleRef } from './module-contract.js';
+
+export function resolveModules(source, { adapters = [], capabilities = [] } = {}) {
+  validateAdapters(adapters); validateCapabilities(capabilities);
+  const registry = manifest(source);
+  const unknownA = adapters.filter(id => !registry.adapters.includes(id));
+  const unknownC = capabilities.filter(id => !(registry.capabilities ?? []).includes(id));
+  if (unknownA.length || unknownC.length) {
+    throw new HarnessError(`Unknown modules: ${[
+      ...unknownA.map(id => moduleRef('adapter', id)),
+      ...unknownC.map(id => moduleRef('capability', id)),
+    ].join(', ')}`);
+  }
+  const sortedA = [...adapters].sort(), sortedC = [...capabilities].sort();
+  const modules = [
+    ...sortedA.map(id => ({ kind: 'adapter', id, data: loadAdapter(source, id) })),
+    ...sortedC.map(id => ({ kind: 'capability', id, data: loadCapability(source, id) })),
+  ];
+  const selected = new Map(modules.map(m => [moduleRef(m.kind, m.id), m]));
+  const declared = new Set([...registry.adapters.map(x => moduleRef('adapter', x)),
+    ...(registry.capabilities ?? []).map(x => moduleRef('capability', x))]);
+  const warnings = [], graph = new Map();
+  for (const { kind, id, data } of modules) {
+    const owner = moduleRef(kind, id);
+    for (const field of ['requires', 'recommends', 'conflicts']) {
+      for (const ref of data[field] ?? []) {
+        if (!declared.has(ref)) throw new HarnessError(`Unknown ${field} reference ${ref} in ${owner}`);
+      }
+    }
+    for (const dep of data.requires ?? []) {
+      if (!selected.has(dep)) throw new HarnessError(`Missing required module ${dep} for ${owner}`);
+    }
+    for (const denied of data.conflicts ?? []) {
+      if (selected.has(denied)) throw new HarnessError(`Incompatible modules: ${owner} conflicts with ${denied}`);
+    }
+    if (data.compatible_adapters?.length) {
+      for (const adapter of sortedA) {
+        if (!data.compatible_adapters.includes(adapter)) {
+          throw new HarnessError(`Incompatible adapter ${adapter} for ${owner}`);
+        }
+      }
+    }
+    for (const hint of data.recommends ?? []) {
+      if (!selected.has(hint)) warnings.push(`${owner} recommends ${hint} (optional)`);
+    }
+    graph.set(owner, data.requires ?? []);
+  }
+  const states = new Map();
+  function visit(ref) {
+    if (states.get(ref) === 'visiting') throw new HarnessError(`Module dependency cycle at ${ref}`);
+    if (states.get(ref) === 'done') return;
+    states.set(ref, 'visiting');
+    for (const dep of graph.get(ref) ?? []) visit(dep);
+    states.set(ref, 'done');
+  }
+  for (const ref of graph.keys()) visit(ref);
+  return { status: 'ok', adapters: sortedA, capabilities: sortedC,
+    modules: modules.map(m => ({ id: m.id, kind: m.kind, module_version: m.data.module_version ?? null })),
+    warnings };
+}
+
+/** Validate the complete catalog without pretending every registered module is selected. */
+export function validateRegistry(source) {
+  const registry = manifest(source);
+  const entries = [
+    ...registry.adapters.map(id => ({kind:'adapter',id,data:loadAdapter(source,id)})),
+    ...(registry.capabilities ?? []).map(id => ({kind:'capability',id,data:loadCapability(source,id)})),
+  ];
+  const declared = new Set(entries.map(m=>moduleRef(m.kind,m.id)));
+  const graph = new Map();
+  for (const {kind,id,data} of entries) {
+    const owner=moduleRef(kind,id);
+    for (const field of ['requires','recommends','conflicts']) {
+      for (const ref of data[field] ?? []) {
+        if (!declared.has(ref)) throw new HarnessError(`Unknown ${field} reference ${ref} in ${owner}`);
+      }
+    }
+    for (const id of data.compatible_adapters ?? []) {
+      if (!registry.adapters.includes(id)) throw new HarnessError(`Unknown compatible adapter ${id} in ${owner}`);
+    }
+    graph.set(owner,data.requires ?? []);
+  }
+  const states=new Map();
+  function visit(ref) {
+    if (states.get(ref)==='visiting') throw new HarnessError(`Module dependency cycle at ${ref}`);
+    if (states.get(ref)==='done') return;
+    states.set(ref,'visiting');
+    for (const dep of graph.get(ref) ?? []) visit(dep);
+    states.set(ref,'done');
+  }
+  for (const ref of graph.keys()) visit(ref);
+  return {status:'ok',modules:entries.length};
+}

package/cli/evaluation-contract.js

@@ -0,0 +1,40 @@
+import { readJson, safe, HarnessError, SLUG } from './files.js';
+const requireThat = (condition, message) => { if (!condition) throw new HarnessError(message); };
+const text = v => typeof v === 'string' && v.trim().length > 0;
+const exact = (v, keys) => v && typeof v === 'object' && !Array.isArray(v)
+  && Object.keys(v).sort().join(',') === [...keys].sort().join(',');
+export function checksFrom(source, relative) {
+  const doc = readJson(safe(source, relative));
+  requireThat(exact(doc, ['schema_version', 'checks']) && doc.schema_version === 1 && Array.isArray(doc.checks)
+    && doc.checks.length > 0, `Invalid verification: ${relative}`);
+  const ids = new Set();
+  for (const check of doc.checks) {
+    requireThat(!ids.has(check?.id), `Duplicate checks: ${relative}`);
+    requireThat(exact(check, ['id', 'title', 'command', 'when_file', 'evidence', 'execution'])
+      && typeof check.id === 'string' && SLUG.test(check.id) && !ids.has(check.id)
+      && text(check.title) && Array.isArray(check.command) && check.command.every(text)
+      && Array.isArray(check.evidence) && check.evidence.length > 0 && check.evidence.every(text)
+      && ((check.execution === 'advisory' && check.command.length > 0)
+       || (check.execution === 'manual' && check.command.length === 0)), `Invalid check: ${relative}`);
+    if (check.when_file !== null) {
+      requireThat(typeof check.when_file === 'string', `Invalid when_file: ${relative}`);
+      safe(source, check.when_file);
+    }
+    ids.add(check.id);
+  }
+  return doc.checks;
+}
+export function casesFrom(source, relative) {
+  const doc = readJson(safe(source, relative));
+  requireThat(exact(doc, ['schema_version', 'cases']) && doc.schema_version === 1 && Array.isArray(doc.cases)
+    && doc.cases.length > 0, `Invalid evaluation: ${relative}`);
+  const ids = new Set();
+  for (const c of doc.cases) {
+    requireThat(exact(c, ['id', 'prompt', 'criteria', 'critical'])
+      && typeof c.id === 'string' && SLUG.test(c.id) && !ids.has(c.id)
+      && text(c.prompt) && Array.isArray(c.criteria) && c.criteria.length > 0 && c.criteria.every(text)
+      && typeof c.critical === 'boolean', `Invalid eval case: ${relative}`);
+    ids.add(c.id);
+  }
+  return doc.cases;
+}

package/cli/files.js

@@ -0,0 +1,125 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+// Resolve from the installed package, never the consumer's cwd or npm's bin symlink.
+export const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const START = '<!-- ai-harness:start -->';
+export const END = '<!-- ai-harness:end -->';
+export const LOCK = '.harness/lock.json';
+export const CONFIG = '.harness/project.json';
+export const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+export const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+export class HarnessError extends Error {}
+
+export function encode(value) {
+  // Matches v0.1 Python json.dumps(indent=2, sort_keys=True, ensure_ascii=False).
+  const sorted = item => Array.isArray(item) ? item.map(sorted) : isObject(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(k => [k, sorted(item[k])])) : item;
+  return Buffer.from(JSON.stringify(sorted(value), null, 2) + '\n');
+}
+export const digest = data => createHash('sha256').update(data).digest('hex');
+
+export function stat(filename) {
+  try { return fs.lstatSync(filename); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+}
+
+export function safe(root, name) {
+  if (typeof name !== 'string' || !name || !/^[a-zA-Z0-9._/-]+$/.test(name)
+      || path.posix.isAbsolute(name) || path.posix.normalize(name) !== name
+      || name.split('/').some(p => !p || p === '.' || p === '..' || p.endsWith('.')
+        || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(p))) {
+    throw new HarnessError(`Unsafe relative path: ${name}`);
+  }
+  let current = root;
+  const parts = name.split('/');
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    const info = stat(current);
+    if (!info) continue;
+    if (info.isSymbolicLink()) throw new HarnessError(`Symlink is not supported: ${current}`);
+    if (index < parts.length - 1 ? !info.isDirectory() : !info.isFile()) {
+      throw new HarnessError(`Unexpected filesystem entry: ${current}`);
+    }
+  }
+  return current;
+}
+
+export function targetRoot(value) {
+  const root = path.resolve(value);
+  for (let current = root; ; current = path.dirname(current)) {
+    if (stat(current)?.isSymbolicLink()) throw new HarnessError(`Target contains a symlink: ${current}`);
+    if (path.dirname(current) === current) break;
+  }
+  if (!stat(root)?.isDirectory()) throw new HarnessError('Target must be an existing directory');
+  return root;
+}
+
+export function assertSeparate(root, source) {
+  const inside = (parent, child) => {
+    const rel = path.relative(parent, child);
+    return !rel || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel));
+  };
+  // npm local installs intentionally place the package in the consumer's node_modules.
+  const localPackage = path.relative(root, source).split(path.sep)[0] === 'node_modules';
+  if (inside(source, root) || (inside(root, source) && !localPackage)) {
+    throw new HarnessError('Source and target must not overlap, except a source installed in node_modules');
+  }
+}
+
+export function readJson(filename) {
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch (error) { throw new HarnessError(`Cannot read JSON document: ${filename}: ${error.message}`); }
+}
+
+export function block(data) {
+  const a = data.indexOf(START), b = data.indexOf(END);
+  if (a === -1 && b === -1) return null;
+  if (a === -1 || b < a || data.indexOf(START, a + START.length) !== -1
+      || data.indexOf(END, b + END.length) !== -1) {
+    throw new HarnessError('AGENTS.md has duplicate, reversed or incomplete harness markers');
+  }
+  return data.subarray(a, b + END.length);
+}
+
+export function mergeAgents(existing, generated) {
+  const old = block(existing);
+  if (old === null) {
+    const separator = !existing.length ? '' : existing.at(-1) === 10 ? '\n' : '\n\n';
+    return Buffer.concat([existing, Buffer.from(separator), generated, Buffer.from('\n')]);
+  }
+  const offset = existing.indexOf(START);
+  return Buffer.concat([existing.subarray(0, offset), generated, existing.subarray(offset + old.length)]);
+}
+
+export function payload(root, name) {
+  const filename = safe(root, name);
+  if (!stat(filename)) return null;
+  const data = fs.readFileSync(filename);
+  return name === 'AGENTS.md' ? block(data) : data;
+}
+
+export function manifest(source) {
+  const m = readJson(safe(source, 'harness.yaml'));
+  if (!isObject(m) || m.schema_version !== 1 || !VERSION.test(m.version)) {
+    throw new HarnessError('Invalid harness manifest schema/version');
+  }
+  validateAdapters(m.adapters);
+  validateCapabilities(m.capabilities ?? []);
+  if (!m.adapters.length) throw new HarnessError('Empty adapter registry');
+  return m;
+}
+
+export function validateAdapters(names) {
+  if (!Array.isArray(names) || names.some(a => typeof a !== 'string' || !SLUG.test(a))
+      || new Set(names).size !== names.length) throw new HarnessError('Invalid or duplicate adapters');
+}
+
+export function validateCapabilities(names) {
+  if (!Array.isArray(names) || names.some(a => typeof a !== 'string' || !SLUG.test(a))
+      || new Set(names).size !== names.length) throw new HarnessError('Invalid or duplicate capabilities');
+}