@manhd_d/ai-harness 0.12.0 → 0.14.0

package/cli/harness.js

@@ -1,4 +1,8 @@
 import fs from 'node:fs';
+import { loadStartConfig } from './start-config.js';
+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';
@@ -11,7 +15,7 @@ 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) {
+export 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 ?? [] };
@@ -55,7 +59,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 +78,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 +95,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) {
@@ -116,7 +121,7 @@ function drift(root, lock) {
   }).map(([name]) => name);
 }
 
-function guard(root, operation) {
+export function guard(root, operation) {
   const filename = safe(root, '.harness-install.lock');
   let fd;
   try { fd = fs.openSync(filename, 'wx', 0o600); }
@@ -128,12 +133,12 @@ function guard(root, operation) {
   finally { fs.closeSync(fd); fs.unlinkSync(filename); }
 }
 
-export function atomicWrite(filename, data) {
+export function atomicWrite(filename, data, mode = 0o644) {
   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.chmodSync(tmp, stat(filename) ? fs.statSync(filename).mode & 0o777 : mode);
     fs.renameSync(tmp, filename);
   } finally { fs.rmSync(tmp, { force: true }); }
 }
@@ -161,18 +166,38 @@ 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)));
     if (command === 'update' && !hasLock) throw new HarnessError('Not installed; run init first');
     const old = hasLock ? loadLock(root) : null;
     const existingAgents = loadAgentConfig(root);
+    loadStartConfig(root);
     loadArtifactContract(root); // Validate project-owned declarations before planning any writes.
     if (agentPreset !== undefined && command !== 'init') throw new HarnessError('Agent preset is supported only by init');
     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,26 +214,26 @@ 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.
     // This does not remove an already tracked machine file from the Git index.
     const ignoreName = '.harness/.gitignore', ignorePath = safe(root, ignoreName);
     const ignore = stat(ignorePath) ? fs.readFileSync(ignorePath, 'utf8') : '';
