@manhd_d/ai-harness 0.14.0 → 0.15.0

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,17 +1,21 @@
-import { startPlan, saveStart, guidedStart } from './start.js';
+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
@@ -31,16 +35,27 @@ 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
+  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 first-run questions for the AI host (read-only)
+  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
@@ -50,12 +65,13 @@ Options:
   --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
@@ -63,12 +79,13 @@ 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 → start → open your AI host and send the returned host_prompt.
+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.
@@ -109,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: {
-      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' },
+      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' },
@@ -123,10 +140,23 @@ 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 (!['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');
+    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 === 'start') for (const key of ['goal','task','change','input','output','host']) allowed.add(key);
+    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');
@@ -136,7 +166,7 @@ export function main(argv = process.argv.slice(2)) {
     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');
@@ -146,10 +176,18 @@ export function main(argv = process.argv.slice(2)) {
     const { values, positionals: [command, name] } = args;
     const root = targetRoot(values.target ?? process.cwd());
     let result;
-    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);
+    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);
@@ -185,17 +223,17 @@ 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 start with the same CLI (aih start or npx --yes @manhd_d/ai-harness start); open your AI host and send host_prompt.',
+      : [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 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 = [

package/cli/portable-config.js

@@ -1,3 +1,4 @@
+import { localContext } from './knowledge.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -9,9 +10,10 @@ 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', 'openspec/config.yaml'];
+  '.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';
@@ -53,7 +55,7 @@ function validateFiles(files) {
     }
     const config = projectConfig(temp, undefined, undefined, true);
     resolveModules(SOURCE, config);
-    loadAgentConfig(temp); loadArtifactContract(temp); loadEnvironment(temp); loadStartConfig(temp);
+    loadAgentConfig(temp); loadArtifactContract(temp); loadEnvironment(temp); loadStartConfig(temp); localContext(temp); loadProjectDecisions(temp);
   } finally { fs.rmSync(temp, { recursive: true, force: true }); }
 }
 function outputPath(root, name) {
@@ -79,7 +81,8 @@ export function restoreConfig(root, from, { dryRun = false, transfer = false, re
     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.
+      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 = [];

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

package/cli/readiness.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { safe, stat, SLUG, isObject, HarnessError } from './files.js';
+import { safe, stat, SLUG, isObject, HarnessError, readJson } from './files.js';
 import { readConfig } from './project-config.js';
 import { artifactImpact } from './artifacts.js';
+import { loadWorkflow, readApprovals } from './workflow.js';
 
 const text = s => typeof s === 'string' && s.trim().length > 0;
 const draft = s => /\b(?:TODO|TBD|FIXME)\b|\{\{[^}]+\}\}/i.test(s);
@@ -20,9 +21,10 @@ function prose(body) {
     return fence ? '' : line;
   }).join('\n');
 }
