@manhd_d/ai-harness 0.13.0 → 0.15.0

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

package/cli/setup.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { safe, stat, encode, HarnessError, CONFIG } from './files.js';
+import { loadLock, snapshotCheck, projectConfig, guard, transaction, userIgnoreChanges } from './harness.js';
+import { validateAgentConfig, loadAgentConfig, AGENT_CONFIG } from './agents.js';
+import { loadEnvironment, setupPlan } from './environment.js';
+import { loadArtifactContract, ARTIFACTS, INTEGRATIONS } from './artifacts.js';
+import { localContext } from './knowledge.js';
+import { loadStartConfig } from './start-config.js';
+import { PROJECT_DECISIONS, emptyProjectDecisions, loadProjectDecisions } from './project-decisions.js';
+
+function validateCandidate(root, changes) {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'aih-setup-validate-'));
+  try {
+    for (const name of [CONFIG, AGENT_CONFIG, ARTIFACTS, INTEGRATIONS, '.harness/environment.json',
+      '.harness/machine.json', '.harness/local.md', '.harness/start.json', PROJECT_DECISIONS]) {
+      const p = safe(root, name), data = changes[name] ?? (stat(p) ? fs.readFileSync(p) : null);
+      if (data !== null) { const dest = safe(temp, name); fs.mkdirSync(path.dirname(dest), { recursive: true }); fs.writeFileSync(dest, data, { mode: 0o600 }); }
+    }
+    projectConfig(temp, undefined, undefined, true); loadAgentConfig(temp); loadEnvironment(temp);
+    loadArtifactContract(temp); loadStartConfig(temp); localContext(temp); loadProjectDecisions(temp);
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+
+// A cloned snapshot supplies templates; this operation never reinstalls or changes its payload/lock.
+export function setupProject(root, { apply = false, dryRun = false, greenfield = false, host, writer } = {}) {
+  if (dryRun && !apply) throw new HarnessError('setup --dry-run requires --apply');
+  const operation = () => {
+    if (snapshotCheck(root).status !== 'ok') throw new HarnessError('Fix installation drift before setup');
+    const lock = loadLock(root), hasProject = Boolean(stat(safe(root, CONFIG)));
+    const config = hasProject ? projectConfig(root, undefined, undefined, true)
+      : { schema_version: 1, adapters: lock.adapters, capabilities: lock.capabilities ?? [] };
+    if (JSON.stringify([...config.adapters].sort()) !== JSON.stringify([...lock.adapters].sort())
+      || JSON.stringify([...(config.capabilities ?? [])].sort()) !== JSON.stringify([...(lock.capabilities ?? [])].sort())) {
+      throw new HarnessError('Project selection changed; run update before setup');
+    }
+    loadAgentConfig(root); loadEnvironment(root); loadArtifactContract(root); loadStartConfig(root); localContext(root); loadProjectDecisions(root);
+    if (!hasProject && !apply) throw new HarnessError('Missing project.json; use setup --apply to scaffold from the installed snapshot');
+    const changes = {};
+    if (apply) {
+      const template = name => {
+        const p = '.harness/templates/' + name;
+        if (!Object.hasOwn(lock.files, p)) throw new HarnessError('Setup requires installed template ' + name + '; use a reviewed update');
+        return fs.readFileSync(safe(root, p));
+      };
+      const missingTemplate = (dest, name) => { if (!stat(safe(root, dest))) changes[dest] = template(name); };
+      if (!hasProject) changes[CONFIG] = encode(config);
+      if (!stat(safe(root, AGENT_CONFIG))) {
+        const data = template('agents.default.json'); validateAgentConfig(JSON.parse(data)); changes[AGENT_CONFIG] = data;
+      }
+      missingTemplate(ARTIFACTS, 'artifacts.json'); missingTemplate(INTEGRATIONS, 'integrations.json');
+      missingTemplate('.harness/environment.json', 'environment.json'); missingTemplate('.harness/local.md', 'local.md');
+      missingTemplate('openspec/config.yaml', 'openspec/config.yaml');
+      if (!stat(safe(root, PROJECT_DECISIONS))) changes[PROJECT_DECISIONS] = encode(emptyProjectDecisions());
+      Object.assign(changes, userIgnoreChanges(root));
+      validateCandidate(root, changes);
+      if (!dryRun) transaction(root, changes, writer);
+    }
+    return { ...(dryRun ? { status: 'planned' } : setupPlan(root, lock.adapters, process.env, host)),
+      changes: Object.keys(changes), applied: apply && !dryRun,
+      workflow: '.harness/core/workflows/' + (greenfield ? 'greenfield-setup.md' : 'seed.md'),
+      note: 'Missing-only configuration scaffolding from the installed snapshot. Existing answers, machine paths, managed files and lock are preserved; host inspection/interview establishes facts.' };
+  };
+  return apply ? guard(root, operation) : operation();
+}

package/cli/skill-requirements.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import { safe, stat, isObject, HarnessError } from './files.js';
+import { parseStructured } from './structured.js';
+import { loadEnvironment, environmentReport } from './environment.js';
+import { loadArtifactContract } from './artifacts.js';
+
+export function skillRequirements(body) {
+  const front = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(body)?.[1];
+  if (front === undefined) throw new HarnessError('Skill frontmatter is required');
+  const lines = front.split(/\r?\n/), starts = lines.map((l,i) => /^requires:/.test(l) ? i : -1).filter(i => i >= 0);
+  if (!starts.length) return { machine: [], environment: [], mcp: [] };
+  if (starts.length !== 1) throw new HarnessError('Duplicate skill requires');
+  let end = starts[0] + 1;
+  while (end < lines.length && (!lines[end].trim() || /^\s/.test(lines[end]))) end++;
+  const requires = parseStructured(lines.slice(starts[0], end).join('\n'), 'skill requires').requires;
+  if (!isObject(requires) || Object.keys(requires).some(k => !['machine','environment','mcp'].includes(k))) throw new HarnessError('Invalid skill requires');
+  const result = { machine: [], environment: [], mcp: [], ...requires };
+  for (const [group, entries] of Object.entries(result)) {
+    const pattern = group === 'mcp' ? /^[A-Za-z0-9_.-]+$/ : /^(?:tools|files|commands)\.[a-z][a-z0-9-]*(?:\.(?:executable|path|tool|args))?$/;
+    if (!Array.isArray(entries) || entries.length > 64 || new Set(entries).size !== entries.length || entries.some(v => typeof v !== 'string' || !pattern.test(v))) throw new HarnessError('Invalid skill requires.' + group);
+  }
+  return result;
+}
+export function requirementReport(root, name) {
+  if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(name)) throw new HarnessError('Invalid skill name');
+  // Project native/custom skills are explicit inputs too; do not scan all their bodies.
+  const candidates = ['.agents/skills/', '.kiro/skills/', 'plugins/'];
+  const relative = candidates.map(p => p + name + '/SKILL.md').find(p => stat(safe(root,p)));
+  if (!relative) throw new HarnessError('Skill not found: ' + name);
+  if (stat(safe(root,relative)).size > 65536) throw new HarnessError('Skill exceeds 64 KiB');
+  const requirements = skillRequirements(fs.readFileSync(safe(root,relative),'utf8'));
+  const env = loadEnvironment(root), presence = environmentReport(root), contract = loadArtifactContract(root);
+  const get = (value, reference) => reference.split('.').reduce((o,k) => o && Object.hasOwn(o,k) ? o[k] : undefined, value);
+  const missing = [], hostChecks = [];
+  for (const group of ['machine','environment']) for (const reference of requirements[group]) {
+    const value = get(group === 'machine' ? env.machine : env.shared, reference);
+    const [kind,id] = reference.split('.');
+    const entry = presence.entries.find(e => e.group === kind && e.id === id);
+    if (value === undefined || !entry || !['present','declared'].includes(entry.status)) missing.push(group + ':' + reference);
+  }
+  for (const binding of requirements.mcp) {
+    if (!Object.values(contract.integrations.connections).some(c => c.via === 'mcp' && c.binding === binding)) missing.push('mcp:' + binding);
+    else hostChecks.push({ binding, status: 'unverified' });
+  }
+  return { status: missing.length ? 'blocked' : 'ok', skill: name, path: relative, requirements, missing, host_checks: hostChecks,
+    note: 'Local prerequisites only. MCP access/tools still require verification in the active host; values are omitted.' };
+}

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

