@manhd_d/ai-harness 0.11.0 → 0.13.0

package/cli/checkpoint.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import { safe, stat, digest, isObject, HarnessError } from './files.js';
+import { readConfig } from './project-config.js';
+import { redacted } from './verification-report.js';
+const requireThat=(v,m)=>{if(!v)throw new HarnessError('Invalid checkpoint: '+m);};
+const text=v=>typeof v==='string'&&v.trim().length>0&&v.length<=1024&&!/[\0\r\n]/.test(v);
+export function checkpointPath(id) {
+  requireThat(typeof id==='string'&&/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(id)&&id!=='archive','change ID');
+  return 'openspec/changes/'+id+'/checkpoint.json';
+}
+function references(root,rows,verify=false) {
+  requireThat(Array.isArray(rows),'reference list');
+  return rows.map(r=>{
+    requireThat(isObject(r)&&text(r.path)&&/^[a-f0-9]{64}$/.test(r.sha256),'local reference/digest');
+    const p=safe(root,r.path),info=stat(p);
+    requireThat(info?.isFile()&&info.size<=1024*1024,'reference missing/oversized');
+    const actual=digest(fs.readFileSync(p));if(verify)requireThat(actual===r.sha256,'evidence digest mismatch');
+    return {...r,current_sha256:actual,current:actual===r.sha256};
+  });
+}
+export function validateCheckpoint(root,id,row) {
+  requireThat(isObject(row)&&row.schema_version===1&&row.change_id===id,'schema/change mismatch');redacted(row);
+  requireThat(text(row.phase)&&text(row.summary)&&text(row.next_action),'phase/summary/next action');
+  requireThat(typeof row.timestamp==='string'&&/T.*(?:Z|[+-]\d\d:\d\d)$/.test(row.timestamp)&&Number.isFinite(Date.parse(row.timestamp)),'timezone timestamp');
+  references(root,row.baseline);
+  requireThat(Array.isArray(row.completed)&&Array.isArray(row.pending)&&Array.isArray(row.blockers),'task lists');
+  const ids=new Set();
+  for(const task of [...row.completed,...row.pending,...(row.in_progress?[row.in_progress]:[])]){
+    requireThat(isObject(task)&&text(task.id)&&!ids.has(task.id)&&text(task.summary),'unique task ID/summary');ids.add(task.id);
+  }
+  for(const task of row.completed)requireThat(references(root,task.evidence,true).length>0,'completed task needs evidence');
+  requireThat(row.in_progress===null||isObject(row.in_progress),'in_progress');
+  requireThat(row.blockers.every(text),'blockers');
+  requireThat(Array.isArray(row.external_sources)&&row.external_sources.every(s=>isObject(s)&&text(s.location)&&text(s.revision)),'external source declarations');
+  requireThat(Array.isArray(row.operations),'operation list');const operations=new Set();
+  for(const op of row.operations){
+    requireThat(isObject(op)&&text(op.id)&&!operations.has(op.id)&&text(op.action)&&text(op.target)&&['prepared','completed','unknown'].includes(op.status),'operation receipt');operations.add(op.id);
+    const refs=references(root,op.evidence,true);if(op.status==='completed')requireThat(refs.length>0,'completed operation needs evidence');
+  }
+  if(row.usage!==undefined){
+    requireThat(isObject(row.usage)&&text(row.usage.source),'measured usage source');
+    for(const k of ['tokens','cost','remaining_tokens'])if(row.usage[k]!==null&&row.usage[k]!==undefined)requireThat(Number.isFinite(row.usage[k])&&row.usage[k]>=0,'usage');
+    if(row.usage.cost!==null&&row.usage.cost!==undefined)requireThat(text(row.usage.currency),'cost currency');
+  }
+  return row;
+}
+export function resumePlan(root,id) {
+  const name=checkpointPath(id),row=readConfig(root,name);requireThat(row!==null,'checkpoint missing');validateCheckpoint(root,id,row);
+  const baseline=references(root,row.baseline),pendingOperations=row.operations.filter(o=>o.status!=='completed');
+  const revalidate=baseline.some(r=>!r.current);
+  return {status:row.blockers.length?'blocked':'planned',executed:false,change_id:id,checkpoint:name,
+    checkpoint_sha256:digest(fs.readFileSync(safe(root,name))),baseline,revalidate_required:revalidate,
+    phase:row.phase,summary:row.summary,completed:row.completed,pending:row.pending,in_progress:row.in_progress,blockers:row.blockers,
+    next_action:row.next_action,operations_to_reconcile:pendingOperations,
+    external_sources:row.external_sources.map(s=>({...s,availability:'unverified'})),usage:row.usage??null,
+    note:'Read-only recovery plan. Reconcile changed sources, completed evidence and unknown/prepared side effects against actual host/remote state before retrying. Receipts and usage are producer-declared; no remote operation, model or quota probe.'};
+}

