@manhd_d/ai-harness 0.13.0 → 0.15.0

package/cli/journey-evidence.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import { safe, stat, digest, isObject, HarnessError } from './files.js';
+const text = value => typeof value === 'string' && value.trim().length > 0 && !/[\0\r\n]/.test(value);
+const assert = (ok, message) => { if (!ok) throw new HarnessError('Invalid user journey: ' + message); };
+const interactions = { web: 'browser', mobile: 'device', cli: 'terminal', api: 'http' };
+export function reviewJourney(root, row) {
+  if (row.journey === undefined) return { acceptance_scope: 'not-declared' };
+  const journey = row.journey;
+  assert(isObject(journey) && Object.keys(journey).every(k => ['surface', 'actor', 'entrypoint', 'interaction', 'dependencies', 'attachments'].includes(k)), 'fields');
+  assert(Object.hasOwn(interactions, journey.surface) && text(journey.actor) && text(journey.entrypoint), 'surface/actor/entrypoint');
+  assert(journey.interaction === interactions[journey.surface], 'surface must be exercised by its actual interface');
+  assert(['real', 'mocked', 'not-applicable', 'unknown'].includes(journey.dependencies), 'dependency classification');
+  if (/^https?:\/\//.test(journey.entrypoint)) {
+    let url; try { url = new URL(journey.entrypoint); } catch { throw new HarnessError('Invalid user journey: entrypoint URL'); }
+    assert(!url.username && !url.password && ![...url.searchParams.keys()].some(k => /^(?:token|access_token|api[_-]?key|password|secret|authorization|sig|signature)$/i.test(k)), 'entrypoint must not contain credentials');
+  }
+  const method = { 'browser-e2e': 'web', 'mobile-e2e': 'mobile', 'cli-e2e': 'cli', api: 'api', 'backend-e2e': 'api', authorization: 'api', security: 'api' }[row.method];
+  assert(method ? method === journey.surface : ['end-user', 'business-workflow'].includes(row.method), 'scenario method/surface mismatch');
+  assert(Array.isArray(journey.attachments) && journey.attachments.length <= 20, 'attachment list (max 20)');
+  const kinds = { screenshot: /\.(?:png|jpe?g|webp)$/i, trace: /\.zip$/i, video: /\.(?:webm|mp4)$/i, report: /\.(?:html|json)$/i };
+  const paths = new Set(); let totalSize = 0;
+  for (const ref of journey.attachments) {
+    assert(isObject(ref) && Object.keys(ref).sort().join(',') === 'kind,path,sha256' && Object.hasOwn(kinds, ref.kind)
+      && text(ref.path) && kinds[ref.kind].test(ref.path) && /^[a-f0-9]{64}$/.test(ref.sha256), 'attachment type/path/digest');
+    assert(!paths.has(ref.path), 'duplicate attachment'); paths.add(ref.path);
+    const filename = safe(root, ref.path), info = stat(filename);
+    assert(info?.isFile() && info.size > 0 && info.size <= 50 * 1024 * 1024, 'attachment missing/empty/over 50 MiB');
+    totalSize += info.size; assert(totalSize <= 100 * 1024 * 1024, 'attachments exceed 100 MiB total');
+    assert(digest(fs.readFileSync(filename)) === ref.sha256, 'attachment digest mismatch');
+  }
+  const scope = !row.executed ? 'not-executed' : journey.dependencies === 'mocked' ? 'interface-only'
+    : journey.dependencies === 'unknown' ? 'unverified-dependencies' : 'end-user';
+  return { journey, acceptance_scope: scope };
+}

package/cli/kiro.js