package/cli/start.js

@@ -0,0 +1,151 @@
+import { knowledgeReport, localContext } from './knowledge.js';
+import { projectDecisionReport } from './project-decisions.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { safe, stat, encode, SLUG, HarnessError } from './files.js';
+import { check, loadLock, guard, transaction, atomicWrite } from './harness.js';
+import { setupPlan } from './environment.js';
+import { loadArtifactContract, emptyArtifacts } from './artifacts.js';
+import { START_CONFIG, GOALS, loadStartConfig } from './start-config.js';
+import { configArchive, backupName } from './portable-config.js';
+import { resumePlan } from './checkpoint.js';
+
+function assert(ok, message) { if (!ok) throw new HarnessError(message); }
+export function compactStart(root, host) {
+  assert(check(root).status === 'ok', 'Fix installation drift before start');
+  const lock = loadLock(root), saved = loadStartConfig(root), local = localContext(root);
+  return { status: 'planned', version: lock.version, adapters: lock.adapters,
+    task: saved?.task ?? null, change: saved?.change_id ?? null, stack: local.value?.stack ?? null,
+    context: { structured: local.structured, freshness: 'unchecked' },
+    next_action: host === 'kiro' ? '/harness-start' : 'Read .agents/skills/harness-start/SKILL.md',
+    note: 'Orientation only; no source scan, MCP probe, interview or task execution. Check freshness with seed --check.' };
+}
+export function startPlan(root, host) {
+  assert(check(root).status === 'ok', 'Fix installation drift before start');
+  const lock = loadLock(root), saved = loadStartConfig(root), contract = loadArtifactContract(root);
+  const evidence = ['README.md', 'docs', 'requirements', 'pom.xml', 'package.json', 'build.gradle', 'pyproject.toml']
+    .filter(name => { const p = path.join(root, name), info = stat(p); if (info?.isDirectory()) safe(root, name + '/.start-probe'); else safe(root, name); return Boolean(info); });
+  const base = path.join(root, 'openspec/changes'), checkpoints = [];
+  if (stat(base)) {
+    safe(root, 'openspec/changes/.start-probe');
+    for (const id of fs.readdirSync(base).sort().slice(0, 100)) {
+      if (id !== 'archive' && SLUG.test(id) && stat(safe(root, 'openspec/changes/' + id + '/checkpoint.json'))) checkpoints.push(id);
+    }
+  }
+  const recommendation = saved?.goal ?? (checkpoints.length ? 'resume' : contract.artifacts.mode === 'document-driven' ? 'docs'
+    : evidence.some(p => ['pom.xml', 'package.json', 'build.gradle', 'pyproject.toml'].includes(p)) ? 'change' : 'idea');
+  const goal = saved?.goal;
+  const workflow = goal === 'idea' ? 'solution-framing.md' : 'continuous-development.md';
+  const setup = setupPlan(root, lock.adapters, process.env, host);
+  let resume = null;
+  if (goal === 'resume') {
+    try { resume = resumePlan(root, saved.change_id); }
+    catch (error) { if (!(error instanceof HarnessError)) throw error; resume = { status: 'blocked', executed: false, message: error.message, next_action: 'Restore/reconcile checkpoints and evidence before continuation, or choose a new task.' }; }
+  }
+  return { status: resume?.status === 'blocked' ? 'blocked' : 'planned', saved, discovery: { evidence, checkpoints, inputs: Object.keys(contract.artifacts.inputs), outputs: Object.keys(contract.artifacts.outputs) },
+    knowledge: knowledgeReport(root),
+    project_decisions: projectDecisionReport(root),
+    recommendation, reason: saved ? 'Reuse the saved task; choose a new goal explicitly to start another task.'
+      : checkpoints.length ? 'Checkpoint candidates exist; inspect freshness before continuing.'
+      : 'Based on declared sources and root build-file presence; the host must inspect their contents.',
+    questions: [ ...(!saved ? [{ id: 'goal', question: 'Start from an idea, existing docs, change existing code, or resume?', options: GOALS, recommendation }] : []),
+      ...(!Object.keys(contract.artifacts.inputs).length && goal !== 'resume' ? [{ id: 'input', question: 'Use which requirement path or credential-free HTTPS URL? Leave unknowns for the AI discussion.', options: ['repository', 'external', 'idea'], recommendation: evidence.includes('docs') ? 'repository' : 'idea' }] : []),
+      ...(!Object.keys(contract.artifacts.outputs).length && ['idea','docs'].includes(goal) ? [{ id: 'output', question: 'Where should draft docs be written?', options: ['docs/product', 'existing destination', 'discuss with AI'], recommendation: 'docs/product' }] : []) ],
+    suggested_roles: goal === 'idea' ? ['product:business-analyst', 'architecture:solution-architect']
+      : goal === 'docs' ? ['core:planner', 'core:implementer', 'core:reviewer'] : ['core:implementer', 'core:reviewer'],
+    agent_routes: setup.agent_configuration.roles.filter(role => (goal === 'idea' ? ['product:business-analyst', 'architecture:solution-architect'] : goal === 'docs' ? ['core:planner', 'core:implementer', 'core:reviewer'] : ['core:implementer', 'core:reviewer']).includes(role.canonical_id)),
+    installed_modules: { adapters: lock.adapters, capabilities: lock.capabilities ?? [] },
+    setup_questions: setup.questions, environment: setup.environment,
+    resume,
+    configuration: { directory: '.harness/', task: START_CONFIG, inputs_outputs: '.harness/artifacts.json', models_agents: '.harness/agents.json',
+      backup: 'aih backup', restore: 'aih restore --from <project-relative-backup.json>', transfer: 'aih restore --from <backup.json> --transfer' },
+    host_prompt: (Object.hasOwn(lock.files, '.agents/skills/harness-start/SKILL.md') ? 'Read .agents/skills/harness-start/SKILL.md and follow its session onboarding procedure. ' : '') + 'Read AGENTS.md, .harness/start.json if present, .harness/local.md, .harness/decisions.json if present and .harness/core/workflows/project-setup.md. '
+      + 'Inspect declared input/output locations and current code. Reuse saved answers; ask only missing consequential decisions with options and a grounded recommendation. '
+      + 'Use .harness/core/workflows/' + workflow + '. Discover only relevant installed agents/skills; suggest missing modules before editing project.json. '
+      + 'Keep model defaults unless requested; save accepted source/output/connection choices in their project-owned configs. '
+      + 'For resumed tasks inspect checkpoint freshness and side effects. Implement accepted scope with actual verification and maintain affected docs.',
+    next_steps: [host === 'kiro' ? 'In Kiro select /harness-start; complete the interview in the current AI session. This CLI plan never asks terminal questions for --host kiro.' : 'In a terminal start interviews and saves answers; without a TTY it prints this plan. Use --goal/--task to save non-interactively.',
+      'Open this project in your AI tool and send host_prompt; CLI does not launch a model or read remote document contents.',
+      'Use backup and copy its file outside the repository; see the configuration backup guide.'] };
+}
+export function saveStart(root, { goal, task, changeId, input, output, host } = {}) {
+  assert(GOALS.includes(goal), 'Choose --goal idea|docs|change|resume');
+  assert(typeof task === 'string' && task.trim().length > 0 && task.length <= 4096 && !/[\x00-\x1f\x7f]/.test(task), 'Supply a nonempty single-line --task (max 4096 characters)');
+  assert(goal === 'resume' ? SLUG.test(changeId ?? '') && changeId !== 'archive' : changeId === undefined, 'Use --change only with resume and an existing change ID');
+  return guard(root, () => {
+    const plan = startPlan(root, host), contract = loadArtifactContract(root);
+    if (goal === 'resume') {
+      assert(plan.discovery.checkpoints.includes(changeId), 'Resume requires an existing checkpoint; restore project changes/evidence first');
+      resumePlan(root, changeId); // Validate checkpoint/evidence before saving any configuration.
+    }
+    assert(goal !== 'resume' || (input === undefined && output === undefined), 'Resume reuses source/output contracts; do not combine with --input/--output');
+    const changes = {}, value = { schema_version: 1, goal, task: task.trim(), ...(changeId ? { change_id: changeId } : {}) };
+    changes[START_CONFIG] = encode(value);
+    if (input !== undefined || output !== undefined) {
+      const artifacts = structuredClone(contract.artifacts);
+      if (!contract.configured) Object.assign(artifacts, emptyArtifacts(), { mode: input ? 'document-driven' : goal === 'docs' ? 'document-driven' : 'idea-driven' });
+      if (input !== undefined) {
+        assert(!Object.keys(artifacts.inputs).length, 'Inputs already configured; review artifacts.json instead of replacing them through start');
+        assert(typeof input === 'string' && input.trim().length > 0, 'Input cannot be empty');
+        artifacts.inputs.requirements = { kind: 'requirements', location: input.startsWith('https://') ? { url: input } : { path: input }, write_policy: 'read-only' };
+      }
+      if (output !== undefined) {
+        assert(!Object.keys(artifacts.outputs).length, 'Outputs already configured; review artifacts.json instead of replacing them through start');
+        artifacts.outputs.documents = { kind: 'docs', location: { path: output }, capability: 'product', write_policy: 'propose', sources: Object.keys(artifacts.inputs) };
+      }
+      // Reuse the existing contract validator in a temporary workspace, before touching the target.
+      validateProposed(root, artifacts);
+      changes['.harness/artifacts.json'] = encode(artifacts);
+    }
+    for (const [name, bytes] of Object.entries(changes)) if (stat(safe(root, name)) && fs.readFileSync(safe(root, name)).equals(bytes)) delete changes[name];
+    const replacing = Object.keys(changes).some(name => stat(safe(root, name)));
+    let backup = null;
+    if (replacing) { backup = backupName(); assert(!stat(safe(root, backup)), 'Backup collision'); changes[backup] = encode(configArchive(root)); }
+    transaction(root, changes, (filename, data) => atomicWrite(filename, data, filename === (backup ? safe(root, backup) : null) ? 0o600 : 0o644));
+    const next = startPlan(root, host);
+    return { ...next, status: next.status === 'blocked' ? 'blocked' : 'ok', changes: Object.keys(changes), backup };
+  });
+}
+function validateProposed(root, artifacts) {
+  // Validate cross-file references with existing integrations and validate target paths through the canonical loader.
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'aih-start-'));
+  try {
+    fs.mkdirSync(path.join(temp, '.harness'));
+    fs.writeFileSync(path.join(temp, '.harness/artifacts.json'), encode(artifacts));
+    fs.writeFileSync(path.join(temp, '.harness/integrations.json'), encode(loadArtifactContract(root).integrations));
+    loadArtifactContract(temp);
+    for (const group of ['inputs', 'outputs']) for (const item of Object.values(artifacts[group])) {
+      const name = item.location.path;
+      if (name) safe(root, name + (group === 'outputs' || stat(path.join(root, name))?.isDirectory() ? '/.artifact-probe' : ''));
+    }
+  } finally { fs.rmSync(temp, { recursive: true, force: true }); }
+}
+
+export async function guidedStart(root, { host, ask } = {}) {
+  const plan = startPlan(root, host);
+  let rl;
+  if (!ask) { rl = createInterface({ input: process.stdin, output: process.stdout }); ask = q => rl.question(q); }
+  try {
+    let goal = plan.saved?.goal;
+    if (plan.saved) {
+      const answer = (await ask('Saved task: ' + plan.saved.task + '\n1. Continue (recommended)  2. New task\nChoice [1]: ')).trim();
+      assert(['', '1', '2'].includes(answer), 'Choose 1 or 2');
+      if (answer !== '2') return plan;
+      goal = undefined;
+    }
+    if (!goal) {
+      const choice = (await ask('Goal: 1. Idea  2. Existing docs  3. Change code  4. Resume\nSuggested: ' + plan.recommendation + '\nChoice [Enter uses suggestion]: ')).trim();
+      goal = choice ? GOALS[Number(choice) - 1] : plan.recommendation;
+      assert(GOALS.includes(goal), 'Choose 1, 2, 3 or 4');
+    }
+    const changeId = goal === 'resume' ? (await ask('Checkpoint ID (' + plan.discovery.checkpoints.join(', ') + '): ')).trim() : undefined;
+    const task = (await ask('What should the AI do? ')).trim();
+    let input, output;
+    if (!plan.discovery.inputs.length && goal !== 'resume') input = (await ask('Requirements: relative path or HTTPS URL (Enter: discuss idea/unknown sources with AI): ')).trim() || undefined;
+    if (!plan.discovery.outputs.length && ['idea', 'docs'].includes(goal)) output = (await ask('Draft docs folder [docs/product; type - to discuss with AI]: ')).trim() || 'docs/product';
+    if (output === '-') output = undefined;
+    return saveStart(root, { goal, task, changeId, input, output, host });
+  } finally { rl?.close(); }
+}