package/cli/claude.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { safe, stat, HarnessError } from './files.js';
+export const CLAUDE_START = '<!-- ai-harness:claude:start -->';
+export const CLAUDE_END = '<!-- ai-harness:claude:end -->';
+export const CLAUDE_IMPORT = Buffer.from(CLAUDE_START + '\n@AGENTS.md\n' + CLAUDE_END);
+export function claudeBlock(data) {
+  const a=data.indexOf(CLAUDE_START), b=data.indexOf(CLAUDE_END);
+  if(a===-1 && b===-1)return null;
+  if(a===-1 || b<a || data.indexOf(CLAUDE_START,a+CLAUDE_START.length)!==-1 || data.indexOf(CLAUDE_END,b+CLAUDE_END.length)!==-1)
+    throw new HarnessError('CLAUDE.md has invalid Harness markers');
+  return data.subarray(a,b+CLAUDE_END.length);
+}
+function activeText(text) {
+  return text.replace(/^[ \t]*(\x60{3,}|~{3,})[^\r\n]*\r?\n[\s\S]*?^[ \t]*\1[ \t]*(?:\r?\n|$)/gm,'')
+    .replace(/\x60[^\x60\r\n]*\x60/g,'').replace(/<!--[\s\S]*?-->/g,'');
+}
+export function hasAgentsImport(text, nested=false) {
+  return new RegExp('(?:^|\\s)@' + (nested ? '\\.\\./' : '(?:\\./)?') + 'AGENTS\\.md(?=\\s|$)').test(activeText(text));
+}
+export function linkClaude(existing) {
+  const block=claudeBlock(existing);
+  if(block){if(block.toString().replaceAll('\r\n','\n')!==CLAUDE_IMPORT.toString())throw new HarnessError('CLAUDE managed import differs; reconcile before linking');return existing;}
+  if(hasAgentsImport(existing.toString('utf8')))return existing;
+  const newline=existing.includes(Buffer.from('\r\n'))?'\r\n':'\n';
+  const separator=existing.length?(existing.at(-1)===10?newline:newline+newline):'';
+  return Buffer.concat([existing,Buffer.from(separator),Buffer.from(CLAUDE_IMPORT.toString().replaceAll('\n',newline)+newline)]);
+}
+export function claudeReport(root) {
+  const files=[];
+  for(const name of ['CLAUDE.md','CLAUDE.local.md','.claude/CLAUDE.md']){
+    const p=safe(root,name),info=stat(p);if(!info)continue;
+    if(info.size>1024*1024)throw new HarnessError('Claude instruction file exceeds 1 MiB: '+name);
+    const body=fs.readFileSync(p,'utf8');
+    files.push({path:name,imports_agents:hasAgentsImport(body,name.startsWith('.claude/'))});
+  }
+  const linked=files.some(f=>f.imports_agents);
+  return {status:files.length&&!linked?'warning':'unverified',files,
+    warnings:files.length&&!linked?['Claude instructions may shadow AGENTS.md. Review actual version/settings; opt in to init/update --link-claude or configure the host to load both.']:[],
+    note:'Local import inspection only. Ancestor/global files, host version/plugin/settings and actual instruction loading are unverified; confirm with Claude /context. No native settings are changed.'};
+}

package/cli/comparison.js