@@ -0,0 +1,15 @@
+import { encode, HarnessError } from './files.js';
+
+export const KIRO_HOOK = '.kiro/hooks/harness-session.json';
+export function kiroPayload(files) {
+  if (!Object.hasOwn(files, ".agents/skills/harness-start/SKILL.md")) throw new HarnessError("Kiro onboarding requires a source bundle containing harness-start; use a reviewed update");
+  const result = {};
+  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];
+    const description = data.toString().match(/^description: (.+)$/m)?.[1] ?? 'Load canonical Harness instructions.';
+    result['.kiro/skills/' + id + '/SKILL.md'] = Buffer.from('---\nname: ' + id + '\ndescription: ' + description + '\n---\n\nRead the complete canonical project file `' + name + '` before applying this skill. Follow its inputs, procedure, constraints and handoff.\n');
+  }
+  result[KIRO_HOOK] = encode({ version: 'v1', hooks: [{ name: 'Harness session context', trigger: 'SessionStart', action: { type: 'agent', prompt:
+    'Read AGENTS.md and .harness/local.md. Read .harness/start.json and .harness/decisions.json if present. Inspect .harness/knowledge.json if present and check declared-source freshness using the installed Harness CLI (aih seed --check), or compare its hashes with available host tools. Reuse applicable confirmed decisions; superseded/proposed choices are not current approvals. Load other instructions only when applicable. If setup is missing/stale, mention /harness-start. Do not start an interview, rewrite configuration or execute a saved task solely because this hook ran.' } }] });
+  return result;
+}

