@manhd_d/ai-harness 0.6.2 → 0.8.0

package/capabilities/product/skills/harness-product-use-case-generation/SKILL.md

@@ -24,3 +24,20 @@ description: Translate requirement and story IDs into consistent main, alternati
 - Never imply a draft flow is accepted without sign-off.
 - Avoid duplicating product scope in a competing document; reference established IDs.
 - No assumptions about system behavior presented as approved facts.
+
+## Template
+Read `.harness/capabilities/product/templates/use-cases.md`; `aih new-doc use-cases` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: UC-001 contains main lookup, no-result, permission denial and provider timeout paths linked to FR/AC.
+
+## Quality checklist
+- Actor, precondition, result and alternate/error flows are explicit.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/skills/harness-product-user-stories/SKILL.md

@@ -23,3 +23,20 @@ description: Turn approved requirements into atomic epics and user stories with
 ## Constraints
 - Do not fabricate persona needs or change scope via user-story rewriting.
 - A story marked Ready requires actual acceptance criteria and PO review.
+
+## Template
+Read `.harness/capabilities/product/templates/backlog.md`; `aih new-doc backlog` creates only a missing
+draft. Reuse canonical existing documents and source pointers; never regenerate approved content by default.
+
+## Example
+Synthetic illustration: US-001: authorized employee finds a customer; links FR-001 and AC-US-001-01, with access-denial criteria.
+
+## Quality checklist
+- Story has user value, dependency and observable acceptance.
+- Actual decisions/status and source revisions distinguish approved facts from proposals.
+- Scope, relevant IDs, unresolved questions and verification limits are recorded.
+
+## Handoff
+Use `.harness/capabilities/product/workflows/product-to-solution.md`; supply reviewed source/requirement
+IDs, output paths and actual owner decisions to the next BA/PO/SA/PM role as applicable. Return gaps
+to their owner; a single host may perform roles sequentially without claiming independent approval.

package/capabilities/product/templates/mvp.md

@@ -0,0 +1,25 @@
+# MVP scope
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## User and outcome
+Target actor, problem, value-bearing end-to-end journey and validation evidence.
+## Scope cuts
+| Capability | In / out | Value / dependency | Requirement / AC | Decision source |
+| --- | --- | --- | --- | --- |
+| TODO | TODO | TODO | TODO | TODO |
+## Minimum viable quality
+Authorization, data integrity, failure recovery and relevant NFRs that cannot be deferred.
+## Acceptance and learning
+Observable journey completion, success signals, measurement owner, known baseline/target or unknown.
+## Open decisions
+Options/trade-offs, recommended cut with evidence and actual owner answer; unanswered choices remain pending.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.

package/capabilities/product/templates/outcomes.md

@@ -0,0 +1,23 @@
+# Product outcomes
+
+Status: draft / pending review
+Owner: TODO
+Sources and revisions: TODO
+Scope / related requirement and decision IDs: TODO
+Last verified against code: TODO (or not applicable with reason)
+
+## Value hypothesis
+User problem and expected benefit; link MVP/PRD instead of duplicating scope.
+## Measurement plan
+| Outcome / metric | Definition / source | Baseline | Proposed target / authority | Owner / period |
+| --- | --- | --- | --- | --- |
+| TODO | TODO | unknown | pending | TODO |
+## Experiment and guardrails
+Hypothesis, smallest experiment, cost/privacy limits, negative effects and decision checkpoint.
+## Evidence and next action
+Separate observed results from forecasts; propose continue/pivot/stop without self-approving scope changes.
+
+
+## Review and handoff
+Record actual owner decisions, unresolved consequential questions, verification performed/skipped,
+next role, source/output paths and affected OpenSpec change. Draft text is not an accepted decision.

package/capabilities/product/workflows/document-driven.md