@@ -0,0 +1,46 @@
+import { isObject, HarnessError } from './files.js';
+import { redacted } from './verification-report.js';
+const tasks=['spring-api','transaction-defect','maven-onboarding'];
+const metrics=['human_correction_rounds','unnecessary_questions','accepted_criteria','total_criteria','elapsed_seconds','tokens','cost'];
+const requireThat=(v,m)=>{if(!v)throw new HarnessError('Invalid real-task comparison: '+m);};
+export function comparisonTemplate(){
+ return {schema_version:1,status:'unperformed',metadata:{model:null,runtime:null,harness_commit:null,starting_commit:null,budget:null},tasks,
+   runs:tasks.flatMap(task=>['without-harness','with-harness'].flatMap(condition=>[1,2,3].map(repeat=>({task_id:task,condition,repeat,status:'UNPERFORMED',evidence:[],usage_source:null,currency:null,...Object.fromEntries(metrics.map(m=>[m,null]))}))))};
+}
+function distribution(values) {
+ if(!values.length)return {observed_runs:0,median:null,min:null,max:null};
+ const sorted=[...values].sort((a,b)=>a-b),i=Math.floor(sorted.length/2);
+ return {observed_runs:values.length,median:sorted.length%2?sorted[i]:(sorted[i-1]+sorted[i])/2,min:sorted[0],max:sorted.at(-1)};
+}
+export function summarizeComparison(report){
+ requireThat(isObject(report)&&report.schema_version===1&&isObject(report.metadata),'schema');redacted(report);
+ requireThat(Array.isArray(report.tasks)&&report.tasks.length===3&&new Set(report.tasks).size===3&&report.tasks.every(t=>typeof t==='string'&&/^[a-z][a-z0-9-]*$/.test(t)),'three unique task IDs');
+ requireThat(Array.isArray(report.runs)&&report.runs.length===18,'18 independent run slots');
+ const ids=new Set();
+ for(const row of report.runs){
+  requireThat(isObject(row)&&report.tasks.includes(row.task_id)&&['with-harness','without-harness'].includes(row.condition)&&[1,2,3].includes(row.repeat),'task/condition/repeat');
+  const id=row.task_id+'/'+row.condition+'/'+row.repeat;requireThat(!ids.has(id),'duplicate run');ids.add(id);
+  requireThat(['UNPERFORMED','COMPLETED','FAILED','INTERRUPTED','BLOCKED'].includes(row.status),'status');
+  requireThat(Array.isArray(row.evidence)&&row.evidence.every(v=>typeof v==='string'&&v.trim()&&!/[\0\r\n]/.test(v)),'evidence');
+  if(row.status!=='UNPERFORMED')requireThat(row.evidence.length>0,'observed run needs evidence');
+  for(const m of metrics){requireThat(row[m]===null||(typeof row[m]==='number'&&Number.isFinite(row[m])&&row[m]>=0),'metric '+m);
+    if(['human_correction_rounds','unnecessary_questions','accepted_criteria','total_criteria','tokens'].includes(m)&&row[m]!==null)requireThat(Number.isSafeInteger(row[m]),'integer metric '+m);
+  }
+  if(row.status==='UNPERFORMED')requireThat(metrics.every(m=>row[m]===null),'unperformed metrics must stay null');
+  if(row.accepted_criteria!==null)requireThat(row.total_criteria!==null&&row.accepted_criteria<=row.total_criteria,'accepted/total criteria');
+  if(row.tokens!==null||row.cost!==null)requireThat(typeof row.usage_source==='string'&&row.usage_source.trim(),'actual usage source');
+  if(row.cost!==null)requireThat(typeof row.currency==='string'&&row.currency.trim(),'cost currency');
+ }
+ const currencies=new Set(report.runs.filter(r=>r.cost!==null).map(r=>r.currency));
+ requireThat(currencies.size<=1,'mixed cost currencies');
+ for(const task of report.tasks)requireThat(new Set(report.runs.filter(r=>r.task_id===task&&r.total_criteria!==null).map(r=>r.total_criteria)).size<=1,'inconsistent acceptance totals');
+ const observed=report.runs.some(r=>r.status!=='UNPERFORMED');
+ if(observed)for(const key of ['model','runtime','harness_commit','starting_commit'])requireThat(typeof report.metadata[key]==='string'&&report.metadata[key].trim(),'metadata '+key);
+ const summaries=report.tasks.flatMap(task=>['without-harness','with-harness'].map(condition=>{
+  const rows=report.runs.filter(r=>r.task_id===task&&r.condition===condition);
+  return {task_id:task,condition,statuses:Object.fromEntries(['UNPERFORMED','COMPLETED','FAILED','INTERRUPTED','BLOCKED'].map(s=>[s,rows.filter(r=>r.status===s).length])),
+    metrics:Object.fromEntries(metrics.map(m=>[m,distribution(rows.map(r=>r[m]).filter(v=>v!==null))]))};
+ }));
+ return {status:'ok',executed:false,observed_runs:report.runs.filter(r=>r.status!=='UNPERFORMED').length,summaries,
+  note:'Summarizes manually supplied observations only. Null is unknown, not zero. Retain all failures/interruptions; independently review evidence, equal acceptance criteria and matching model/task/budget. No productivity claim or model execution is inferred.'};
+}

package/cli/composition.js