package/cli/knowledge.js

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, digest, encode, isObject, HarnessError } from './files.js';
+import { readConfig } from './project-config.js';
+import { frontmatter } from './structured.js';
+import { check, loadLock, guard, transaction } from './harness.js';
+
+export const KNOWLEDGE = '.harness/knowledge.json';
+const CONTEXT = ['.harness/local.md', '.harness/environment.json', '.harness/agents.json', '.harness/artifacts.json', '.harness/integrations.json', '.harness/decisions.json'];
+const EXCLUDE = new Set(['.git', '.harness', '.agents', '.kiro', '.claude', 'node_modules', 'target', 'build', 'dist', '.next', '.venv', 'vendor']);
+const RELEVANT = /^(?:AGENTS\.md|README\.md|OVERVIEW\.md|pom\.xml|package\.json|build\.gradle(?:\.kts)?|pyproject\.toml|[^/]*(?:conventions|workflow|testing)[^/]*\.md)$/i;
+function assert(ok, message) { if (!ok) throw new HarnessError(message); }
+function bytes(root, name) {
+  const p = safe(root, name), info = stat(p);
+  assert(!info || info.size <= 1024 * 1024, 'Knowledge source exceeds 1 MiB: ' + name);
+  return info ? fs.readFileSync(p) : null;
+}
+export function localContext(root) {
+  const body = bytes(root, '.harness/local.md')?.toString('utf8') ?? '';
+  const parsed = frontmatter(body, '.harness/local.md');
+  if (!parsed) return { structured: false, value: null };
+  const value = parsed.value;
+  assert(value.schema_version === 1 && Object.keys(value).every(k => ['schema_version', 'stack', 'build', 'approved_deviations', 'sources'].includes(k)), 'Invalid local.md schema');
+  for (const key of ['stack', 'build']) if (value[key] !== undefined) {
+    assert(isObject(value[key]) && Object.values(value[key]).every(v => typeof v === 'string' && v.length <= 512), 'Invalid local.md ' + key);
+  }
+  const deviations = value.approved_deviations ?? [];
+  assert(Array.isArray(deviations) && deviations.length <= 128 && deviations.every(v => isObject(v)
+    && ['id', 'rule', 'reason'].every(k => typeof v[k] === 'string' && v[k].trim())
+    && Object.keys(v).every(k => ['id', 'rule', 'reason', 'source'].includes(k)))
+    && new Set(deviations.map(v => v.id)).size === deviations.length, 'Invalid approved_deviations');
+  const sources = value.sources ?? [];
+  assert(Array.isArray(sources) && sources.length <= 128 && new Set(sources).size === sources.length, 'Invalid local.md sources');
+  for (const name of sources) {
+    safe(root, name);
+    assert(!name.startsWith('.harness/') && !name.startsWith('.agents/') && !name.startsWith('.kiro/') && !name.startsWith('.claude/') && !/(?:^|\/)(?:\.git|node_modules|machine\.json|\.env(?:\..*)?)(?:\/|$)/.test(name), 'Private or unsupported knowledge source');
+  }
+  return { structured: true, value };
+}
+function discover(root) {
+  const files = []; let visited = 0;
+  function walk(folder, depth) {
+    for (const entry of fs.readdirSync(path.join(root, folder), { withFileTypes: true }).sort((a,b) => a.name.localeCompare(b.name))) {
+      assert(++visited <= 10000, 'Knowledge discovery exceeds 10000 entries; narrow the workspace');
+      const name = folder ? folder + '/' + entry.name : entry.name;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory() && depth < 4 && !EXCLUDE.has(entry.name)) walk(name, depth + 1);
+      else if (entry.isFile() && RELEVANT.test(entry.name)) { safe(root, name); files.push(name); }
+    }
+  }
+  walk('', 0);
+  assert(files.length <= 256, 'Knowledge discovery exceeds 256 sources');
+  return files.sort();
+}
+function hashes(root, names) { return Object.fromEntries(names.map(name => [name, bytes(root, name)]).map(([name,data]) => [name, data === null ? null : digest(data)])); }
+function state(root) {
+  const local = localContext(root), discovered = discover(root);
+  return { local, discovered, source_hashes: hashes(root, [...new Set([...discovered, ...(local.value?.sources ?? [])])].sort()), context_hashes: hashes(root, CONTEXT), bundle_sha256: loadLock(root).bundle_sha256 };
+}
+function savedKnowledge(root) {
+  const saved = readConfig(root, KNOWLEDGE);
+  if (!saved) { assert(!stat(safe(root, KNOWLEDGE)), 'Invalid knowledge schema'); return null; }
+  assert(isObject(saved) && saved.schema_version === 1 && Object.keys(saved).sort().join(',') === 'bundle_sha256,context_hashes,knowledge_hash,schema_version,source_hashes', 'Invalid knowledge schema');
+  for (const group of ['source_hashes', 'context_hashes']) {
+    assert(isObject(saved[group]) && Object.keys(saved[group]).length <= 384, 'Invalid knowledge hashes');
+    for (const [name, hash] of Object.entries(saved[group])) { safe(root, name); assert(hash === null || /^[a-f0-9]{64}$/.test(hash), 'Invalid knowledge digest'); }
+  }
+  const { knowledge_hash, ...content } = saved;
+  assert(knowledge_hash === digest(encode(content)), 'Knowledge digest mismatch');
+  return saved;
+}
+export function knowledgeReport(root) {
+  const current = state(root), saved = savedKnowledge(root);
+  const changed = [];
+  for (const group of ['source_hashes', 'context_hashes']) for (const name of new Set([...Object.keys(current[group]), ...Object.keys(saved?.[group] ?? {})])) {
+    if (current[group][name] !== saved?.[group]?.[name]) changed.push(name);
+  }
+  if (saved && current.bundle_sha256 !== saved.bundle_sha256) changed.push('.harness/lock.json');
+  return { status: !saved ? 'missing' : changed.length ? 'stale' : 'current', structured: current.local.structured,
+    changed_sources: [...new Set(changed)].sort(), sources: Object.keys(current.source_hashes),
+    knowledge_hash: saved?.knowledge_hash ?? null,
+    note: 'Local declared-source freshness only; remote revisions and facts remain host-verified. Summaries do not override scoped instructions.' };
+}
+export function seed(root, { record = false, checkOnly = false } = {}) {
+  assert(check(root).status === 'ok', 'Fix installation drift before seed');
+  if (!record) {
+    const report = knowledgeReport(root);
+    return { ...report, status: checkOnly ? report.status === 'current' ? 'ok' : 'blocked' : 'planned', freshness: report.status,
+      next_steps: ['Use /harness-start in your AI session; inspect changed/new sources, populate structured local.md and shared environment.json.',
+        'Keep personal paths in ignored machine.json. Record only evidence-backed facts and already approved deviations.',
+        'After reconciliation run aih seed --record; --check detects changes without updating the cache.'] };
+  }
+  return guard(root, () => {
+    const current = state(root);
+    assert(current.local.structured && current.local.value.sources?.length > 0, 'Populate structured local.md with inspected sources before recording knowledge');
+    assert(Object.values(current.source_hashes).every(v => v !== null), 'Resolve missing knowledge sources before recording');
+    const previous = savedKnowledge(root);
+    const value = { schema_version: 1, source_hashes: current.source_hashes, context_hashes: current.context_hashes, bundle_sha256: current.bundle_sha256 };
+    value.knowledge_hash = digest(encode(value));
+    if (previous?.knowledge_hash !== value.knowledge_hash) transaction(root, { [KNOWLEDGE]: encode(value) });
+    return { status: 'ok', path: KNOWLEDGE, knowledge_hash: value.knowledge_hash, changed: previous?.knowledge_hash !== value.knowledge_hash,
+      note: 'Recorded host-reconciled source hashes; this does not certify summary correctness.' };
+  });
+}