@@ -11,3 +11,7 @@ Use when a project already supplies authorized BA/PO materials (Confluence, BRD,
 7. **Source changes:** compare actual source revisions and propose a reviewed requirements/code impact diff rather than overwriting user-owned artifacts.
 
 Canonical enterprise source stays in the enterprise system; consumer repo stores pointers, versioned derived docs and project-local engineering artifacts. RAG is optional permission-scoped retrieval, not a replacement for a system of record. The `aih` CLI does not ingest data or run agents.
+
+For new/material journeys, continue with `product-to-solution.md` after resolving the relevant scope.
+Use reviewed MVP/outcomes and optional Architecture/Delivery to assess solution/dependencies before
+OpenSpec implementation. Existing approved sources remain canonical; small clear changes stay compact.

package/capabilities/product/workflows/idea-driven.md

@@ -11,3 +11,7 @@ Use this when the developer starts with an idea, including a solo project. Produ
 7. **Changes:** when the idea changes, perform impact analysis and propose minimal document diffs; never silently overwrite approved requirements.
 
 Deliverables are **consumer-owned** `docs/discovery/`, `docs/product/` and `openspec/` files. For Confluence publishing, preserve URLs/page versions and request explicit write permission; the Harness CLI does not connect or publish to Confluence.
+
+For new/material journeys, continue with `product-to-solution.md` after resolving the relevant scope.
+Use reviewed MVP/outcomes and optional Architecture/Delivery to assess solution/dependencies before
+OpenSpec implementation. Existing approved sources remain canonical; small clear changes stay compact.

package/capabilities/product/workflows/product-to-solution.md

@@ -0,0 +1,15 @@
+# BA → PO → Solution → Delivery
+
+Use for a new product or material feature. For a small clear fix, use the Core compact path.
+1. BA preserves idea/approved document revisions, identifies users, business rules and contradictions;
+   load existing business-analysis/use-case/AC skills. Source/output register is authoritative.
+2. PO uses mvp-definition and product-outcomes to propose a complete journey, in/out scope, minimum
+   quality and success evidence. Resolve consequential unknowns with actual owner; no self-approval.
+3. Pass reviewed FR/US/AC/NFR and decision status to installed Architecture discovery-to-design.
+   If Architecture is not selected, Core spec uses the same constraints and records relevant choices.
+4. Pass accepted solution boundaries, AC, dependencies and actual estimates to optional Delivery planning;
+   absent Delivery, record a proportional task order in the OpenSpec change.
+5. UI/UX can iterate with SA/PO; adapters implement accepted technical decisions. Verify and review
+   against requirements/ADRs. Evidence and scope changes loop back to the owning role.
+6. Carry source revisions, IDs, output paths, decisions, unresolved questions, actual checks and next
+   owner in every handoff. A role label never creates a worker or approves a stakeholder decision.

package/cli/agents.js

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, readJson, isObject, SLUG, SOURCE, HarnessError } from './files.js';
+
+export const AGENT_CONFIG = '.harness/agents.json';
+export const DEFAULT_AGENTS = 'config/agents.default.json';
+export const PRESETS = ['recommended', 'economy', 'custom'];
+export const REASONING = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const ROLE = /^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$/;
+const text = value => typeof value === 'string' && value.trim() === value && value.length > 0
+  && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value);
+const requireThat = (condition, label) => { if (!condition) throw new HarnessError('Invalid agent configuration: ' + label); };
+function fields(value, allowed, required, label) {
+  requireThat(isObject(value) && Object.keys(value).every(key => allowed.includes(key))
+    && required.every(key => Object.hasOwn(value, key)), label + ' fields');
+}
+function reference(value, label) {
+  requireThat(text(value), label + ' must be nonempty single-line text (max 256 characters)');
+  if (value.startsWith('@')) requireThat(SLUG.test(value.slice(1)), label + ' alias syntax');
+  else requireThat(!/\s/.test(value), label + ' model ID must not contain whitespace');
+}
+function provider(value, label) { requireThat(typeof value === 'string' && SLUG.test(value), label + ' provider ID'); }
+function reasoning(value, label) { requireThat(REASONING.includes(value), label + ' reasoning level'); }
+
+export function resolveModel(config, referenceValue, visited = []) {
+  if (!referenceValue.startsWith('@')) return { model: referenceValue, provider: config.provider };
+  const alias = referenceValue.slice(1);
+  requireThat(Object.hasOwn(config.models, alias), 'unknown alias @' + alias);
+  requireThat(!visited.includes(alias), 'cyclic alias @' + alias);
+  const descriptor = config.models[alias];
+  const next = typeof descriptor === 'string' ? descriptor : descriptor.model;
+  const resolved = resolveModel(config, next, [...visited, alias]);
+  return { ...resolved, provider: typeof descriptor === 'object' ? descriptor.provider ?? resolved.provider : resolved.provider };
+}
+
+export function validateAgentConfig(config) {
+  fields(config, ['schema_version', 'provider', 'defaultModel', 'defaultReasoning', 'models', 'agents', 'execution', 'hosts'],
+    ['schema_version', 'provider', 'defaultModel', 'defaultReasoning', 'models', 'agents', 'execution'], 'root');
+  requireThat(config.schema_version === 1, 'unsupported schema_version');
+  provider(config.provider, 'default'); reference(config.defaultModel, 'defaultModel');
+  reasoning(config.defaultReasoning, 'default');
+  requireThat(isObject(config.models) && Object.keys(config.models).length <= 64, 'models map (max 64 aliases)');
+  for (const [alias, descriptor] of Object.entries(config.models)) {
+    requireThat(SLUG.test(alias), 'alias ID');
+    if (typeof descriptor === 'string') reference(descriptor, 'models.' + alias);
+    else {
+      fields(descriptor, ['model', 'provider'], ['model'], 'models.' + alias);
+      reference(descriptor.model, 'models.' + alias);
+      if (descriptor.provider !== undefined) provider(descriptor.provider, 'models.' + alias);
+    }
+  }
+  resolveModel(config, config.defaultModel);
+  for (const alias of Object.keys(config.models)) resolveModel(config, '@' + alias);
+  requireThat(isObject(config.agents) && Object.keys(config.agents).length <= 128, 'agents map (max 128 roles)');
+  for (const [id, agent] of Object.entries(config.agents)) {
+    requireThat(ROLE.test(id), 'role ID must use namespace:role');
+    fields(agent, ['model', 'provider', 'reasoning', 'enabled'], [], id);
+    if (agent.model !== undefined) { reference(agent.model, id); resolveModel(config, agent.model); }
+    if (agent.provider !== undefined) provider(agent.provider, id);
+    if (agent.reasoning !== undefined) reasoning(agent.reasoning, id);
+    requireThat(agent.enabled === undefined || typeof agent.enabled === 'boolean', id + ' enabled');
+  }
+  const execution = config.execution;
+  fields(execution, ['mode', 'maxConcurrentAgents', 'maxRounds', 'autoEscalateToPremium'],
+    ['mode', 'maxConcurrentAgents', 'maxRounds', 'autoEscalateToPremium'], 'execution');
+  requireThat(['single-agent', 'hybrid', 'multi-agent'].includes(execution.mode), 'execution mode');
+  requireThat(Number.isSafeInteger(execution.maxConcurrentAgents) && execution.maxConcurrentAgents >= 1
+    && execution.maxConcurrentAgents <= 32, 'maxConcurrentAgents must be an integer from 1 to 32');
+  requireThat(execution.mode !== 'single-agent' || execution.maxConcurrentAgents === 1, 'single-agent requires maxConcurrentAgents=1');
+  requireThat(Number.isSafeInteger(execution.maxRounds) && execution.maxRounds >= 1 && execution.maxRounds <= 20,
+    'maxRounds must be an integer from 1 to 20');
+  requireThat(execution.autoEscalateToPremium === false, 'autoEscalateToPremium must be false; select premium explicitly');
+  const hosts = config.hosts ?? {};
+  requireThat(isObject(hosts) && Object.keys(hosts).length <= 16, 'hosts map (max 16 profiles)');
+  for (const [id, profile] of Object.entries(hosts)) {
+    requireThat(SLUG.test(id), 'host ID'); fields(profile, ['models', 'reasoning'], [], 'host ' + id);
+    for (const key of ['models', 'reasoning']) {
+      const map = profile[key] ?? {};
+      requireThat(isObject(map) && Object.keys(map).length <= 128, 'host ' + id + ' ' + key + ' map');
+      for (const [from, to] of Object.entries(map)) {
+        requireThat(key === 'models' ? text(from) && from.includes('/') : REASONING.includes(from), 'host mapping key');
+        requireThat(text(to) && !to.startsWith('@'), 'host mapping target must be explicit native text');
+      }
+    }
+  }
+  return config;
+}
+
+function readConfiguration(root, relative) {
+  const filename = safe(root, relative), info = stat(filename);
+  if (!info) return null;
+  requireThat(info.isFile() && info.size <= 1024 * 1024, relative + ' must be a file up to 1 MiB');
+  let config;
+  try { config = JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { throw new HarnessError('Invalid JSON in ' + relative); }
+  return validateAgentConfig(config);
+}
+export function loadAgentConfig(root) { return readConfiguration(root, AGENT_CONFIG); }
+
+export function agentDefaults(source = SOURCE, preset = 'recommended') {
+  requireThat(PRESETS.includes(preset), 'unknown preset; use recommended, economy or custom');
+  // Older alternate bundles remain usable; the packaged CLI supplies the new canonical seed.
+  const config = structuredClone(readConfiguration(source, DEFAULT_AGENTS) ?? readConfiguration(SOURCE, DEFAULT_AGENTS));
+  requireThat(config !== null, 'missing canonical default');
+  if (preset === 'economy') {
+    config.defaultModel = '@economy'; config.defaultReasoning = 'low';
+    config.execution.mode = 'single-agent'; config.execution.maxConcurrentAgents = 1;
+    for (const agent of Object.values(config.agents)) { agent.model = '@economy'; agent.reasoning = 'low'; }
+  }
+  return validateAgentConfig(config);
+}
+
+export function registeredRoles(source, capabilities = []) {
+  const roles = {};
+  const folder = path.dirname(safe(source, 'core/agents/.role-index'));
+  for (const name of fs.readdirSync(folder).filter(name => name.endsWith('.md')).sort()) {
+    roles['core:' + name.slice(0, -3)] = 'core/agents/' + name;
+  }
+  for (const id of capabilities) {
+    const metadata = readJson(safe(source, `capabilities/${id}/capability.json`));
+    for (const file of metadata.agents ?? []) {
+      const role = id + ':' + path.basename(file, '.md');
+      roles[role] = `capabilities/${id}/${file}`;
+    }
+  }
+  return roles;
+}
+
+export function resolveAgent(config, id) {
+  const agent = Object.hasOwn(config.agents, id) ? config.agents[id] : {};
+  const resolved = resolveModel(config, agent.model ?? config.defaultModel);
+  return { id, ...resolved, provider: agent.provider ?? resolved.provider,
+    reasoning: agent.reasoning ?? config.defaultReasoning, enabled: agent.enabled !== false,
+    source: Object.hasOwn(config.agents, id) ? 'role' : 'project-default' };
+}
+
+export function agentPlan(root, host) {
+  if (host !== undefined) requireThat(typeof host === 'string' && SLUG.test(host), 'host ID');
+  const config = loadAgentConfig(root);
+  const presets = [{ label: 'A', value: 'recommended', description: 'Sol, hybrid, at most two concurrent agents when supported.' },
+    { label: 'B', value: 'economy', description: 'Economy model, single-agent roles.' },
+    { label: 'C', value: 'custom', description: 'Edit provider/model/reasoning and role/host mappings explicitly.' }];
+  const note = 'Read-only declaration. No provider/model probing, native config writes, agent spawning, concurrency/token enforcement or usage tracking. Verify model access, effort and delegation in the actual host before execution.';
+  if (!config) return { status: 'not-configured', configured: false, presets, roles: [], note };
+  const lock = readJson(safe(root, '.harness/lock.json'));
+  const registry = registeredRoles(path.join(root, '.harness'), lock.capabilities ?? []);
+  const ids = [...new Set([...Object.keys(registry), ...Object.keys(config.agents)])].sort();
+  const profile = config.hosts?.[host] ?? {};
+  const roles = ids.map(id => {
+    const requested = resolveAgent(config, id);
+    const active = requested.enabled && Object.hasOwn(registry, id);
+    const mapping = profile.models?.[requested.provider + '/' + requested.model];
+    const incompatible = !mapping && ((host === 'claude-code' &&
+      (!['anthropic', 'bedrock', 'vertex'].includes(requested.provider) || requested.model.startsWith('gpt-'))) ||
+      (host === 'gemini-cli' && (!['google', 'vertex'].includes(requested.provider) || requested.model.startsWith('gpt-'))));
+    return { ...requested, active, contract: registry[id] ? '.harness/' + registry[id] : null,
+      host_model: mapping ?? requested.model, host_reasoning: profile.reasoning?.[requested.reasoning] ?? requested.reasoning,
+      mapping: mapping ? 'explicit-user-host-mapping' : 'requested',
+      availability: active && incompatible ? 'incompatible-provider' : 'unverified',
+      runtime_verified: false };
+  });
+  return { status: roles.some(role => role.active && role.availability === 'incompatible-provider') ? 'host-incompatible' : 'requires-host-verification',
+    configured: true, host: host ?? null, presets, execution: config.execution, roles,
+    missing_mappings: Object.keys(registry).filter(id => !Object.hasOwn(config.agents, id)), note };
+}

package/cli/environment.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safe, stat, isObject, SLUG, HarnessError } from './files.js';
+import { agentPlan } from './agents.js';
+
+export const ENVIRONMENT = '.harness/environment.json';
+export const MACHINE = '.harness/machine.json';
+export const emptyEnvironment = () => ({ schema_version: 1, tools: {}, files: {}, commands: {} });
+const validText = s => typeof s === 'string' && s.trim().length > 0 && !/[\0\r\n]/.test(s);
+const own = (o, k) => Object.hasOwn(o, k);
+function requireThat(ok, message) { if (!ok) throw new HarnessError(message); }
+
+export function readConfig(root, name) {
+  const p = safe(root, name), info = stat(p);
+  if (!info) return null;
+  requireThat(info.size <= 1024 * 1024, 'Configuration exceeds 1 MiB: ' + name);
+  // Never include parser input (possibly private machine paths) in diagnostics.
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { throw new HarnessError('Invalid JSON: ' + name); }
+}
+function keys(value, allowed, label) {
+  requireThat(isObject(value) && Object.keys(value).every(k => allowed.includes(k)), 'Invalid fields: ' + label);
+}
+export function loadEnvironment(root) {
+  const shared = readConfig(root, ENVIRONMENT);
+  const machine = readConfig(root, MACHINE);
+  if (shared === null) {
+    requireThat(machine === null, 'Machine configuration requires environment.json');
+    return { configured: false, shared: emptyEnvironment(), machine: null };
+  }
+  keys(shared, ['schema_version', 'tools', 'files', 'commands'], ENVIRONMENT);
+  requireThat(shared.schema_version === 1, 'Unsupported environment schema');
+  for (const group of ['tools', 'files', 'commands']) {
+    requireThat(isObject(shared[group]), 'Missing environment map: ' + group);
+    for (const [id, value] of Object.entries(shared[group])) {
+      requireThat(SLUG.test(id), 'Invalid environment identifier');
+      const label = group + '/' + id;
+      if (group === 'commands') {
+        keys(value, ['tool', 'args'], label);
+        requireThat(validText(value.tool) && own(shared.tools, value.tool), 'Unknown command tool: ' + id);
+        requireThat(Array.isArray(value.args) && value.args.every(a => typeof a === 'string' && !/[\0\r\n]/.test(a)), 'Invalid arguments: ' + id);
+      } else {
+        const field = group === 'tools' ? 'executable' : 'path';
+        keys(value, [field, 'required'], label);
+        requireThat(validText(value[field]), 'Missing path: ' + label);
+        requireThat(value.required === undefined || typeof value.required === 'boolean', 'Invalid required flag: ' + label);
+      }
+    }
+  }
+  if (machine !== null) {
+    keys(machine, ['schema_version', 'tools', 'files'], MACHINE);
+    requireThat(machine.schema_version === 1, 'Unsupported machine schema');
+    for (const group of ['tools', 'files']) {
+      if (machine[group] === undefined) continue;
+      requireThat(isObject(machine[group]), 'Invalid machine map: ' + group);
+      const field = group === 'tools' ? 'executable' : 'path';
+      for (const [id, value] of Object.entries(machine[group])) {
+        requireThat(SLUG.test(id) && own(shared[group], id), 'Machine override must reference a declared ' + group + ' entry');
+        keys(value, [field], 'machine ' + group + '/' + id);
+        requireThat(validText(value[field]), 'Invalid machine override: ' + group + '/' + id);
+      }
+    }
+  }
+  return { configured: true, shared, machine };
+}
+
+function expand(value, env) {
+  const missing = [];
+  const resolved = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, key) => {
+    if (!own(env, key) || !validText(env[key])) { missing.push(key); return ''; }
+    return env[key];
+  });
+  return { resolved, missing: [...new Set(missing)], invalid: /\$\{/.test(resolved) };
+}
+function pathStatus(value, root, executable, env) {
+  if ((process.platform !== 'win32' && /^[A-Za-z]:[\\/]|^\\\\/.test(value)) ||
+      (process.platform === 'win32' && value.startsWith('/'))) return 'platform-mismatch';
+  if (value.startsWith('~')) return 'unsupported-path'; // No implicit shell expansion.
+  const bare = !path.isAbsolute(value) && !/[\\/]/.test(value);
+  const candidates = executable && bare
+    ? (env.PATH || '').split(path.delimiter).filter(Boolean).filter(path.isAbsolute).map(dir => path.join(dir, value))
+    : [path.resolve(root, value)];
+  const extensions = executable && process.platform === 'win32' && !path.extname(value)
+    ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';').filter(e => /^\.[A-Za-z0-9]+$/.test(e)) : [''];
+  let notExecutable = false;
+  for (const candidate of candidates) for (const ext of extensions) {
+    try {
+      const p = candidate + ext;
+      if (!fs.statSync(p).isFile()) continue;
+      fs.accessSync(p, executable && process.platform !== 'win32' ? fs.constants.X_OK : fs.constants.F_OK);
+      return 'present';
+    } catch (e) { if (e.code === 'EACCES') notExecutable = true; }
+  }
+  return notExecutable ? 'not-accessible' : 'missing';
+}
+
+export function environmentReport(root, env = process.env) {
+  const { configured, shared, machine } = loadEnvironment(root);
+  const entries = [];
+  for (const group of ['tools', 'files']) for (const [id, value] of Object.entries(shared[group])) {
+    const field = group === 'tools' ? 'executable' : 'path';
+    const override = machine?.[group]?.[id];
+    const expanded = expand(override ? override[field] : value[field], env);
+    entries.push({ group, id, source: override ? 'machine' : 'project', required: value.required !== false,
+      status: expanded.missing.length ? 'missing-env' : expanded.invalid ? 'invalid-reference'
+        : pathStatus(expanded.resolved, root, group === 'tools', env),
+      missing_variables: expanded.missing });
+  }
+  // Arguments are references only; do not execute or print resolved values.
+  for (const [id, command] of Object.entries(shared.commands)) {
+    const args = command.args.map(a => expand(a, env));
+    const missing = [...new Set(args.flatMap(a => a.missing))];
+    entries.push({ group: 'commands', id, source: 'project', required: shared.tools[command.tool].required !== false,
+      status: missing.length ? 'missing-env' : args.some(a => a.invalid) ? 'invalid-reference' : 'declared',
+      missing_variables: missing });
+  }
+  const problems = entries.filter(e => e.required && !['present', 'declared'].includes(e.status))
+    .map(e => e.group + '/' + e.id + ': ' + e.status);
+  return { configured, machine_present: machine !== null, entries, problems,
+    note: 'Presence/reference checks only. No commands executed; values and arguments are omitted. Never store credentials here.' };
+}
+
+export function setupPlan(root, adapters, env = process.env, host) {
+  const environment = environmentReport(root, env);
+  const configuredTools = environment.entries.some(e => e.group === 'tools');
+  const questions = [];
+  if (adapters.includes('java-spring') && !configuredTools) {
+    const wrapper = process.platform === 'win32' ? 'mvnw.cmd' : 'mvnw';
+    const hasWrapper = Boolean(stat(safe(root, wrapper)));
+    const gradle = ['gradlew', 'gradlew.bat', 'build.gradle', 'build.gradle.kts'].some(p => Boolean(stat(safe(root, p))));
+    if (gradle) {
+      questions.push({ id: 'build-tool', question: 'Which build tool does this project use?',
+        options: [{ label: 'A', value: 'gradle', description: 'Use the existing Gradle setup.' },
+          { label: 'B', value: 'maven', description: 'Use Maven only if project conventions require it.' }],
+        recommendation: 'A', reason: 'Gradle files exist; confirm the project convention.', allow_free_text: true });
+    } else questions.push({ id: 'maven-mode', question: 'How should Maven be invoked?',
+      options: [{ label: 'A', value: 'wrapper', description: 'Use the repository Maven Wrapper.' },
+        { label: 'B', value: 'path', description: 'Use Maven available on PATH.' },
+        { label: 'C', value: 'custom', description: 'Use an internal Maven executable and optional settings file.' }],
+      recommendation: hasWrapper ? 'A' : null,
+      reason: hasWrapper ? 'A wrapper exists for this OS; review it before execution.' : 'No wrapper found for this OS; ask which Maven the team uses.',
+      allow_free_text: true });
+  }
+  if (!environment.configured || !environment.entries.length) questions.push({
+    id: 'project-context', question: 'Where are the authoritative project requirements and conventions?',
+    options: [{ label: 'A', value: 'repository', description: 'Use existing repository documentation and build files.' },
+      { label: 'B', value: 'external', description: 'Use authorized BA/Confluence sources with revisions.' },
+      { label: 'C', value: 'idea', description: 'Start from the user idea and clarify the scope.' }],
+    recommendation: null, reason: 'The host must inspect existing local.md and sources before recommending.',
+    allow_free_text: true
+  }, {
+    id: 'project-mode', question: 'What is the scope of the affected code?',
+    options: [{ label: 'A', value: 'maintain', description: 'Extend existing modules using their conventions and shared APIs.' },
+      { label: 'B', value: 'new', description: 'Start a new application with a minimal agreed adapter baseline.' },
+      { label: 'C', value: 'mixed', description: 'Add a new module while preserving repository-wide contracts.' }],
+    recommendation: null,
+    reason: 'Inspect the task, local.md and neighboring code; stack detection or environment configuration does not establish project mode. Skip if already known.',
+    allow_free_text: true
+  });
+  return { status: environment.problems.length ? 'blocked' : 'planned', environment, questions,
+    agent_configuration: agentPlan(root, host),
+    next_steps: ['Read AGENTS.md, .harness/local.md and the installed project-setup workflow.',
+      'Apply installed Core project-conventions.md and relevant adapter conventions; establish mode per affected module even when no setup questions are suggested.',
+      'Inspect comparable code and search public shared APIs before creating files, dependencies or abstractions; record source paths and reuse/new-code rationale.',
+      'Skip answered questions; ask at most 1–3 consequential questions with evidence-based recommendations.',
+      'Review agents.json provider/model/reasoning and preset choices; verify access/effort/delegation in the actual host before execution. No automatic premium fallback.',
+      'Record shared decisions in local.md/environment.json; put only machine paths in ignored machine.json.',
+      'Run aih doctor, then use the reviewed project commands through your AI host.'],
+    note: 'Read-only host-facing suggestions, not an interactive terminal wizard or approval.' };
+}