@@ -73,6 +73,7 @@ export function validateRegistry(source) {
   const graph = new Map();
   for (const {kind,id,data} of entries) {
     const owner=moduleRef(kind,id);
+    if (data.asset_owner && !declared.has(moduleRef('capability',data.asset_owner))) throw new HarnessError('Unknown capability asset owner');
     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}`);

package/cli/files.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { claudeBlock } from './claude.js';
 import { fileURLToPath } from 'node:url';
 
 // Resolve from the installed package, never the consumer's cwd or npm's bin symlink.
@@ -100,7 +101,7 @@ 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;
+  return name === 'AGENTS.md' ? block(data) : name === 'CLAUDE.md' ? claudeBlock(data) : data;
 }
 
 export function manifest(source) {

package/cli/harness.js

@@ -1,4 +1,7 @@
 import fs from 'node:fs';
+import { checkpointPath, validateCheckpoint } from './checkpoint.js';
+import { readConfig } from './project-config.js';
+import { claudeReport, claudeBlock, linkClaude } from './claude.js';
 import { emptyEnvironment, environmentReport } from './environment.js';
 import { AGENT_CONFIG, agentDefaults, loadAgentConfig } from './agents.js';
 import { reviewVerification, techspecEvidence } from './verification-report.js';
@@ -55,7 +58,7 @@ export function bundle(source, config) {
   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 folder of ['core', 'integrations', 'templates', ...adapters.map(a => `adapters/${a}`), ...capabilities.map(c => `capabilities/${c}`), ...[...new Set(capabilities.map(c => loadCapability(source, c).asset_owner).filter(Boolean))].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;
@@ -74,11 +77,12 @@ export function bundle(source, config) {
     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 data = fs.readFileSync(safe(source, `capabilities/${info.asset_owner ?? c}/skills/${name}/SKILL.md`));
+      if (Object.hasOwn(files, dest) && !files[dest].equals(data)) throw new HarnessError(`Skill collision: ${name}`);
+      files[dest] = data;
     }
   }
-  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')
+  const capabilityLinks = capabilities.map(c => `- For ${c} tasks, read \`.harness/capabilities/${loadCapability(source,c).asset_owner ?? c}/workflows/\` and discover relevant \`.agents/skills/harness-${loadCapability(source,c).asset_owner ?? 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');
@@ -90,7 +94,7 @@ export function bundle(source, config) {
 }
 
 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));
+  return name === 'AGENTS.md' || name === 'CLAUDE.md' || ['.harness/core/', '.harness/adapters/', '.harness/capabilities/', '.harness/integrations/', '.harness/templates/', '.agents/skills/harness-', '.claude/skills/harness-'].some(prefix => name.startsWith(prefix));
 }
 
 export function loadLock(root) {
@@ -161,7 +165,7 @@ export function transaction(root, changes, writer = atomicWrite) {
   }
 }
 
-export function install(root, source, { command = 'init', adapters, capabilities, agentPreset, dryRun = false, allowMajor = false, writer } = {}) {
+export function install(root, source, { command = 'init', adapters, capabilities, agentPreset, dryRun = false, allowMajor = false, host, linkClaude: linkClaudeOpt = false, claudeSkills = false, writer } = {}) {
   assertSeparate(root, source);
   return guard(root, () => {
     const hasLock = Boolean(stat(safe(root, LOCK)));
@@ -173,6 +177,25 @@ export function install(root, source, { command = 'init', adapters, capabilities
     if (agentPreset !== undefined && existingAgents) throw new HarnessError('agents.json is project-owned; edit it explicitly instead of applying an init preset');
     const config = projectConfig(root, adapters, capabilities, hasLock);
     const { files, lock, warnings } = bundle(source, config);
+    const claudeName = 'CLAUDE.md', claudePath = safe(root, claudeName);
+    const existingClaude = stat(claudePath) ? fs.readFileSync(claudePath) : Buffer.alloc(0);
+    if (existingClaude.length > 1024 * 1024) throw new HarnessError('CLAUDE.md exceeds 1 MiB');
+    let linkedClaude;
+    if (linkClaudeOpt || old?.files[claudeName]) {
+      linkedClaude = linkClaude(existingClaude);
+      const owned = claudeBlock(linkedClaude);
+      if (owned) { files[claudeName] = owned; lock.files[claudeName] = digest(owned); }
+    }
+    if (claudeSkills || Object.keys(old?.files ?? {}).some(p => p.startsWith('.claude/skills/harness-'))) {
+      for (const [name, data] of Object.entries(files).filter(([p]) => /^\.agents\/skills\/harness-[a-z0-9-]+\/SKILL\.md$/.test(p))) {
+        const id = name.split('/')[2], description = data.toString().match(/^description: (.+)$/m)?.[1] ?? 'Load canonical Harness instructions.';
+        const destination = '.claude/skills/' + id + '/SKILL.md';
+        files[destination] = Buffer.from('---\nname: ' + id + '\ndescription: ' + description + '\n---\n\nRead the complete canonical project file ' + String.fromCharCode(96) + name + String.fromCharCode(96) + ' before applying this skill. Follow its inputs, procedure, constraints and handoff; do not substitute this wrapper for the full instructions.\n');
+        lock.files[destination] = digest(files[destination]);
+      }
+    }
+    lock.files = Object.fromEntries(Object.entries(lock.files).sort(([a],[b]) => a.localeCompare(b)));
+    lock.bundle_sha256 = digest(encode(lock.files));
     if (old) {
       const conflicts = drift(root, old);
       if (conflicts.length) throw new HarnessError(`Managed files changed; reconcile in Git before updating: ${conflicts.join(', ')}`);
@@ -189,18 +212,18 @@ export function install(root, source, { command = 'init', adapters, capabilities
       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;
+        changes[name] = name === 'AGENTS.md' ? mergeAgents(existing, data) : name === 'CLAUDE.md' ? linkedClaude : data;
       }
     }
     if (old) for (const name of Object.keys(old.files)) if (!Object.hasOwn(files, name)) changes[name] = null;
     const seeds = {
-      [AGENT_CONFIG]: encode(agentDefaults(source, agentPreset ?? 'recommended')),
+      [AGENT_CONFIG]: encode(agentDefaults(source, agentPreset ?? 'recommended', host)),
       [CONFIG]: encode(config),
       [ARTIFACTS]: encode(emptyArtifacts()),
       [INTEGRATIONS]: encode(emptyIntegrations()),
       '.harness/environment.json': encode(emptyEnvironment()),
       '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\n## Development conventions\nRecord scope/mode (new, maintain or mixed), authoritative source paths, module boundaries, reusable public APIs, naming/error/test conventions and configured checks. Link existing guides instead of duplicating them. Unknowns are not approved defaults; the AI host inspects evidence and asks only consequential questions.\n'),
+      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n\n## Stack\nstack: unknown\nRecord actual dependency versions and approved design sources. This field does not select technology.\n\n## Development conventions\nRecord scope/mode (new, maintain or mixed), authoritative source paths, module boundaries, reusable public APIs, naming/error/test conventions and configured checks. Link existing guides instead of duplicating them. Unknowns are not approved defaults; the AI host inspects evidence and asks only consequential questions.\n'),
     };
     for (const [name, data] of Object.entries(seeds)) if (!stat(safe(root, name))) changes[name] = data;
     // Project-owned ignore file: preserve all prior rules, place our anchored rule last.
@@ -257,20 +280,31 @@ export function newDoc(root, name, capability = 'product', options = {}) {
   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(capability)) {
+    const selected = lock.capabilities ?? [];
+    const profile = selected.find(id => {
+      const info = loadCapability(path.join(root, '.harness'), id);
+      return info.asset_owner === capability && info.templates.includes('templates/' + name + '.md');
+    });
+    if (!selected.includes(capability) && !profile) {
       throw new HarnessError(capability === 'product' ? 'Product capability is not installed' : `Capability is not installed: ${capability}`);
     }
-    const sourceName = `.harness/capabilities/${capability}/templates/${name}.md`;
+    const info = loadCapability(path.join(root, '.harness'), capability);
+    const owner = info.asset_owner ?? capability;
+    const sourceName = info.template_aliases?.['templates/' + name + '.md']
+      ? '.harness/' + info.template_aliases['templates/' + name + '.md']
+      : `.harness/capabilities/${owner}/templates/${name}.md`;
     if (!Object.hasOwn(lock.files, `.harness/capabilities/${capability}/capability.json`)) {
       throw new HarnessError(`Capability metadata is not locked: ${capability}`);
     }
     const declared = loadCapability(path.join(root, '.harness'), capability).templates;
     if (!declared.includes(`templates/${name}.md`)) throw new HarnessError(`Unknown document type for ${capability}: ${name}`);
     if (!Object.hasOwn(lock.files, sourceName)) throw new HarnessError(`Document template is not locked: ${capability}/${name}`);
-    if (options.report && (capability !== 'product' || name !== 'techspec')) throw new HarnessError('--report is supported only for product techspec');
+    if (options.report && (owner !== 'product' || name !== 'techspec')) throw new HarnessError('--report is supported only for product techspec');
     const content = options.report ? techspecEvidence(reviewVerification(root, options.report)) : fs.readFileSync(safe(root, sourceName), 'utf8');
     const folder = capability === 'product' && ['idea', 'research'].includes(name) ? 'discovery' : capability;
-    const route = docRoute(root, capability, name);
+    const outputs = loadArtifactContract(root).artifacts.outputs;
+    const routeCapability = Object.values(outputs).some(a => a.kind === 'docs' && (a.capability ?? 'product') === capability) ? capability : owner;
+    const route = docRoute(root, routeCapability, name);
     if (route?.external) return { status: 'planned', type: name, capability, destination: route.destination,
       write_policy: route.write_policy, executed: false,
       template: content,
@@ -294,5 +328,26 @@ export function doctor(root) {
   }
   const state = check(root), environment = environmentReport(root);
   return { ...state, status: state.status !== 'ok' || environment.problems.length ? 'error' : 'ok',
-    tools, environment, artifacts: artifactReport(root), note: 'Tool presence only; no commands executed or compatibility claim made. Configured project tools take precedence over generic PATH hints.' };
+    tools, environment, claude: claudeReport(root), artifacts: artifactReport(root), note: 'Tool presence only; no commands executed or compatibility claim made. Configured project tools take precedence over generic PATH hints.' };
+}
+
+export function saveCheckpoint(root, id, report, expected) {
+  return guard(root, () => {
+    if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before checkpointing');
+    const name = checkpointPath(id);
+    if (!stat(safe(root, 'openspec/changes/' + id + '/tasks.md'))) throw new HarnessError('Checkpoint requires an existing change');
+    const row = validateCheckpoint(root, id, readConfig(root, report));
+    const destination = safe(root, name), previous = stat(destination) ? fs.readFileSync(destination) : null;
+    if (previous && (!/^[a-f0-9]{64}$/.test(expected ?? '') || digest(previous) !== expected)) throw new HarnessError('Checkpoint exists or changed; resume, reconcile, then supply --expected digest');
+    if (!previous && expected !== undefined) throw new HarnessError('Expected checkpoint is missing');
+    const changes = { [name]: encode(row) };
+    if (previous) {
+      const history = 'openspec/changes/' + id + '/checkpoint-history/' + digest(previous) + '.json';
+      const p = safe(root, history);
+      if (stat(p) && !fs.readFileSync(p).equals(previous)) throw new HarnessError('Checkpoint history collision');
+      if (!stat(p)) changes[history] = previous;
+    }
+    transaction(root, changes);
+    return { status: 'ok', checkpoint: name, checkpoint_sha256: digest(encode(row)), executed: false, note: 'Saved project-owned handoff/evidence declarations. Execution and remote state still require host verification.' };
+  });
 }

package/cli/main.js

@@ -4,16 +4,21 @@ import { resolveModules } from './composition.js';
 import { parseArgs } from 'node:util';
 import { setupPlan } from './environment.js';
 import { ready } from './readiness.js';
+import { resumePlan } from './checkpoint.js';
+import { agentPlan } from './agents.js';
 import { adaptiveVerification } from './verification.js';
 import { reviewVerification } from './verification-report.js';
 import { artifactReport } from './artifacts.js';
-import { SOURCE, readJson, targetRoot, install, check, doctor, newChange, newDoc, loadLock } from './harness.js';
+import { SOURCE, readJson, targetRoot, install, check, doctor, newChange, newDoc, loadLock, saveCheckpoint } 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
+  checkpoint <id>      Save a validated --report handoff; replace with --expected digest
+  resume <id>          Inspect checkpoint freshness and side effects before continuation
+  agents               Show installed agent contracts and declared model/skill routing
   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
@@ -36,10 +41,13 @@ Options:
   --stage <type>      ready only: implement (default) or review
   --capability <id>   new-doc only: installed template owner (default: product)
   --agent-preset <id> init only: recommended (default), economy, custom; no overwrite
-  --host <id>         setup only: codex,claude-code,gemini-cli,cursor,copilot or custom host ID
+  --link-claude       init/update: opt in to a managed CLAUDE.md import
+  --claude-skills     init/update: opt in to canonical .claude/skills wrappers
+  --host <id>         init/setup/agents: codex,claude-code,gemini-cli,cursor,copilot or custom host ID
   --scope <type>      verify/eval: adapters (default), capabilities, core, all
   --adaptive          verify: discover a read-only project verification plan
-  --report <file>     eval: score; verify: validate evidence; new-doc techspec: link evidence
+  --expected <sha>    checkpoint: observed prior checkpoint digest for replacement
+  --report <file>     checkpoint: save handoff; eval: score; verify: validate evidence; new-doc techspec: link evidence
   --adapters <a,b>     init/resolve: java-spring,react-nextjs,react-native,ai-python,kubernetes,astro
   --capabilities <a,b> init/resolve: uiux,product,architecture,delivery,devops,monetization
   --source <directory> init/update/list/detect/resolve: trusted alternate bundle directory
@@ -88,8 +96,8 @@ export function main(argv = process.argv.slice(2)) {
   try {
     args = parseArgs({ args: argv, allowPositionals: true, strict: true, tokens: true, options: {
       target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, capability: { type: 'string' }, source: { type: 'string' },
-      'agent-preset': { type: 'string' }, host: { type: 'string' },
-      adaptive: { type: 'boolean' }, detect: { type: 'boolean' }, report: { type: 'string' }, scope: { type: 'string' }, stage: { type: 'string' },
+      'agent-preset': { type: 'string' }, host: { type: 'string' }, expected: { type: 'string' },
+      'link-claude': { type: 'boolean' }, 'claude-skills': { type: 'boolean' }, adaptive: { type: 'boolean' }, detect: { type: 'boolean' }, report: { type: 'string' }, scope: { type: 'string' }, stage: { type: 'string' },
       'dry-run': { type: 'boolean' }, 'allow-major': { type: 'boolean' },
       help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
     } });
@@ -101,15 +109,17 @@ export function main(argv = process.argv.slice(2)) {
     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', 'setup', 'ready', 'artifacts'].includes(command)) throw new Error(`Unknown command: ${command}`);
-    if (extra.length || (!['new-change', 'new-doc', 'skill', 'ready'].includes(command) && name !== undefined) || (['new-change', 'new-doc', 'skill', 'ready'].includes(command) && name === undefined)) throw new Error('Unexpected or missing positional argument; run aih --help');
+    if (!['init', 'update', 'check', 'doctor', 'new-change', 'new-doc', 'list', 'detect', 'resolve', 'verify', 'eval', 'skills', 'skill', 'setup', 'ready', 'artifacts', 'agents', 'checkpoint', 'resume'].includes(command)) throw new Error(`Unknown command: ${command}`);
+    if (extra.length || (!['new-change', 'new-doc', 'skill', 'ready', 'checkpoint', 'resume'].includes(command) && name !== undefined) || (['new-change', 'new-doc', 'skill', 'ready', 'checkpoint', 'resume'].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'] : []), ...(command === 'ready' ? ['stage'] : []), ...(['verify', 'eval'].includes(command) ? ['scope'] : [])]);
+    if (command === 'checkpoint') { allowed.add('report'); allowed.add('expected'); if (!args.values.report) throw new Error('checkpoint requires --report'); }
     if (command === 'new-doc') { allowed.add('capability'); allowed.add('report'); }
     if (command === 'verify') { allowed.add('adaptive'); allowed.add('report'); }
     if (args.values.adaptive && args.values.report) throw new Error('Choose --adaptive or --report');
     if (args.values.scope && (args.values.adaptive || (command === 'verify' && args.values.report))) throw new Error('--scope applies only to advisory checks');
     if (command === 'init') allowed.add('agent-preset');
-    if (command === 'setup') allowed.add('host');
+    if (['setup','agents','init'].includes(command)) allowed.add('host');
+    if (['init','update'].includes(command)) { allowed.add('link-claude'); allowed.add('claude-skills'); }
     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', 'capability', 'report', 'agent-preset', 'host']) if (args.values[key] !== undefined && !args.values[key].trim()) throw new Error(`--${key} cannot be empty`);
@@ -124,7 +134,7 @@ export function main(argv = process.argv.slice(2)) {
       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())),
-        agentPreset: values['agent-preset'],
+        agentPreset: values['agent-preset'], host: values.host, linkClaude: values['link-claude'], claudeSkills: values['claude-skills'],
         capabilities: values.capabilities === undefined ? undefined : values.capabilities.split(',').map(v => v.trim()),
         dryRun: values['dry-run'], allowMajor: values['allow-major'],
       });
@@ -145,6 +155,9 @@ export function main(argv = process.argv.slice(2)) {
       result = values.report ? reviewVerification(root, values.report) : values.adaptive ? adaptiveVerification(root, SOURCE) : verify(root, values.scope ?? 'adapters');
     }
     else if (command === 'eval') result = evaluate(root, values.report, values.scope ?? 'adapters');
+    else if (command === 'checkpoint') result = saveCheckpoint(root, name, values.report, values.expected);
+    else if (command === 'resume') { if (check(root).status !== 'ok') throw new Error('Fix installation drift before resume'); result = resumePlan(root, name); }
+    else if (command === 'agents') { if (check(root).status !== 'ok') throw new Error('Fix installation drift before reading agents'); result = agentPlan(root, values.host); }
     else if (command === 'artifacts') {
       if (check(root).status !== 'ok') throw new Error('Fix installation drift before reading artifact declarations');
       result = artifactReport(root);

package/cli/maven.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, HarnessError } from './files.js';
+
+// A bounded metadata reader, not an XML runtime. No entities, interpolation or parent traversal.
+export function mavenModules(root) {
+  const files=[],warnings=[],visited=new Set();let total=0;
+  function visit(file,depth){
+    if(visited.has(file))return;visited.add(file);
+    if(visited.size>64)throw new HarnessError('Maven discovery exceeds 64 POM files');
+    const p=safe(root,file),info=stat(p);if(!info){if(depth>0)warnings.push({file,reason:'Declared POM is missing'});return;}
+    if(info.size>1024*1024)throw new HarnessError('Maven POM exceeds 1 MiB: '+file);
+    total+=info.size;if(total>4*1024*1024)throw new HarnessError('Maven discovery exceeds 4 MiB total');
+    const body=fs.readFileSync(p,'utf8').replace(/<!--[\s\S]*?-->/g,'');
+    if(/<!DOCTYPE|<!ENTITY|<!\[CDATA\[/i.test(body))throw new HarnessError('Unsupported XML declarations in '+file);
+    files.push({file,body,depth});
+    if(depth>=2){if(/<(?:[\w.-]+:)?modules\b/.test(body))warnings.push({file,reason:'Depth limit reached; deeper modules not scanned'});return;}
+    for(const section of body.matchAll(/<(?:[\w.-]+:)?modules\b[^>]*>([\s\S]*?)<\/(?:[\w.-]+:)?modules\s*>/g)){
+      for(const item of section[1].matchAll(/<(?:[\w.-]+:)?module\b[^>]*>([^<]*)<\/(?:[\w.-]+:)?module\s*>/g)){
+        const value=item[1].trim();
+        if(!value || /[$&\\]/.test(value) || value.split('/').some(x=>x==='..'||x==='.') || value.startsWith('/'))
+          throw new HarnessError('Unsupported or unsafe Maven module path in '+file);
+        const child=path.posix.join(path.posix.dirname(file),value,'pom.xml');safe(root,child);visit(child,depth+1);
+      }
+    }
+  }
+  visit('pom.xml',0);return {files,warnings};
+}

package/cli/verification-report.js

@@ -11,7 +11,7 @@ const errorKinds = ['timeout', 'network', 'http', 'application', 'assertion', 'e
 const finite = n => typeof n === 'number' && Number.isFinite(n) && n >= 0;
 const iso = s => text(s) && /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(s) && Number.isFinite(Date.parse(s));
 const secretKey = /^(password|passwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|authorization|cookie|credentials?)$/i;
-function redacted(value) {
+export function redacted(value) {
   if (typeof value === 'string') {
     assert(!/Bearer\s+[A-Za-z0-9._~-]{8,}/i.test(value), 'Redact bearer credentials before verification');
     return;

package/config/agents.claude-code.json

@@ -0,0 +1,100 @@
+{
+  "schema_version": 1,
+  "provider": "anthropic",
+  "defaultModel": "sonnet",
+  "defaultReasoning": "medium",
+  "models": {
+    "economy": "haiku",
+    "balanced": "sonnet",
+    "premium": "opus"
+  },
+  "agents": {
+    "core:implementer": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "core:planner": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:security-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:test-engineer": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "core:orchestrator": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "core:documentation": {
+      "model": "@economy",
+      "reasoning": "low"
+    },
+    "product:business-analyst": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:product-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:product-owner": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:project-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "product:requirements-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "architecture:solution-architect": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "architecture:architecture-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "delivery:project-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "core:project-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "analysis:business-analyst": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "analysis:requirements-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "discovery:product-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "discovery:product-owner": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    }
+  },
+  "execution": {
+    "mode": "hybrid",
+    "maxConcurrentAgents": 2,
+    "maxRounds": 3,
+    "autoEscalateToPremium": false
+  },
+  "hosts": {}
+}

package/config/agents.default.json

@@ -1,12 +1,12 @@
 {
   "schema_version": 1,
-  "provider": "openai",
-  "defaultModel": "gpt-6.1-sol",
+  "provider": "host",
+  "defaultModel": "host-default",
   "defaultReasoning": "medium",
   "models": {
-    "economy": "gpt-6-luna",
-    "balanced": "gpt-6.1-sol",
-    "premium": "gpt-6-astra"
+    "economy": "host-default",
+    "balanced": "host-default",
+    "premium": "host-default"
   },
   "agents": {
     "core:implementer": {
@@ -68,6 +68,26 @@
     "delivery:project-manager": {
       "model": "@balanced",
       "reasoning": "medium"
+    },
+    "core:project-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "analysis:business-analyst": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "analysis:requirements-reviewer": {
+      "model": "@balanced",
+      "reasoning": "high"
+    },
+    "discovery:product-manager": {
+      "model": "@balanced",
+      "reasoning": "medium"
+    },
+    "discovery:product-owner": {
+      "model": "@balanced",
+      "reasoning": "medium"
     }
   },
   "execution": {