-export function ready(root, id, stage = 'implement') {
+function structuralReady(root, id, stage = 'implement', checks) {
+  const has = name => !checks || checks.includes(name);
   if (!SLUG.test(id) || id === 'archive') throw new HarnessError('Invalid change ID');
-  if (!['implement', 'review'].includes(stage)) throw new HarnessError('Invalid readiness stage');
+
   const base = 'openspec/changes/' + id;
   const problems = [], documents = new Map();
   const read = relative => {
@@ -35,41 +37,45 @@ export function ready(root, id, stage = 'implement') {
     if (draft(content)) problems.push('Draft placeholders in ' + relative);
     documents.set(relative, content);
   };
-  for (const name of ['proposal.md', 'design.md', 'tasks.md']) read(name);
-  // safe() validates parent segments using a file leaf; do not traverse symlinked folders.
-  safe(root, base + '/specs/probe.md');
-  const specsRoot = path.join(root, base, 'specs');
-  let count = 0;
-  const visit = (folder, relative, depth = 0) => {
-    if (depth > 12) throw new HarnessError('Spec directory nesting exceeds limit');
-    for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
-      if (entry.isSymbolicLink()) throw new HarnessError('Symlink in change specs');
-      if (entry.isDirectory()) visit(path.join(folder, entry.name), relative + '/' + entry.name, depth + 1);
-      else if (entry.isFile() && entry.name.endsWith('.md')) {
-        if (++count > 100) throw new HarnessError('Too many spec documents');
-        const name = relative + '/' + entry.name;
-        read(name);
-        const body = documents.get(name) || '';
-        if (!/^### Requirement:/m.test(body) || !/^#### Scenario:/m.test(body) ||
-            !/\bWHEN\b/.test(body) || !/\bTHEN\b/.test(body)) problems.push('Missing requirement/scenario structure in ' + name);
+  if (has('spec-structure')) for (const name of ['proposal.md', 'design.md']) read(name);
+  if (has('spec-structure') || has('tasks-present') || has('tasks-complete')) read('tasks.md');
+  if (has('spec-structure')) {
+    // safe() validates parent segments using a file leaf; do not traverse symlinked folders.
+    safe(root, base + '/specs/probe.md');
+    const specsRoot = path.join(root, base, 'specs');
+    let count = 0;
+    const visit = (folder, relative, depth = 0) => {
+      if (depth > 12) throw new HarnessError('Spec directory nesting exceeds limit');
+      for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+        if (entry.isSymbolicLink()) throw new HarnessError('Symlink in change specs');
+        if (entry.isDirectory()) visit(path.join(folder, entry.name), relative + '/' + entry.name, depth + 1);
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+          if (++count > 100) throw new HarnessError('Too many spec documents');
+          const name = relative + '/' + entry.name;
+          read(name);
+          const body = documents.get(name) || '';
+          if (!/^### Requirement:/m.test(body) || !/^#### Scenario:/m.test(body) ||
+              !/\bWHEN\b/.test(body) || !/\bTHEN\b/.test(body)) problems.push('Missing requirement/scenario structure in ' + name);
+        }
+      }
+    };
+    if (fs.existsSync(specsRoot)) visit(specsRoot, 'specs');
+    if (!count) problems.push('Missing delta specs');
+  }
+  if (has('decisions-resolved')) {
+    const decisions = readConfig(root, base + '/decisions.json');
+    if (!isObject(decisions) || decisions.schema_version !== 1 || typeof decisions.reviewed !== 'boolean' ||
+        !Array.isArray(decisions.decisions)) problems.push('Missing/invalid decisions.json; copy the installed template for legacy changes');
+    else {
+      if (!decisions.reviewed) problems.push('Consequential ambiguity review is not recorded');
+      const ids = new Set();
+      for (const row of decisions.decisions) {
+        if (!isObject(row) || !text(row.id) || ids.has(row.id) || !text(row.question) ||
+            !['open', 'resolved'].includes(row.status)) { problems.push('Invalid/duplicate decision record'); continue; }
+        ids.add(row.id);
+        if (row.status === 'open') problems.push('Unresolved decision: ' + row.id);
+        else if (!evidenceText(row.answer) || !evidenceText(row.source)) problems.push('Decision needs answer and source: ' + row.id);
       }
-    }
-  };
-  if (fs.existsSync(specsRoot)) visit(specsRoot, 'specs');
-  if (!count) problems.push('Missing delta specs');
-
-  const decisions = readConfig(root, base + '/decisions.json');
-  if (!isObject(decisions) || decisions.schema_version !== 1 || typeof decisions.reviewed !== 'boolean' ||
-      !Array.isArray(decisions.decisions)) problems.push('Missing/invalid decisions.json; copy the installed template for legacy changes');
-  else {
-    if (!decisions.reviewed) problems.push('Consequential ambiguity review is not recorded');
-    const ids = new Set();
-    for (const row of decisions.decisions) {
-      if (!isObject(row) || !text(row.id) || ids.has(row.id) || !text(row.question) ||
-          !['open', 'resolved'].includes(row.status)) { problems.push('Invalid/duplicate decision record'); continue; }
-      ids.add(row.id);
-      if (row.status === 'open') problems.push('Unresolved decision: ' + row.id);
-      else if (!evidenceText(row.answer) || !evidenceText(row.source)) problems.push('Decision needs answer and source: ' + row.id);
     }
   }
   let postMergeLevel = null, taskCount = 0, pending = 0;
@@ -82,11 +88,11 @@ export function ready(root, id, stage = 'implement') {
     const task = line.match(/^\s*(?:[-*+]|\d+\.)\s+\[([ xX])\]/);
     if (task && postMergeLevel === null) { taskCount++; if (task[1] === ' ') pending++; }
   }
-  if (!taskCount) problems.push('Missing pre-merge task checklist');
-  if (stage === 'review' && pending) problems.push('Incomplete pre-merge tasks: ' + pending);
+  if ((has('tasks-present') || has('tasks-complete')) && !taskCount) problems.push('Missing pre-merge task checklist');
+  if ((checks ? has('tasks-complete') : stage === 'review') && pending) problems.push('Incomplete pre-merge tasks: ' + pending);
 
   const skipped = [];
-  if (stage === 'review') {
+  if (checks ? has('verification-evidence') : stage === 'review') {
     const verification = readConfig(root, base + '/verification.json');
     if (!isObject(verification) || verification.schema_version !== 1 || !Array.isArray(verification.checks) ||
         !verification.checks.length) problems.push('Missing verification evidence');
@@ -109,7 +115,7 @@ export function ready(root, id, stage = 'implement') {
       if (!passed) problems.push('No completed passing check or manual review recorded');
     }
   }
-  problems.push(...artifactImpact(root, base, stage));
+  if (has('artifact-impact')) problems.push(...artifactImpact(root, base, stage === 'implement' ? 'implement' : 'review'));
   return { status: problems.length ? 'blocked' : 'ready', change: id, stage, problems,
     tasks: { pre_merge: taskCount, pending }, skipped_checks: skipped, executed: false,
     next_steps: problems.length ? ['Resolve reported gaps; ask the user about unresolved consequential decisions.']
@@ -117,3 +123,38 @@ export function ready(root, id, stage = 'implement') {
         : 'Review actual evidence and the diff before creating a PR.'],
     note: 'Structural readiness only, not business approval, OpenSpec validation or proof of truthful test evidence.' };
 }
+
+export function ready(root, id, stage = 'implement', workflowId) {
+  if (!SLUG.test(id) || id === 'archive') throw new HarnessError('Invalid change ID');
+  // Snapshot-less legacy use keeps working. Installed legacy stages validate the new declaration,
+  // but do not retroactively add approvals to previously supported structural gates.
+  const legacy = workflowId === undefined && ['implement', 'review'].includes(stage);
+  const lockPath = safe(root, '.harness/lock.json'), lock = stat(lockPath) ? readJson(lockPath) : null;
+  const source = path.join(root, '.harness');
+  if (legacy) {
+    if (stat(safe(source, 'core/workflows/spec-to-code.workflow.json'))) loadWorkflow(source, 'spec-to-code', lock?.capabilities ?? []);
+    return structuralReady(root, id, stage);
+  }
+  const workflow = loadWorkflow(source, workflowId ?? 'spec-to-code', lock?.capabilities ?? []);
+  const selected = workflow.stages.find(s => s.id === stage);
+  if (!selected) throw new HarnessError('Invalid readiness stage: ' + stage);
+  const checks = selected.entry_gate?.deterministic ?? [];
+  const result = structuralReady(root, id, stage, checks);
+  const approvals = readApprovals(root, 'openspec/changes/' + id, workflow);
+  const from = selected.entry_gate?.approval_from;
+  if (from && !approvals.some(a => a.stage === from && a.role === workflow.stages.find(s => s.id === from).approval.role)) result.problems.push('Missing recorded approval from ' + from);
+  if (checks.includes('outputs-present')) {
+    for (const file of workflow.stages.flatMap(s => s.outputs ?? [])) {
+      const relative = workflow.id === 'spec-to-code' ? 'openspec/changes/' + id + '/' + file : file;
+      const info = stat(safe(root, relative));
+      if (!info || !info.size) result.problems.push('Missing/empty output: ' + relative);
+    }
+  }
+  result.status = result.problems.length ? 'blocked' : 'ready';
+  result.next_steps = result.problems.length ? ['Resolve reported entry-gate gaps before entering this stage.']
+    : ['Enter ' + selected.id + ' with owner ' + selected.owner + '; follow the matching Markdown procedure.',
+       ...(selected.approval ? ['Record actual external ' + selected.approval.role + ' review before completing this stage.'] : [])];
+  result.workflow = workflow.id; result.owner = selected.owner; result.approval_required = selected.approval ?? null;
+  result.note += ' Recorded approvals are declarations only: identity, authority, freshness and semantic truth are not authenticated. Entry readiness does not complete a stage or authorize its outputs.';
+  return result;
+}