@manhd_d/ai-harness 0.0.0-stage → 0.6.2

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');
+}

package/cli/harness.js

@@ -0,0 +1,255 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadAdapter } from './adapter-schema.js';
+import { loadCapability } from './capabilities.js';
+import { resolveModules } from './composition.js';
+import { safe, readJson, manifest, encode, digest, stat, block, mergeAgents, payload, validateAdapters, validateCapabilities, assertSeparate, HarnessError, LOCK, CONFIG, VERSION, SLUG, isObject } from './files.js';
+export * from './files.js';
+
+function projectConfig(root, adapters, capabilities, required = false) {
+  const filename = safe(root, CONFIG);
+  if (required && !stat(filename)) throw new HarnessError(`Missing ${CONFIG}; restore it from Git`);
+  const config = stat(filename) ? readJson(filename) : { schema_version: 1, adapters: adapters ?? [], capabilities: capabilities ?? [] };
+  const keys = isObject(config) ? Object.keys(config).sort().join(',') : '';
+  if (!isObject(config) || !['adapters,schema_version', 'adapters,capabilities,schema_version'].includes(keys)
+      || config.schema_version !== 1) throw new HarnessError('Invalid project.json schema');
+  validateAdapters(config.adapters);
+  validateCapabilities(config.capabilities ?? []);
+  if (adapters !== undefined && stat(filename)
+      && JSON.stringify([...adapters].sort()) !== JSON.stringify([...config.adapters].sort())) {
+    throw new HarnessError('Edit .harness/project.json to select adapters, then run update');
+  }
+  if (capabilities !== undefined && stat(filename)
+      && JSON.stringify([...capabilities].sort()) !== JSON.stringify([...(config.capabilities ?? [])].sort())) {
+    throw new HarnessError('Edit .harness/project.json to select capabilities, then run update');
+  }
+  return config;
+}
+
+export function collect(source, folder) {
+  const files = {};
+  const visit = name => {
+    const filename = path.join(source, name);
+    const info = stat(filename);
+    if (!info || info.isSymbolicLink()) throw new HarnessError(`Missing/unsafe source: ${name}`);
+    if (info.isDirectory()) {
+      for (const child of fs.readdirSync(filename).sort()) visit(`${name}/${child}`);
+    } else if (info.isFile()) files[name] = fs.readFileSync(safe(source, name));
+    else throw new HarnessError(`Unsupported source entry: ${name}`);
+  };
+  visit(folder);
+  if (!Object.keys(files).length) throw new HarnessError(`Empty source directory: ${folder}`);
+  return files;
+}
+
+export function bundle(source, config) {
+  const selection = resolveModules(source, config);
+  const m = manifest(source), adapters = selection.adapters, capabilities = selection.capabilities;
+  const unknown = adapters.filter(a => !m.adapters.includes(a));
+  if (unknown.length) throw new HarnessError(`Unknown adapters: ${unknown.join(', ')}`);
+  const unknownCapabilities = capabilities.filter(c => !(m.capabilities ?? []).includes(c));
+  if (unknownCapabilities.length) throw new HarnessError(`Unknown capabilities: ${unknownCapabilities.join(', ')}`);
+  const files = {};
+  for (const folder of ['core', 'integrations', 'templates', ...adapters.map(a => `adapters/${a}`), ...capabilities.map(c => `capabilities/${c}`)]) {
+    for (const [name, data] of Object.entries(collect(source, folder))) {
+      files[`.harness/${name}`] = data;
+      if (name.startsWith('core/skills/')) files[`.agents/skills/${name.slice('core/skills/'.length)}`] = data;
+    }
+  }
+  for (const a of adapters) {
+    const info = loadAdapter(source, a);
+    for (const name of info.skills) {
+      const dest = `.agents/skills/${name}/SKILL.md`;
+      if (Object.hasOwn(files, dest)) throw new HarnessError(`Skill collision: ${name}`);
+      files[dest] = fs.readFileSync(safe(source, `adapters/${a}/skills/${name}/SKILL.md`));
+    }
+  }
+  for (const c of capabilities) {
+    const info = loadCapability(source, c);
+    for (const name of info.skills) {
+      const dest = `.agents/skills/${name}/SKILL.md`;
+      if (Object.hasOwn(files, dest)) throw new HarnessError(`Skill collision: ${name}`);
+      files[dest] = fs.readFileSync(safe(source, `capabilities/${c}/skills/${name}/SKILL.md`));
+    }
+  }
+  const capabilityLinks = capabilities.map(c => `- For ${c} tasks, read \`.harness/capabilities/${c}/workflows/\` and discover relevant \`.agents/skills/harness-${c}-*/SKILL.md\` by description.`).join('\n')
+    || '- No optional capability selected.';
+  const links = adapters.map(a => `- Read \`.harness/adapters/${a}/rules.md\` and \`.harness/adapters/${a}/adapter.yaml\`; load relevant skills from \`.agents/skills/harness-${a}-*\`.`).join('\n') || '- No technology adapter selected.';
+  const template = fs.readFileSync(safe(source, 'templates/AGENTS.md'), 'utf8');
+  const generated = Buffer.from(template.replaceAll('{{version}}', m.version).replaceAll('{{adapters}}', links).replaceAll('{{capabilities}}', capabilityLinks).trim());
+  if (!block(generated)?.equals(generated)) throw new HarnessError('AGENTS template must be one managed block');
+  files['AGENTS.md'] = generated;
+  const hashes = Object.fromEntries(Object.keys(files).sort().map(k => [k, digest(files[k])]));
+  return { files, warnings: selection.warnings, lock: { schema_version: 1, version: m.version, adapters, capabilities, files: hashes, bundle_sha256: digest(encode(hashes)) } };
+}
+
+function managedName(name) {
+  return name === 'AGENTS.md' || ['.harness/core/', '.harness/adapters/', '.harness/capabilities/', '.harness/integrations/', '.harness/templates/', '.agents/skills/harness-'].some(prefix => name.startsWith(prefix));
+}
+
+export function loadLock(root) {
+  const lock = readJson(safe(root, LOCK));
+  if (!isObject(lock) || !['adapters,bundle_sha256,files,schema_version,version',
+      'adapters,bundle_sha256,capabilities,files,schema_version,version'].includes(Object.keys(lock).sort().join(','))
+      || lock.schema_version !== 1 || !VERSION.test(lock.version) || !isObject(lock.files)
+      || !Object.hasOwn(lock.files, 'AGENTS.md')) throw new HarnessError('Invalid lock schema/content');
+  validateAdapters(lock.adapters);
+  validateCapabilities(lock.capabilities ?? []);
+  for (const [name, sha] of Object.entries(lock.files)) {
+    if (!managedName(name) || typeof sha !== 'string' || !/^[0-9a-f]{64}$/.test(sha)) throw new HarnessError(`Invalid lock entry: ${name}`);
+    safe(root, name);
+  }
+  if (lock.bundle_sha256 !== digest(encode(lock.files))) throw new HarnessError('Lock digest mismatch');
+  return lock;
+}
+
+function drift(root, lock) {
+  return Object.entries(lock.files).filter(([name, sha]) => {
+    const data = payload(root, name);
+    return data === null || digest(data) !== sha;
+  }).map(([name]) => name);
+}
+
+function guard(root, operation) {
+  const filename = safe(root, '.harness-install.lock');
+  let fd;
+  try { fd = fs.openSync(filename, 'wx', 0o600); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new HarnessError('Another installation is active; inspect .harness-install.lock before removing a stale lock');
+    throw error;
+  }
+  try { fs.writeSync(fd, String(process.pid)); return operation(); }
+  finally { fs.closeSync(fd); fs.unlinkSync(filename); }
+}
+
+export function atomicWrite(filename, data) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  const tmp = path.join(path.dirname(filename), `.harness-tmp-${randomUUID()}`);
+  try {
+    fs.writeFileSync(tmp, data, { flag: 'wx', mode: 0o600 });
+    fs.chmodSync(tmp, stat(filename) ? fs.statSync(filename).mode & 0o777 : 0o644);
+    fs.renameSync(tmp, filename);
+  } finally { fs.rmSync(tmp, { force: true }); }
+}
+
+export function transaction(root, changes, writer = atomicWrite) {
+  const originals = {}, applied = [];
+  for (const name of Object.keys(changes)) {
+    const filename = safe(root, name);
+    originals[name] = stat(filename) ? fs.readFileSync(filename) : null;
+  }
+  try {
+    for (const [name, data] of Object.entries(changes)) {
+      const filename = safe(root, name);
+      if (data === null) fs.rmSync(filename, { force: true });
+      else writer(filename, data);
+      applied.push(name);
+    }
+  } catch (error) {
+    for (const name of applied.reverse()) {
+      const filename = safe(root, name);
+      if (originals[name] === null) fs.rmSync(filename, { force: true });
+      else atomicWrite(filename, originals[name]);
+    }
+    throw error;
+  }
+}
+
+export function install(root, source, { command = 'init', adapters, capabilities, dryRun = false, allowMajor = false, writer } = {}) {
+  assertSeparate(root, source);
+  return guard(root, () => {
+    const hasLock = Boolean(stat(safe(root, LOCK)));
+    if (command === 'update' && !hasLock) throw new HarnessError('Not installed; run init first');
+    const old = hasLock ? loadLock(root) : null;
+    const config = projectConfig(root, adapters, capabilities, hasLock);
+    const { files, lock, warnings } = bundle(source, config);
+    if (old) {
+      const conflicts = drift(root, old);
+      if (conflicts.length) throw new HarnessError(`Managed files changed; reconcile in Git before updating: ${conflicts.join(', ')}`);
+      const before = old.version.split('.').map(BigInt), after = lock.version.split('.').map(BigInt);
+      const diff = after.findIndex((v, i) => v !== before[i]);
+      if (diff !== -1 && after[diff] < before[diff]) throw new HarnessError('Downgrades are refused; revert the installation commit in Git');
+      if (after[0] !== before[0] && !allowMajor) throw new HarnessError('Major upgrade requires --allow-major and migration review');
+      if (command === 'init' && !encode(old).equals(encode(lock))) throw new HarnessError('Already installed; use update');
+    }
+    const changes = {};
+    for (const [name, data] of Object.entries(files)) {
+      const present = payload(root, name), owned = old && Object.hasOwn(old.files, name);
+      if (present !== null && !owned && !present.equals(data)) throw new HarnessError(`Unmanaged file collision: ${name}`);
+      if (present === null || !present.equals(data)) {
+        const filename = safe(root, name);
+        const existing = stat(filename) ? fs.readFileSync(filename) : Buffer.alloc(0);
+        changes[name] = name === 'AGENTS.md' ? mergeAgents(existing, data) : data;
+      }
+    }
+    if (old) for (const name of Object.keys(old.files)) if (!Object.hasOwn(files, name)) changes[name] = null;
+    const seeds = {
+      [CONFIG]: encode(config),
+      'openspec/config.yaml': fs.readFileSync(safe(source, 'templates/openspec/config.yaml')),
+      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n'),
+    };
+    for (const [name, data] of Object.entries(seeds)) if (!stat(safe(root, name))) changes[name] = data;
+    const newLock = encode(lock);
+    if (!hasLock || !fs.readFileSync(safe(root, LOCK)).equals(newLock)) changes[LOCK] = newLock;
+    const plan = Object.entries(changes).map(([name, data]) => ({ path: name, action: data === null ? 'delete' : 'write' }));
+    if (!dryRun) transaction(root, changes, writer);
+    return { status: dryRun ? 'planned' : 'ok', version: lock.version, changes: plan, warnings };
+  });
+}
+
+export function check(root) {
+  const lock = loadLock(root), config = projectConfig(root, undefined, undefined, true);
+  const problems = drift(root, lock);
+  if (JSON.stringify([...config.adapters].sort()) !== JSON.stringify([...lock.adapters].sort())) problems.push(`${CONFIG}: adapter selection changed; run update`);
+  if (JSON.stringify([...(config.capabilities ?? [])].sort()) !== JSON.stringify([...(lock.capabilities ?? [])].sort())) problems.push(`${CONFIG}: capability selection changed; run update`);
+  return { status: problems.length ? 'error' : 'ok', version: lock.version, problems };
+}
+
+export function newChange(root, name) {
+  if (!SLUG.test(name) || name === 'archive') throw new HarnessError('Change ID must be a lowercase hyphenated slug, excluding archive');
+  return guard(root, () => {
+    if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before creating a change');
+    const folder = path.join(root, 'openspec', 'changes', name);
+    safe(root, `openspec/changes/${name}/proposal.md`);
+    if (stat(folder)) throw new HarnessError(`Change already exists: ${name}`);
+    const mapping = { 'proposal.md': 'proposal.md', 'design.md': 'design.md', 'tasks.md': 'tasks.md', 'spec.md': `specs/${name}/spec.md`, '.openspec.yaml': '.openspec.yaml' };
+    const changes = {};
+    for (const [src, dest] of Object.entries(mapping)) {
+      const text = fs.readFileSync(safe(root, `.harness/templates/openspec/${src}`), 'utf8');
+      changes[`openspec/changes/${name}/${dest}`] = Buffer.from(text.replaceAll('{{change_id}}', name));
+    }
+    transaction(root, changes);
+    return { status: 'ok', change: name, path: folder, note: 'Draft only; replace TODOs and validate with OpenSpec' };
+  });
+}
+
+// Product drafts are project-owned and never added to the managed bundle.
+export function newDoc(root, name) {
+  if (!SLUG.test(name)) throw new HarnessError('Document type must be a lowercase hyphenated slug');
+  return guard(root, () => {
+    if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before creating a document');
+    const lock = loadLock(root);
+    if (!(lock.capabilities ?? []).includes('product')) throw new HarnessError('Product capability is not installed');
+    const sourceName = `.harness/capabilities/product/templates/${name}.md`;
+    if (!Object.hasOwn(lock.files, sourceName)) throw new HarnessError(`Unknown product document type: ${name}`);
+    const folder = ['idea', 'research'].includes(name) ? 'discovery' : 'product';
+    const outputName = `docs/${folder}/${name}.md`;
+    if (stat(safe(root, outputName))) throw new HarnessError(`Document already exists: ${outputName}`);
+    transaction(root, { [outputName]: fs.readFileSync(safe(root, sourceName)) });
+    return { status: 'ok', type: name, path: outputName,
+      note: 'Template only; populate from authorized evidence and obtain human approval.' };
+  });
+}
+
+export function doctor(root) {
+  const extensions = process.platform === 'win32' ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+  const tools = {};
+  for (const name of ['git', 'node', 'npm', 'java', 'mvn', 'openspec']) {
+    tools[name] = (process.env.PATH || '').split(path.delimiter).filter(Boolean).some(dir => extensions.some(ext => {
+      try { const p = path.join(dir, name + ext); fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); }
+      catch { return false; }
+    }));
+  }
+  return { ...check(root), tools, note: 'Tool presence only; no commands executed or compatibility claim made' };
+}