package/cli/structured.js

@@ -0,0 +1,65 @@
+import { HarnessError, isObject } from './files.js';
+
+// Deliberately bounded YAML subset: mappings, sequences, JSON inline values and scalars.
+// No tags, anchors, aliases, block scalars, implicit dates or object construction.
+export function parseStructured(text, label = 'structured data') {
+  const fail = () => { throw new HarnessError('Invalid or unsupported YAML: ' + label); };
+  if (text.length > 65536) fail();
+  const clean = text.trim();
+  if (clean.startsWith('{')) {
+    try { const value = JSON.parse(clean); if (!isObject(value)) fail(); return value; }
+    catch { fail(); }
+  }
+  const lines = text.split(/\r?\n/).filter(l => l.trim() && !l.trim().startsWith('#'));
+  if (lines.some(l => /\t/.test(l))) fail();
+  const indent = l => l.length - l.trimStart().length;
+  const scalar = s => {
+    if (!s || /^[!&*|>]/.test(s)) fail();
+    if (s.startsWith('"') || s.startsWith('[') || s.startsWith('{')) {
+      try { return JSON.parse(s); } catch { fail(); }
+    }
+    if (s.startsWith("'")) { if (!s.endsWith("'")) fail(); return s.slice(1, -1).replaceAll("''", "'"); }
+    if (s === 'true') return true;
+    if (s === 'false') return false;
+    if (s === 'null') return null;
+    if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(s)) return Number(s);
+    return s;
+  };
+  let index = 0;
+  function block(depth, level = 0) {
+    if (level > 12 || index >= lines.length || indent(lines[index]) !== depth) fail();
+    const array = lines[index].trimStart().startsWith('- '), result = array ? [] : {};
+    function pair(line, object, keyDepth) {
+      const match = /^([A-Za-z_][A-Za-z0-9_-]*):(?:\s+(.*))?$/.exec(line);
+      if (!match || ['__proto__', 'constructor', 'prototype'].includes(match[1]) || Object.hasOwn(object, match[1])) fail();
+      const value = match[2];
+      object[match[1]] = value !== undefined ? scalar(value.trim())
+        : index < lines.length && indent(lines[index]) > keyDepth ? block(indent(lines[index]), level + 1) : null;
+    }
+    while (index < lines.length && indent(lines[index]) >= depth) {
+      if (indent(lines[index]) !== depth) fail();
+      const line = lines[index++].trimStart();
+      if (array) {
+        if (!line.startsWith('- ')) fail();
+        const value = line.slice(2);
+        if (/^[A-Za-z_][A-Za-z0-9_-]*:(?:\s|$)/.test(value)) {
+          const item = {}; pair(value, item, depth + 2);
+          while (index < lines.length && indent(lines[index]) === depth + 2) pair(lines[index++].trimStart(), item, depth + 2);
+          result.push(item);
+        } else result.push(scalar(value));
+      } else pair(line, result, depth);
+    }
+    return result;
+  }
+  if (!lines.length) return {};
+  const value = block(0);
+  if (!isObject(value) || index !== lines.length) fail();
+  return value;
+}
+
+export function frontmatter(body, label) {
+  if (!body.startsWith('---\n') && !body.startsWith('---\r\n')) return null;
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(body);
+  if (!match) throw new HarnessError('Incomplete frontmatter: ' + label);
+  return { raw: match[1], value: parseStructured(match[1], label) };
+}