package/cli/harness.js

@@ -1,4 +1,6 @@
 import fs from 'node:fs';
+import { emptyEnvironment, environmentReport } from './environment.js';
+import { AGENT_CONFIG, agentDefaults, loadAgentConfig } from './agents.js';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { loadAdapter } from './adapter-schema.js';
@@ -65,6 +67,7 @@ export function bundle(source, config) {
       files[dest] = fs.readFileSync(safe(source, `adapters/${a}/skills/${name}/SKILL.md`));
     }
   }
+  files['.harness/templates/agents.default.json'] = encode(agentDefaults(source));
   for (const c of capabilities) {
     const info = loadCapability(source, c);
     for (const name of info.skills) {
@@ -156,12 +159,15 @@ export function transaction(root, changes, writer = atomicWrite) {
   }
 }
 
-export function install(root, source, { command = 'init', adapters, capabilities, dryRun = false, allowMajor = false, writer } = {}) {
+export function install(root, source, { command = 'init', adapters, capabilities, agentPreset, dryRun = false, allowMajor = false, writer } = {}) {
   assertSeparate(root, source);
   return guard(root, () => {
     const hasLock = Boolean(stat(safe(root, LOCK)));
     if (command === 'update' && !hasLock) throw new HarnessError('Not installed; run init first');
     const old = hasLock ? loadLock(root) : null;
+    const existingAgents = loadAgentConfig(root);
+    if (agentPreset !== undefined && command !== 'init') throw new HarnessError('Agent preset is supported only by init');
+    if (agentPreset !== undefined && existingAgents) throw new HarnessError('agents.json is project-owned; edit it explicitly instead of applying an init preset');
     const config = projectConfig(root, adapters, capabilities, hasLock);
     const { files, lock, warnings } = bundle(source, config);
     if (old) {
@@ -185,11 +191,20 @@ export function install(root, source, { command = 'init', adapters, capabilities
     }
     if (old) for (const name of Object.keys(old.files)) if (!Object.hasOwn(files, name)) changes[name] = null;
     const seeds = {
+      [AGENT_CONFIG]: encode(agentDefaults(source, agentPreset ?? 'recommended')),
       [CONFIG]: encode(config),
+      '.harness/environment.json': encode(emptyEnvironment()),
       'openspec/config.yaml': fs.readFileSync(safe(source, 'templates/openspec/config.yaml')),
-      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n'),
+      '.harness/local.md': Buffer.from('# Project overrides\n\nRecord project facts and reviewed exceptions here. Never weaken security boundaries.\n\n## Development conventions\nRecord scope/mode (new, maintain or mixed), authoritative source paths, module boundaries, reusable public APIs, naming/error/test conventions and configured checks. Link existing guides instead of duplicating them. Unknowns are not approved defaults; the AI host inspects evidence and asks only consequential questions.\n'),
     };
     for (const [name, data] of Object.entries(seeds)) if (!stat(safe(root, name))) changes[name] = data;
+    // Project-owned ignore file: preserve all prior rules, place our anchored rule last.
+    // This does not remove an already tracked machine file from the Git index.
+    const ignoreName = '.harness/.gitignore', ignorePath = safe(root, ignoreName);
+    const ignore = stat(ignorePath) ? fs.readFileSync(ignorePath, 'utf8') : '';
+    if (ignore.trimEnd().split(/\r?\n/).at(-1) !== '/machine.json') {
+      changes[ignoreName] = Buffer.from(ignore + (ignore && !ignore.endsWith('\n') ? '\n' : '') + '/machine.json\n');
+    }
     const newLock = encode(lock);
     if (!hasLock || !fs.readFileSync(safe(root, LOCK)).equals(newLock)) changes[LOCK] = newLock;
     const plan = Object.entries(changes).map(([name, data]) => ({ path: name, action: data === null ? 'delete' : 'write' }));
@@ -201,6 +216,7 @@ export function install(root, source, { command = 'init', adapters, capabilities
 export function check(root) {
   const lock = loadLock(root), config = projectConfig(root, undefined, undefined, true);
   const problems = drift(root, lock);
+  loadAgentConfig(root); // Optional on legacy installs; validate user config without managing its bytes.
   if (JSON.stringify([...config.adapters].sort()) !== JSON.stringify([...lock.adapters].sort())) problems.push(`${CONFIG}: adapter selection changed; run update`);
   if (JSON.stringify([...(config.capabilities ?? [])].sort()) !== JSON.stringify([...(lock.capabilities ?? [])].sort())) problems.push(`${CONFIG}: capability selection changed; run update`);
   return { status: problems.length ? 'error' : 'ok', version: lock.version, problems };
@@ -214,6 +230,10 @@ export function newChange(root, name) {
     safe(root, `openspec/changes/${name}/proposal.md`);
     if (stat(folder)) throw new HarnessError(`Change already exists: ${name}`);
     const mapping = { 'proposal.md': 'proposal.md', 'design.md': 'design.md', 'tasks.md': 'tasks.md', 'spec.md': `specs/${name}/spec.md`, '.openspec.yaml': '.openspec.yaml' };
+    const locked = loadLock(root);
+    for (const name of ['decisions.json', 'verification.json']) {
+      if (Object.hasOwn(locked.files, '.harness/templates/openspec/' + name)) mapping[name] = name;
+    }
     const changes = {};
     for (const [src, dest] of Object.entries(mapping)) {
       const text = fs.readFileSync(safe(root, `.harness/templates/openspec/${src}`), 'utf8');
@@ -224,20 +244,28 @@ export function newChange(root, name) {
   });
 }
 
-// Product drafts are project-owned and never added to the managed bundle.
-export function newDoc(root, name) {
+// Capability drafts are project-owned and never added to the managed bundle.
+export function newDoc(root, name, capability = 'product') {
   if (!SLUG.test(name)) throw new HarnessError('Document type must be a lowercase hyphenated slug');
+  if (!SLUG.test(capability)) throw new HarnessError('Capability must be a lowercase hyphenated slug');
   return guard(root, () => {
     if (check(root).status !== 'ok') throw new HarnessError('Fix installation drift before creating a document');
     const lock = loadLock(root);
-    if (!(lock.capabilities ?? []).includes('product')) throw new HarnessError('Product capability is not installed');
-    const sourceName = `.harness/capabilities/product/templates/${name}.md`;
-    if (!Object.hasOwn(lock.files, sourceName)) throw new HarnessError(`Unknown product document type: ${name}`);
-    const folder = ['idea', 'research'].includes(name) ? 'discovery' : 'product';
+    if (!(lock.capabilities ?? []).includes(capability)) {
+      throw new HarnessError(capability === 'product' ? 'Product capability is not installed' : `Capability is not installed: ${capability}`);
+    }
+    const sourceName = `.harness/capabilities/${capability}/templates/${name}.md`;
+    if (!Object.hasOwn(lock.files, `.harness/capabilities/${capability}/capability.json`)) {
+      throw new HarnessError(`Capability metadata is not locked: ${capability}`);
+    }
+    const declared = loadCapability(path.join(root, '.harness'), capability).templates;
+    if (!declared.includes(`templates/${name}.md`)) throw new HarnessError(`Unknown document type for ${capability}: ${name}`);
+    if (!Object.hasOwn(lock.files, sourceName)) throw new HarnessError(`Document template is not locked: ${capability}/${name}`);
+    const folder = capability === 'product' && ['idea', 'research'].includes(name) ? 'discovery' : capability;
     const outputName = `docs/${folder}/${name}.md`;
     if (stat(safe(root, outputName))) throw new HarnessError(`Document already exists: ${outputName}`);
     transaction(root, { [outputName]: fs.readFileSync(safe(root, sourceName)) });
-    return { status: 'ok', type: name, path: outputName,
+    return { status: 'ok', type: name, capability, path: outputName,
       note: 'Template only; populate from authorized evidence and obtain human approval.' };
   });
 }
@@ -251,5 +279,7 @@ export function doctor(root) {
       catch { return false; }
     }));
   }
-  return { ...check(root), tools, note: 'Tool presence only; no commands executed or compatibility claim made' };
+  const state = check(root), environment = environmentReport(root);
+  return { ...state, status: state.status !== 'ok' || environment.problems.length ? 'error' : 'ok',
+    tools, environment, note: 'Tool presence only; no commands executed or compatibility claim made. Configured project tools take precedence over generic PATH hints.' };
 }