package/cli/main.js

@@ -0,0 +1,119 @@
+import { listAdapters, detect, verify, evaluate } from './adapters.js';
+import { listCapabilities, skillCatalog, readSkill } from './capabilities.js';
+import { resolveModules } from './composition.js';
+import { parseArgs } from 'node:util';
+import { SOURCE, readJson, targetRoot, install, check, doctor, newChange, newDoc, loadLock } from './harness.js';
+import path from 'node:path';
+
+const HELP = `aih — install reusable AI development rules into a project
+
+Usage: aih <command> [options]
+  list                 List available adapters and capabilities
+  skills               List installed skill names/descriptions without full content
+  skill <name>         Load one installed skill on demand
+  detect               Suggest adapters with evidence from target files
+  resolve              Validate a module selection and show compatibility warnings
+  verify               Show installed advisory checks (does not execute)
+  eval                 Emit evaluation template, or score --report <file>
+  init                 Install rules and selected adapters
+  update               Apply the installed CLI bundle to the project (no download)
+  check                Check Harness file integrity, not application tests
+  doctor               Check installation and tool presence
+  new-change <id>      Create an OpenSpec draft using installed templates
+  new-doc <type>       Scaffold a Product/Discovery document draft (requires product capability)
+
+Options:
+  --target <directory> Project directory (default: current directory)
+  --detect            init only: opt in to detected stack selection
+  --scope <type>      verify/eval: adapters (default), capabilities, core, all
+  --report <file>     eval only: score a reviewer-completed JSON report
+  --adapters <a,b>     init/resolve: java-spring,react-nextjs,react-native,ai-python,kubernetes,astro
+  --capabilities <a,b> init/resolve: uiux,product,devops,monetization
+  --source <directory> init/update/list/detect/resolve: trusted alternate bundle directory
+  --dry-run           init/update: preview without persistent changes
+  --allow-major       init/update: acknowledge a major version migration
+  -h, --help          Show help
+  -v, --version       Show installed CLI version
+
+Start: init → fill .harness/local.md → ask your AI host to read AGENTS.md.
+The host runs application tests; verify only prints a checklist.
+Update a global CLI with npm install -g @manhd_d/ai-harness@latest,
+then run aih update --dry-run, aih update, and aih check in the project.
+
+Examples:
+  aih init --adapters java-spring --capabilities uiux
+  aih init --adapters astro --capabilities product,uiux
+  aih init --adapters astro --capabilities monetization
+  aih resolve --adapters java-spring,kubernetes --capabilities product,uiux,devops
+  aih skills
+  aih new-doc brd
+  aih new-doc idea
+  aih new-doc research
+  aih new-doc prd-lite
+  aih new-doc srs
+  aih new-doc use-cases
+  aih init --adapters java-spring,kubernetes --capabilities product,devops
+  aih skill harness-product-brd-generation
+  aih skill harness-uiux-figma-design
+  aih update --dry-run
+  aih new-change add-order
+`;
+
+export function main(argv = process.argv.slice(2)) {
+  let args;
+  try {
+    args = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: {
+      target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, source: { type: 'string' },
+      detect: { type: 'boolean' }, report: { type: 'string' }, scope: { type: 'string' },
+      'dry-run': { type: 'boolean' }, 'allow-major': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+    } });
+    const seen = new Set();
+    for (const token of args.tokens.filter(t => t.kind === 'option')) {
+      if (seen.has(token.name)) throw new Error(`Duplicate option: --${token.name}`);
+      seen.add(token.name);
+    }
+    if (args.values.help || !argv.length) { console.log(HELP); return 0; }
+    if (args.values.version) { console.log(readJson(path.join(SOURCE, 'package.json')).version); return 0; }
+    const [command, name, ...extra] = args.positionals;
+    if (!['init', 'update', 'check', 'doctor', 'new-change', 'new-doc', 'list', 'detect', 'resolve', 'verify', 'eval', 'skills', 'skill'].includes(command)) throw new Error(`Unknown command: ${command}`);
+    if (extra.length || (!['new-change', 'new-doc', 'skill'].includes(command) && name !== undefined) || (['new-change', 'new-doc', 'skill'].includes(command) && name === undefined)) throw new Error('Unexpected or missing positional argument; run aih --help');
+    const allowed = new Set(['target', ...(['init', 'update'].includes(command) ? ['source', 'dry-run', 'allow-major'] : []), ...(['init', 'resolve'].includes(command) ? ['adapters', 'capabilities'] : []), ...(command === 'init' ? ['detect'] : []), ...(['list', 'detect', 'resolve'].includes(command) ? ['source'] : []), ...(command === 'eval' ? ['report'] : []), ...(['verify', 'eval'].includes(command) ? ['scope'] : [])]);
+    for (const key of Object.keys(args.values)) if (!allowed.has(key)) throw new Error(`--${key} is not supported for ${command}`);
+    if (args.values.detect && args.values.adapters !== undefined) throw new Error('Choose either --detect or --adapters');
+    for (const key of ['target', 'source', 'adapters', 'capabilities', 'report']) if (args.values[key] !== undefined && !args.values[key].trim()) throw new Error(`--${key} cannot be empty`);
+  } catch (error) { console.error(JSON.stringify({ status: 'error', message: error.message })); return 2; }
+  try {
+    const { values, positionals: [command, name] } = args;
+    const root = targetRoot(values.target ?? process.cwd());
+    let result;
+    if (command === 'init' || command === 'update') {
+      const source = targetRoot(values.source ?? SOURCE);
+      const selection = values.detect ? detect(root, source).adapters : undefined;
+      if (values.detect && !selection.length) throw new Error('No stack detected; choose --adapters explicitly or omit --detect for core only');
+      result = install(root, source, {
+        command, adapters: selection ?? (values.adapters === undefined ? undefined : values.adapters.split(',').map(v => v.trim())),
+        capabilities: values.capabilities === undefined ? undefined : values.capabilities.split(',').map(v => v.trim()),
+        dryRun: values['dry-run'], allowMajor: values['allow-major'],
+      });
+    } else if (command === 'list') { const source = targetRoot(values.source ?? SOURCE); result = { ...listAdapters(source), capabilities: listCapabilities(source) }; }
+    else if (command === 'skills' || command === 'skill') {
+      const state = check(root);
+      if (state.status !== 'ok') throw new Error(`Fix installation drift before loading skills: ${state.problems.join(', ')}`);
+      const lock = loadLock(root);
+      result = command === 'skills' ? skillCatalog(root, lock) : readSkill(root, lock, name);
+    }
+    else if (command === 'resolve') result = resolveModules(targetRoot(values.source ?? SOURCE), {
+      adapters: values.adapters === undefined ? [] : values.adapters.split(',').map(x => x.trim()),
+      capabilities: values.capabilities === undefined ? [] : values.capabilities.split(',').map(x => x.trim()),
+    });
+    else if (command === 'detect') result = detect(root, targetRoot(values.source ?? SOURCE));
+    else if (command === 'verify') result = verify(root, values.scope ?? 'adapters');
+    else if (command === 'eval') result = evaluate(root, values.report, values.scope ?? 'adapters');
+    else if (command === 'new-change') result = newChange(root, name);
+    else if (command === 'new-doc') result = newDoc(root, name);
+    else result = command === 'doctor' ? doctor(root) : check(root);
+    console.log(JSON.stringify(result, null, 2));
+    return ['error', 'fail'].includes(result.status) ? 1 : 0;
+  } catch (error) { console.error(JSON.stringify({ status: 'error', message: error.message })); return 1; }
+}