package/cli/sync-integrations.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { stat, isObject, SLUG, encode, safe, HarnessError } from './files.js';
+import { loadArtifactContract, INTEGRATIONS } from './artifacts.js';
+import { check, guard, transaction } from './harness.js';
+
+export function syncIntegrations(root, { host = 'kiro', from, dryRun = false } = {}) {
+  if (host !== 'kiro') throw new HarnessError('MCP config discovery currently supports --host kiro');
+  if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before syncing integrations');
+  // Explicit input overrides the standard project/user Kiro settings. Never copy values.
+  const names = from ? [path.resolve(from)] : [path.join(os.homedir(), '.kiro/settings/mcp.json'), path.join(root,'.kiro/settings/mcp.json')];
+  const servers = new Set(); let found = false;
+  for (const filename of names) {
+    for (let p = filename; ; p = path.dirname(p)) {
+      if (stat(p)?.isSymbolicLink()) throw new HarnessError('Symlinked MCP config is unsupported');
+      if (path.dirname(p) === p) break;
+    }
+    const info = stat(filename);
+    if (!info) { if (from) throw new HarnessError('MCP config not found'); continue; }
+    if (!info.isFile() || info.size > 1024 * 1024) throw new HarnessError('MCP config must be a file up to 1 MiB');
+    let config;
+    try { config = JSON.parse(fs.readFileSync(filename,'utf8')); } catch { throw new HarnessError('Invalid MCP config JSON (values omitted)'); }
+    if (!isObject(config) || !isObject(config.mcpServers)) throw new HarnessError('MCP config requires mcpServers');
+    found = true;
+    for (const [binding, server] of Object.entries(config.mcpServers)) {
+      if (!/^[A-Za-z0-9_.-]{1,128}$/.test(binding) || !isObject(server)) throw new HarnessError('Invalid MCP server declaration');
+      if (server.disabled === true) servers.delete(binding); else servers.add(binding);
+    }
+  }
+  if (!found) return { status: 'planned', discovered: [], added: [], note: 'No Kiro MCP config found. Verify active host connections directly.' };
+  if (servers.size > 128) throw new HarnessError('MCP inventory exceeds 128 servers');
+  return guard(root, () => {
+    const integrations = structuredClone(loadArtifactContract(root).integrations), added = [];
+    for (const binding of [...servers].sort()) {
+      if (Object.values(integrations.connections).some(c => c.via === 'mcp' && c.binding === binding)) continue;
+      const base = binding.toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^-|-$/g,'');
+      let id = /^[a-z]/.test(base) ? base : 'mcp-' + base;
+      if (!SLUG.test(id)) throw new HarnessError('Cannot create a safe MCP alias');
+      let suffix = 2; const initial = id;
+      while (Object.hasOwn(integrations.connections,id)) id = initial + '-' + suffix++;
+      integrations.connections[id] = { via: 'mcp', binding, purpose: 'Discovered Kiro server; verify purpose, scope and actual tools in the host.', access: 'read-only' };
+      added.push(id);
+    }
+    if (!dryRun && added.length) transaction(root, { [INTEGRATIONS]: encode(integrations) });
+    return { status: dryRun ? 'planned' : 'ok', discovered: [...servers].sort(), added, availability: 'unverified', tools: 'host-discovery-required',
+      note: 'Aliases only; no credentials, endpoints, commands, env or autoApprove lists copied. Existing declarations preserved; absent servers are not deleted. Declared read-only access does not constrain the server.' };
+  });
+}