package/cli/main.js

@@ -1,15 +1,21 @@
+import { seed } from './knowledge.js';
+import { syncIntegrations } from './sync-integrations.js';
+import { startPlan, saveStart, guidedStart, compactStart } from './start.js';
+import { setupProject } from './setup.js';
+import { projectDecisionReport } from './project-decisions.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 { workflowReport } from './workflow.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, saveCheckpoint } from './harness.js';
+import { SOURCE, readJson, targetRoot, install, check, doctor, newChange, changeSidecars, newDoc, loadLock, saveCheckpoint } from './harness.js';
 import path from 'node:path';
 
 const HELP = `aih — install reusable AI development rules into a project
@@ -29,21 +35,43 @@ 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
-  setup                Suggest first-run questions for the AI host (read-only)
+  seed                 Plan context loading; --record reconciled hashes or --check freshness
+  sync-integrations    Import Kiro MCP aliases only; verify tools in the active host
+  change-sidecars <id>  Add missing OpenSpec sidecars without overwriting existing files
+  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 questions; --apply scaffolds missing user config only
+  decisions            Read shared decisions; --scope module:<name> narrows context
   artifacts            Show input/output/storage and connection declarations (read-only)
+  workflow validate    Validate installed workflow contracts (read-only)
   ready <id>           Check structural change readiness, not approval
   new-change <id>      Create an OpenSpec draft using installed templates
   new-doc <type>       Scaffold a locked capability template (default: product)
 
 Options:
+  --apply             setup: create missing user configs from the installed snapshot
+  --greenfield        setup: select new-project guidance, not an adapter or architecture
+  --compact           start: short read-only orientation; skips terminal intake/source scan
+  --record            seed: record hashes after host context reconciliation
+  --check             seed: read-only freshness check
+  --skill <name>      doctor: check one canonical/project skill prerequisite contract
+  --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
+  --stage <type>      ready: workflow stage ID; legacy implement/review stay compatible
+  --workflow <id>     ready: opt into full workflow gates and approval records
   --capability <id>   new-doc only: installed template owner (default: product)
   --agent-preset <id> init only: recommended (default), economy, custom; no overwrite
   --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
+  --host <id>         init/update/setup/agents/start: kiro,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
   --expected <sha>    checkpoint: observed prior checkpoint digest for replacement
@@ -51,12 +79,15 @@ Options:
   --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
-  --dry-run           init/update: preview without persistent changes
+  --dry-run           init/update/setup --apply: 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.
+All hosts: init --host <host> → first AI chat: invoke/read harness-start.
+Kiro exposes /harness-start; other clients can read .agents/skills/harness-start/SKILL.md.
+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.
@@ -95,8 +126,8 @@ 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' }, expected: { type: 'string' },
+      apply: { type: 'boolean' }, greenfield: { type: 'boolean' }, compact: { type: 'boolean' }, record: { type: 'boolean' }, check: { type: 'boolean' }, skill: { 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' },
+      workflow: { 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' },
@@ -109,26 +140,56 @@ 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', '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');
+    if (!['workflow', 'decisions', 'seed', 'sync-integrations', 'change-sidecars', '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 || (!['workflow', 'change-sidecars', 'new-change', 'new-doc', 'skill', 'ready', 'checkpoint', 'resume'].includes(command) && name !== undefined) || (['workflow', 'change-sidecars', '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 === 'workflow' && name !== 'validate') throw new Error('Usage: aih workflow validate');
+    if (command === 'ready') allowed.add('workflow');
+    if (command === 'seed') { allowed.add('record'); allowed.add('check'); if (args.values.record && args.values.check) throw new Error('Choose --record or --check'); }
+    if (command === 'doctor') allowed.add('skill');
+    if (command === 'sync-integrations') { for (const key of ['host','from','dry-run']) allowed.add(key); }
+    if (command === 'start') {
+      for (const key of ['goal','task','change','input','output','host','compact']) allowed.add(key);
+      if (args.values.compact && ['goal','task','change','input','output'].some(k => args.values[k] !== undefined)) throw new Error('--compact cannot save intake answers');
+    }
+    if (command === 'decisions') allowed.add('scope');
+    if (command === 'setup') {
+      for (const key of ['apply','greenfield','dry-run']) allowed.add(key);
+      if (args.values['dry-run'] && !args.values.apply) throw new Error('setup --dry-run requires --apply');
+    }
+    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 (['setup','agents','init'].includes(command)) allowed.add('host');
+    if (['setup','agents','init','update'].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 === 'workflow') {
+      if (check(root).status !== 'ok') throw new Error('Fix installation drift before reading workflows');
+      result = workflowReport(path.join(root, '.harness'), loadLock(root).capabilities ?? []);
+    } else if (command === 'start') {
+      if (!values.compact && !values.goal && values.host !== 'kiro' && 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.compact ? compactStart(root, values.host) : 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 === 'setup') result = setupProject(root, { apply: values.apply, dryRun: values['dry-run'], greenfield: values.greenfield, host: values.host });
+    else if (command === 'decisions') { if (check(root).status !== 'ok') throw new Error('Fix installation drift before reading decisions'); result = projectDecisionReport(root, values.scope); }
+    else if (command === 'seed') result = seed(root, { record: values.record, checkOnly: values.check });
+    else if (command === 'sync-integrations') result = syncIntegrations(root, { host: values.host, from: values.from, dryRun: values['dry-run'] });
+    else if (command === 'change-sidecars') result = changeSidecars(root, name);
+    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');
@@ -162,19 +223,19 @@ export function main(argv = process.argv.slice(2)) {
       if (check(root).status !== 'ok') throw new Error('Fix installation drift before reading artifact declarations');
       result = artifactReport(root);
     }
-    else if (command === 'setup' || command === 'ready') {
+    else if (command === 'ready') {
       const state = check(root);
       if (state.status !== 'ok') throw new Error('Fix installation drift before setup/readiness checks');
-      result = command === 'setup' ? setupPlan(root, loadLock(root).adapters, process.env, values.host) : ready(root, name, values.stage ?? 'implement');
+      result = ready(root, name, values.stage ?? 'implement', values.workflow);
     }
     else if (command === 'new-change') result = newChange(root, name);
     else if (command === 'new-doc') result = newDoc(root, name, values.capability ?? 'product', { report: values.report });
-    else result = command === 'doctor' ? doctor(root) : check(root);
+    else result = command === 'doctor' ? doctor(root, values.skill) : 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.',
+      : [values.host === 'kiro' || Object.keys(loadLock(root).files).some(p => p.startsWith('.kiro/skills/harness-')) ? 'Open this project in Kiro. In your first chat select /harness-start; the agent asks only missing questions and saves context.' : '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/portable-config.js

@@ -0,0 +1,124 @@
+import { localContext } from './knowledge.js';
+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';
+import { PROJECT_DECISIONS, loadProjectDecisions } from './project-decisions.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', PROJECT_DECISIONS, '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); localContext(temp); loadProjectDecisions(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 decisions never move to a different project.
+      for (const agent of Object.values(config.agents)) delete agent.extensions;
+      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/project-decisions.js

@@ -0,0 +1,47 @@
+import { readConfig } from './project-config.js';
+import { safe, stat, isObject, HarnessError } from './files.js';
+
+export const PROJECT_DECISIONS = '.harness/decisions.json';
+export const emptyProjectDecisions = () => ({ schema_version: 1, decisions: [] });
+const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value);
+const id = value => typeof value === 'string' && /^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(value);
+const scope = value => value === 'project' || typeof value === 'string' && /^module:[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)*$/.test(value);
+const fail = (ok, label) => { if (!ok) throw new HarnessError('Invalid project decisions: ' + label); };
+
+export function loadProjectDecisions(root) {
+  const value = readConfig(root, PROJECT_DECISIONS);
+  if (value === null && !stat(safe(root, PROJECT_DECISIONS))) return null;
+  fail(isObject(value) && value.schema_version === 1 && Object.keys(value).sort().join(',') === 'decisions,schema_version'
+    && Array.isArray(value.decisions) && value.decisions.length <= 256, 'schema');
+  const rows = new Map();
+  for (const row of value.decisions) {
+    fail(isObject(row) && Object.keys(row).every(k => ['id', 'scope', 'status', 'question', 'answer', 'reason', 'source', 'superseded_by', 'do_not_ask_again'].includes(k))
+      && id(row.id) && scope(row.scope) && ['proposed', 'confirmed', 'superseded'].includes(row.status)
+      && text(row.question) && !rows.has(row.id), 'entry fields or duplicate ID');
+    for (const key of ['answer', 'reason', 'source']) fail(row[key] === undefined || text(row[key]), key);
+    if (row.status !== 'proposed') fail(['answer', 'reason', 'source'].every(k => text(row[k])), 'confirmed/superseded decision needs answer, reason and source');
+    fail(row.do_not_ask_again === undefined || typeof row.do_not_ask_again === 'boolean', 'do_not_ask_again');
+    fail(row.status === 'superseded' ? id(row.superseded_by) && row.superseded_by !== row.id : row.superseded_by === undefined, 'superseded_by');
+    rows.set(row.id, row);
+  }
+  for (const row of rows.values()) {
+    const seen = new Set(); let current = row;
+    while (current.status === 'superseded') {
+      fail(!seen.has(current.id), 'supersession cycle'); seen.add(current.id);
+      const next = rows.get(current.superseded_by);
+      fail(next && next.scope === current.scope && next.status !== 'proposed', 'replacement must exist in the same scope and be confirmed/superseded');
+      current = next;
+    }
+  }
+  return value;
+}
+
+export function projectDecisionReport(root, requestedScope) {
+  fail(requestedScope === undefined || scope(requestedScope), 'requested scope');
+  const value = loadProjectDecisions(root);
+  const decisions = (value?.decisions ?? []).filter(row => requestedScope === undefined || row.scope === 'project' || row.scope === requestedScope);
+  return { status: 'ok', configured: value !== null, path: PROJECT_DECISIONS,
+    confirmed: decisions.filter(row => row.status === 'confirmed'),
+    proposed: decisions.filter(row => row.status === 'proposed'), superseded: decisions.filter(row => row.status === 'superseded'),
+    note: 'Recorded decisions are project context, not permissions. Reuse only while scope and sources remain applicable; changed evidence can require reconsideration, even with do_not_ask_again.' };
+}