-    if (ignore.trimEnd().split(/\r?\n/).at(-1) !== '/machine.json') {
-      changes[ignoreName] = Buffer.from(ignore + (ignore && !ignore.endsWith('\n') ? '\n' : '') + '/machine.json\n');
+    if (ignore.trimEnd().split(/\r?\n/).slice(-2).join('\n') !== '/backups/\n/machine.json') {
+      changes[ignoreName] = Buffer.from(ignore + (ignore && !ignore.endsWith('\n') ? '\n' : '') + '/backups/\n/machine.json\n');
     }
     const newLock = encode(lock);
     if (!hasLock || !fs.readFileSync(safe(root, LOCK)).equals(newLock)) changes[LOCK] = newLock;
@@ -222,6 +247,7 @@ export function check(root) {
   const lock = loadLock(root), config = projectConfig(root, undefined, undefined, true);
   const problems = drift(root, lock);
   loadArtifactContract(root);
+  loadStartConfig(root);
   loadAgentConfig(root); // Optional on legacy installs; validate user config without managing its bytes.
   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`);
@@ -257,20 +283,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 +331,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

@@ -1,19 +1,26 @@
+import { startPlan, saveStart, guidedStart } from './start.js';
+import { backupConfig, restoreConfig } from './portable-config.js';
 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 { 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
@@ -24,6 +31,9 @@ Usage: aih <command> [options]
   update               Apply the installed CLI bundle to the project (no download)
   check                Check Harness file integrity, not application tests
   doctor               Check installation, configured paths and tool presence
+  start                Guide intake; reuse saved answers and hand off to your AI host
+  backup               Export user configuration (not docs/checkpoints/secrets)
+  restore              Restore --from backup; --transfer reuses modules/model preferences
   setup                Suggest first-run questions for the AI host (read-only)
   artifacts            Show input/output/storage and connection declarations (read-only)
   ready <id>           Check structural change readiness, not approval
@@ -31,15 +41,25 @@ Usage: aih <command> [options]
   new-doc <type>       Scaffold a locked capability template (default: product)
 
 Options:
+  --goal <type>       start: idea, docs, change, resume (saves with --task)
+  --task <text>       start: task description; --change supplies resume checkpoint ID
+  --input <path/url>  start: seed requirements only if no inputs declared
+  --output <path>     start: draft docs directory; backup: archive path
+  --from <file>       restore: project-relative archive file
+  --transfer          restore: only modules/agent models; omit old autonomy
+  --replace           restore: explicit replacement; automatic before-backup
   --target <directory> Project directory (default: current directory)
   --detect            init only: opt in to detected stack selection
   --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
@@ -48,7 +68,9 @@ Options:
   -h, --help          Show help
   -v, --version       Show installed CLI version
 
-Start: init → fill .harness/local.md → ask your AI host to read AGENTS.md.
+Start: init → start → open your AI host and send the returned host_prompt.
+User settings: .harness/; backup exports only documented user files.
+Restore config before init on a fresh project; --transfer excludes old sources/tasks.
 The host runs application tests; verify prints plans or validates supplied evidence.
 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.
@@ -87,9 +109,9 @@ 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' }, 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' },
+      goal: { type: 'string' }, task: { type: 'string' }, change: { type: 'string' }, input: { type: 'string' }, output: { type: 'string' }, from: { type: 'string' }, transfer: { type: 'boolean' }, replace: { type: 'boolean' }, target: { type: 'string' }, adapters: { type: 'string' }, capabilities: { type: 'string' }, capability: { type: 'string' }, source: { 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,30 +123,41 @@ 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 (!['start', 'backup', 'restore', '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 === 'start') for (const key of ['goal','task','change','input','output','host']) allowed.add(key);
+    if (command === 'backup') allowed.add('output');
+    if (command === 'restore') { for (const key of ['from','transfer','replace','dry-run']) allowed.add(key); if (!args.values.from) throw new Error('restore requires --from'); }
+    if (command === 'start' && !args.values.goal && ['task','change','input','output'].some(key => args.values[key] !== undefined)) throw new Error('start saving options require --goal');
+    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`);
+    for (const key of ['goal', 'task', 'change', 'input', 'output', 'from', '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`);
   } 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') {
+    if (command === 'start') {
+      if (!values.goal && process.stdin.isTTY && process.stdout.isTTY) return guidedStart(root, { host: values.host }).then(value => { console.log(JSON.stringify(value, null, 2)); return value.status === 'blocked' ? 1 : 0; }).catch(error => { console.error(JSON.stringify({ status: 'error', message: error.message })); return 1; });
+      result = values.goal ? saveStart(root, { goal: values.goal, task: values.task, changeId: values.change, input: values.input, output: values.output, host: values.host }) : startPlan(root, values.host);
+    } else if (command === 'backup') result = backupConfig(root, values.output);
+    else if (command === 'restore') result = restoreConfig(root, values.from, { dryRun: values['dry-run'], transfer: values.transfer, replace: values.replace });
+    else 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())),
-        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 +178,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);
@@ -159,9 +195,9 @@ export function main(argv = process.argv.slice(2)) {
     else result = command === 'doctor' ? doctor(root) : check(root);
     if (command === 'init' || command === 'update') result.next_steps = values['dry-run']
       ? ['Review the proposed changes, then repeat without --dry-run.']
-      : ['Run aih setup; ask your AI host to read AGENTS.md and the project-setup workflow.',
+      : ['Run start with the same CLI (aih start or npx --yes @manhd_d/ai-harness start); open your AI host and send host_prompt.',
          'Review local.md/environment.json and artifacts.json/integrations.json; record input/output/storage/ownership, keep credentials in the host and personal paths in ignored machine.json.',
-         'Run aih doctor and review/commit the shared configuration and snapshot.'];
+         'Run doctor and review/commit shared configuration and snapshot. Use backup; copy its file outside the repo. See docs/configuration-backup.md.'];
     if (command === 'new-change') result.next_steps = [
       'Resolve consequential ambiguity with the user and record answers/sources in decisions.json.',
       'When artifact outputs are configured, record create/update/unchanged impact and source-write policy in artifact-impact.json.',

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/portable-config.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { safe, stat, encode, digest, isObject, SOURCE, VERSION, HarnessError } from './files.js';
+import { projectConfig, guard, transaction, atomicWrite } from './harness.js';
+import { loadEnvironment } from './environment.js';
+import { loadAgentConfig } from './agents.js';
+import { loadArtifactContract } from './artifacts.js';
+import { loadStartConfig } from './start-config.js';
+import { resolveModules } from './composition.js';
+
+export const USER_FILES = ['.harness/project.json', '.harness/agents.json', '.harness/artifacts.json',
+  '.harness/integrations.json', '.harness/environment.json', '.harness/local.md', '.harness/start.json', 'openspec/config.yaml'];
+const MAX_FILE = 1024 * 1024, MAX_ARCHIVE = 12 * MAX_FILE;
+const fail = (ok, message) => { if (!ok) throw new HarnessError(message); };
+export const backupName = () => '.harness/backups/config-' + new Date().toISOString().replace(/[:.]/g, '-') + '-' + randomUUID() + '.json';
+function readText(root, name) {
+  const filename = safe(root, name), info = stat(filename);
+  if (!info) return null;
+  fail(info.size <= MAX_FILE, 'Configuration exceeds 1 MiB: ' + name);
+  const bytes = fs.readFileSync(filename), content = bytes.toString('utf8');
+  fail(Buffer.from(content).equals(bytes), 'Configuration must be UTF-8: ' + name);
+  return content;
+}
+export function configArchive(root) {
+  const files = {};
+  for (const name of USER_FILES) {
+    const content = readText(root, name);
+    if (content !== null) files[name] = { content, sha256: digest(Buffer.from(content)) };
+  }
+  fail(Object.hasOwn(files, '.harness/project.json'), 'Missing .harness/project.json; initialize or restore project configuration first');
+  return { schema_version: 1, kind: 'ai-harness-user-config', cli_version: JSON.parse(fs.readFileSync(path.join(SOURCE, 'package.json'))).version,
+    files };
+}
+function validateArchive(value) {
+  fail(isObject(value) && Object.keys(value).sort().join(',') === 'cli_version,files,kind,schema_version'
+    && value.schema_version === 1 && value.kind === 'ai-harness-user-config' && VERSION.test(value.cli_version)
+    && isObject(value.files) && Object.hasOwn(value.files, '.harness/project.json'), 'Unsupported configuration backup schema');
+  for (const [name, file] of Object.entries(value.files)) {
+    fail(USER_FILES.includes(name), 'Backup contains an unapproved configuration path');
+    fail(isObject(file) && Object.keys(file).sort().join(',') === 'content,sha256' && typeof file.content === 'string'
+      && Buffer.byteLength(file.content) <= MAX_FILE && /^[a-f0-9]{64}$/.test(file.sha256)
+      && digest(Buffer.from(file.content)) === file.sha256, 'Backup content/digest mismatch: ' + name);
+  }
+}
+function validateFiles(files) {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'aih-config-'));
+  try {
+    for (const [name, file] of Object.entries(files)) {
+      if (name.endsWith('.json')) { try { JSON.parse(file.content); } catch { throw new HarnessError('Invalid JSON configuration: ' + name); } }
+      const dest = safe(temp, name); fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.writeFileSync(dest, file.content, { mode: 0o600 });
+    }
+    const config = projectConfig(temp, undefined, undefined, true);
+    resolveModules(SOURCE, config);
+    loadAgentConfig(temp); loadArtifactContract(temp); loadEnvironment(temp); loadStartConfig(temp);
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+function outputPath(root, name) {
+  fail(typeof name === 'string' && name.endsWith('.json') && !/^(?:\.git|\.agents|\.claude|node_modules)(?:\/|$)/.test(name) && !USER_FILES.includes(name) && !name.startsWith('.harness/core/') && !name.startsWith('openspec/changes/')
+    && (!name.startsWith('.harness/') || name.startsWith('.harness/backups/')), 'Use a backup path outside active Harness configuration');
+  const filename = safe(root, name); fail(!stat(filename), 'Backup destination already exists'); return filename;
+}
+export function backupConfig(root, output = backupName()) {
+  return guard(root, () => {
+    const archive = configArchive(root); validateArchive(archive); validateFiles(archive.files);
+    const filename = outputPath(root, output);
+    fs.mkdirSync(path.dirname(filename), { recursive: true });
+    fs.writeFileSync(filename, encode(archive), { flag: 'wx', mode: 0o600 });
+    return { status: 'ok', backup: output, included: Object.keys(archive.files),
+      excluded: ['machine.json', 'credentials and native host settings', 'managed snapshot and lock', 'custom skills', 'source/output document contents', 'OpenSpec changes, checkpoints and evidence'],
+      next_steps: ['Copy the backup to a private location outside this project.', 'Keep code/docs/openspec changes and custom skills in your repository backup; configuration backup is not a full project backup.'] };
+  });
+}
+export function restoreConfig(root, from, { dryRun = false, transfer = false, replace = false, writer } = {}) {
+  const filename = safe(root, from); fail(stat(filename)?.size <= MAX_ARCHIVE, 'Missing or oversized configuration backup');
+  const archive = readConfigArchive(filename); validateArchive(archive); validateFiles(archive.files);
+  return guard(root, () => {
+    const files = transfer ? Object.fromEntries(Object.entries(archive.files).filter(([name]) => ['.harness/project.json', '.harness/agents.json'].includes(name))) : archive.files;
+    if (transfer && files['.harness/agents.json']) {
+      const config = JSON.parse(files['.harness/agents.json'].content);
+      delete config.execution.autonomy; // Repository-scoped autonomy decisions never move to a different project.
+      files['.harness/agents.json'] = { content: encode(config).toString() };
+    }
+    const changes = {}, conflicts = [];
+    for (const [name, file] of Object.entries(files)) {
+      const current = readText(root, name);
+      if (current === file.content) continue;
+      if (current !== null) conflicts.push(name);
+      changes[name] = Buffer.from(file.content);
+    }
+    fail(!conflicts.length || replace || dryRun, 'Existing configuration differs: ' + conflicts.join(', ') + '; review --dry-run --replace before replacement');
+    // Validate the prospective merged configuration before any target writes.
+    const merged = {};
+    for (const name of USER_FILES) {
+      const content = changes[name]?.toString() ?? readText(root, name);
+      if (content !== null) merged[name] = { content };
+    }
+    validateFiles(merged);
+    // Validate declared artifact paths against actual target symlinks, not only temporary files.
+    const artifacts = merged['.harness/artifacts.json'] ? JSON.parse(merged['.harness/artifacts.json'].content) : null;
+    for (const group of ['inputs','outputs']) for (const item of Object.values(artifacts?.[group] ?? {})) {
+      if (item.location.path) safe(root, item.location.path + (group === 'outputs' || stat(path.join(root, item.location.path))?.isDirectory() ? '/.artifact-probe' : ''));
+    }
+    let backup = null;
+    if (!dryRun && conflicts.length) {
+      const before = configArchive(root); backup = backupName(); outputPath(root, backup);
+      changes[backup] = encode(before);
+    }
+    if (!dryRun) transaction(root, changes, writer ?? ((filename, data) => atomicWrite(filename, data, filename === (backup ? safe(root, backup) : null) ? 0o600 : 0o644)));
+    return { status: dryRun ? 'planned' : 'ok', mode: transfer ? 'transfer' : 'restore', changes: Object.keys(changes), conflicts,
+      backup, omitted: Object.keys(archive.files).filter(name => !Object.hasOwn(files, name)),
+      next_steps: ['Run init on a fresh project, or update --dry-run then update on an installed project; run check.',
+        transfer ? 'Run start for a new task; rebind input/output locations, commands and connections. Old autonomy declarations were removed.' : 'Run doctor and start; restore docs/checkpoints/evidence separately from your project backup before resume.',
+        'Review host access, models, sources and write policies; importing declarations does not grant permission or connect accounts.'] };
+  });
+}
+function readConfigArchive(filename) {
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { throw new HarnessError('Invalid configuration backup JSON'); }
+}

package/cli/start-config.js

@@ -0,0 +1,15 @@
+import { readConfig } from './project-config.js';
+import { isObject, SLUG, HarnessError, safe, stat } from './files.js';
+export const START_CONFIG = '.harness/start.json';
+export const GOALS = ['idea', 'docs', 'change', 'resume'];
+export function loadStartConfig(root) {
+  const value = readConfig(root, START_CONFIG);
+  if (value === null) { if (stat(safe(root, START_CONFIG))) throw new HarnessError('Invalid start.json schema'); return null; }
+  const text = s => typeof s === 'string' && s.trim().length > 0 && s.length <= 4096 && !/[\x00-\x1f\x7f]/.test(s);
+  if (!isObject(value) || Object.keys(value).some(k => !['schema_version', 'goal', 'task', 'change_id'].includes(k))
+      || value.schema_version !== 1 || !GOALS.includes(value.goal) || !text(value.task)
+      || (value.goal === 'resume' ? !SLUG.test(value.change_id ?? '') || value.change_id === 'archive' : value.change_id !== undefined)) {
+    throw new HarnessError('Invalid start.json schema/goal/task/change_id');
+  }
+  return value;
+}