package/cli/verification-report.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { reviewJourney } from './journey-evidence.js';
 import { isDeepStrictEqual } from 'node:util';
 import { safe, stat, digest, isObject, HarnessError } from './files.js';
 import { readConfig } from './project-config.js';
@@ -89,6 +90,8 @@ export function reviewVerification(root, reportPath) {
   const reqs = new Map();
   for (const req of report.requirements) {
     assert(isObject(req) && text(req.id) && !reqs.has(req.id) && text(req.description) && text(req.source), 'Invalid/duplicate requirement');
+    assert(req.verification_target === undefined || ['behavior', 'end-user'].includes(req.verification_target), 'Unknown requirement verification target');
+    assert(req.verification_target !== 'end-user' || ['web', 'mobile', 'cli', 'api'].includes(req.surface), 'End-user requirement needs an interface surface');
     reqs.set(req.id, req);
   }
   assert(Array.isArray(report.scenarios) && report.scenarios.length > 0, 'Declare scenarios, including NOT_RUN/BLOCKED gaps');
@@ -123,17 +126,18 @@ export function reviewVerification(root, reportPath) {
       assert(refs.length > 0, 'Executed scenarios need digest-checked evidence');
       if (ex.duration_ms !== undefined) assert(finite(ex.duration_ms), 'Invalid observed duration');
       const permittedError = !row.error || (row.expected_error === row.error.kind && ['http', 'application'].includes(row.error.kind));
-      const semantic = !['api', 'backend-e2e', 'business-workflow', 'authorization', 'security'].includes(row.method) || assertions.some(a => a.layer !== 'transport');
+      const semantic = !['api', 'backend-e2e', 'business-workflow', 'authorization', 'security', 'browser-e2e', 'mobile-e2e', 'cli-e2e', 'end-user'].includes(row.method) || assertions.some(a => a.layer !== 'transport');
       const pass = semantic && ex.exit_code === 0 && assertions.length > 0 && assertions.every(a => a.passed) && permittedError &&
         (!row.mutates || row.cleanup.status === 'PASSED');
       // Trust no typed PASS: recompute assertion/execution/cleanup consistency.
       assert(row.status === (pass ? 'PASSED' : 'FAILED'), 'Claimed status contradicts assertions, execution, error or cleanup');
     }
-    return { ...row, assertions, evidence: refs };
+    return { ...row, assertions, evidence: refs, ...reviewJourney(root, row) };
   });
   const requirements = [...reqs.values()].map(req => {
     const linked = scenarios.filter(s => s.references.includes(req.id));
-    return { ...req, verification: linked.length > 0 && linked.every(s => s.status === 'PASSED' && s.assertions.some(a => a.basis === req.id && a.passed)) ? 'VERIFIED' : 'UNVERIFIED',
+    return { ...req, verification: linked.length > 0 && linked.every(s => s.status === 'PASSED' && s.assertions.some(a => a.basis === req.id && a.passed))
+      && (req.verification_target !== 'end-user' || linked.some(s => s.status === 'PASSED' && s.acceptance_scope === 'end-user' && s.journey.surface === req.surface && s.assertions.some(a => a.basis === req.id && a.layer !== 'transport' && a.passed))) ? 'VERIFIED' : 'UNVERIFIED',
       scenarios: linked.map(s => s.id) };
   });
   const counts = Object.fromEntries(statuses.map(s => [s, scenarios.filter(row => row.status === s).length]));
@@ -164,9 +168,9 @@ export function techspecEvidence(summary) {
     ...summary.requirements.map(r => '| ' + cell(r.id) + ' — ' + cell(r.description) + ' | ' + cell(r.source) + ' | ' + r.verification + ' | ' + cell(r.scenarios.join(', ')) + ' |'),
     '',
     '## Scenario results',
-    '| Scenario | Method | Status | Expected | Observed | Evidence |',
+    '| Scenario | Method / acceptance scope | Status | Expected | Observed | Evidence |',
     '| --- | --- | --- | --- | --- | --- |',
-    ...summary.scenarios.map(s => '| ' + cell(s.id) + ' | ' + cell(s.method) + ' | ' + s.status + ' | ' + cell(s.expected) + ' | ' + cell(s.observed) + ' | ' + cell(s.evidence.map(e => e.path + ' sha256:' + e.sha256).join(', ')) + ' |'),
+    ...summary.scenarios.map(s => '| ' + cell(s.id) + ' | ' + cell(s.method + ' / ' + s.acceptance_scope) + ' | ' + s.status + ' | ' + cell(s.expected) + ' | ' + cell(s.observed) + ' | ' + cell(s.evidence.map(e => e.path + ' sha256:' + e.sha256).join(', ')) + ' |'),
     '',
     '## Limitations and change maintenance',
     'Report validation checks consistency, not independent execution authenticity or business approval.',