@dtlabs/ai-toolkit 0.13.0 → 0.14.1

package/lib/workflow-artifacts.js

@@ -0,0 +1,102 @@
+'use strict';
+
+function cell(value) { return String(value ?? '—').replace(/\|/g, '\\|').replace(/[\r\n]/g, ' '); }
+function table(headers, rows) {
+  return [headers, headers.map(() => '---'), ...rows].map(row => '| ' + row.map(cell).join(' | ') + ' |').join('\n') + '\n';
+}
+function pricing(control) {
+  if (!control.exists('docs/token-pricing.json')) return null;
+  const value = control.json('docs/token-pricing.json');
+  if (!value || !value.models || !Number.isFinite(value.usd_to_eur) || value.usd_to_eur <= 0) throw new Error('Invalid token pricing');
+  return value;
+}
+function cost(tokens, model, rates) {
+  if (!rates || !Number.isFinite(tokens)) return null;
+  const rate = rates.models[model];
+  if (!rate || ![rate.input_per_1m_usd, rate.output_per_1m_usd].every(v => Number.isFinite(v) && v >= 0)) throw new Error('Invalid model pricing: ' + model);
+  return tokens * (0.8 * rate.input_per_1m_usd + 0.2 * rate.output_per_1m_usd) / 1000000 * rates.usd_to_eur;
+}
+function tokensDocument(c, prefix) {
+  const rates = pricing(c);
+  return `# Token Estimate — ${prefix}\n\nActuals for this invocation only; previous phases remain in the ledger. Missing usage is unavailable, not zero. Costs use an estimated 80/20 input/output split.\n\n` +
+    table(['Agent', 'Model', 'Tokens Actual', 'Estimated cost EUR'], c.tokenLedger.map(e => [e.agent, e.model, e.phase_delta_tokens, cost(e.phase_delta_tokens, e.model, rates)?.toFixed(4)]));
+}
+function estimates(c, dir, prefix, wb) {
+  if (!wb || !Array.isArray(wb.phases) || !wb.phases.length) throw new Error('Invalid Work Breakdown phases');
+  const tasks = wb.phases.flatMap(p => { if (!Array.isArray(p.tasks)) throw new Error('Invalid phase tasks'); return p.tasks; });
+  const rates = { BE: 120, TEST: 60, INFRA: 30, FE: 90, DB: 90, DevOps: 30 };
+  const domains = {};
+  for (const t of tasks) { if (!Object.hasOwn(rates, t.domain)) throw new Error('Unknown task domain'); domains[t.domain] = (domains[t.domain] || 0) + 1; }
+  const human = list => list.reduce((n, t) => n + rates[t.domain], 0);
+  const minutes = human(tasks);
+  const human_estimate = `~${Math.floor(minutes / 60)}h ${minutes % 60}min`;
+  const agentMinutes = tasks.every(t => Number.isFinite(t.estimate?.agentMinutes)) ? tasks.reduce((n, t) => n + t.estimate.agentMinutes, 0) : null;
+  const agent_estimate = agentMinutes == null ? 'unavailable' : `${agentMinutes}min (sequential estimate)`;
+  const base = `${dir}/${prefix}`;
+  const metrics = { prefix, feature_dir: dir, feature_title: wb.title || wb.feature || prefix,
+    total_tasks: tasks.length, user_stories: wb.phases.filter(p => p.id.startsWith('US-')).length,
+    domain_breakdown: Object.entries(domains).map(([d, n]) => `${d}: ${n}`).join(', '),
+    implementation_phases: wb.phases.length, human_estimate, agent_estimate,
+    work_breakdown_path: `${base}-Work-Breakdown.json`, tasks_csv_path: `${base}-Work-Breakdown.csv`,
+    effort_estimate_path: `${base}-Effort-Estimate.md`, token_estimate_path: `${base}-Token-Estimate.md` };
+  c.write(metrics.effort_estimate_path, `# Effort Estimate — ${prefix} — ${cell(metrics.feature_title)}\n\n` +
+    table(['Metric', 'Value'], [['User Stories', metrics.user_stories], ['Total tasks', tasks.length], ['Human estimate', human_estimate], ['Agent estimate', agent_estimate]]) +
+    '\n## Per-Phase Breakdown\n\n' + table(['Phase', 'Title', 'Tasks', 'Est. Human minutes', 'Actual Human', 'Actual Agent'],
+      wb.phases.map(p => [p.id, p.title, p.tasks.length, human(p.tasks), '—', '—'])));
+  c.write(metrics.token_estimate_path, tokensDocument(c, prefix));
+  return metrics;
+}
+function interventions(c, dir, prefix) {
+  const raw = c.read(`${dir}/${prefix}-Interventions-Index.md`);
+  const lines = raw.split(/\r?\n/).filter(l => l.trim().startsWith('|'));
+  const split = line => line.trim().replace(/^\||\|$/g, '').split(/(?<!\\)\|/).map(s => s.trim());
+  const headerAt = lines.findIndex(l => split(l).some(v => /^(Criticality|Severity)$/i.test(v)));
+  if (headerAt < 0) throw new Error('Interventions index missing Criticality column');
+  const headers = split(lines[headerAt]), severityAt = headers.findIndex(v => /^(Criticality|Severity)$/i.test(v));
+  const rows = [];
+  for (const line of lines.slice(headerAt + 1)) {
+    const values = split(line);
+    if (values.every(v => /^:?-+:?$/.test(v))) continue;
+    const id = line.match(/\bINT-\d+\b/);
+    if (!id) continue;
+    const severity = values[severityAt]?.replace(/\*/g, '').toUpperCase();
+    if (!['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].includes(severity)) throw new Error('Unknown intervention severity: ' + severity);
+    if (rows.some(r => r.id === id[0])) throw new Error('Duplicate intervention ID: ' + id[0]);
+    rows.push({ id: id[0], severity });
+  }
+  return rows;
+}
+function assessmentEstimates(c, dir, prefix) {
+  const rows = interventions(c, dir, prefix);
+  const severity_counts = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+  const rates = { CRITICAL: 8, HIGH: 4, MEDIUM: 2, LOW: 1 };
+  rows.forEach(r => severity_counts[r.severity]++);
+  const hours = rows.reduce((n, r) => n + rates[r.severity], 0);
+  const base = `${dir}/${prefix}`;
+  c.write(`${base}-Token-Estimate.md`, tokensDocument(c, prefix));
+  c.write(`${base}-Effort-Estimate.md`, `# Effort Estimate — ${prefix}\n\n` +
+    table(['Severity', 'Count', 'Hours each', 'Subtotal hours'], Object.entries(severity_counts).map(([s, n]) => [s, n, rates[s], n * rates[s]])) + `\nTotal: ${hours} human hours (estimate).\n`);
+  return { severity_counts, total_interventions: rows.length, remediation_hours_est: hours,
+    interventions_index_path: `${base}-Interventions-Index.md`, effort_estimate_path: `${base}-Effort-Estimate.md`, token_estimate_path: `${base}-Token-Estimate.md` };
+}
+function recordAssessmentApproval(c, dir, prefix, ack, flagged) {
+  const rows = interventions(c, dir, prefix);
+  const selected = flagged === 'none' ? [] : flagged.split(',').map(s => s.trim());
+  for (const id of selected) if (!rows.some(r => r.id === id)) throw new Error('Unknown flagged intervention: ' + id);
+  const today = new Date().toISOString().slice(0, 10), approvals_path = `${dir}/${prefix}-Approvals.md`;
+  const content = `# Assessment Approvals — ${prefix}\n\n## Findings Gate Acknowledgement\n\n` +
+    table(['Field', 'Value'], [['Acknowledged by', 'Toolkit user'], ['Date', today], ['Acknowledgement', ack]]) +
+    '\n## Interventions Flagged for Feature Delivery\n\n' + table(['Intervention', 'Flagged', 'Date', 'Notes'], rows.map(r => [r.id, selected.includes(r.id) ? 'Yes' : 'No', today, selected.includes(r.id) ? '—' : 'Not selected']));
+  c.write(approvals_path, content);
+  if (c.read(approvals_path) !== content) throw new Error('Approval readback mismatch');
+  const registryPath = 'docs/assessments/registry.md';
+  const header = '# Assessment Registry\n\n' + table(['Date', 'Prefix', 'Total', 'CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'Flagged'], []);
+  const old = c.exists(registryPath) ? c.read(registryPath) : header;
+  const row = `| ${today} | [${prefix}](${prefix}/) | ${rows.length} | ` +
+    ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].map(s => rows.filter(r => r.severity === s).length).join(' | ') + ` | ${selected.length} |`;
+  c.write(registryPath, old.split('\n').filter(l => !l.includes(`[${prefix}](`)).join('\n').trimEnd() + '\n' + row + '\n');
+  c.read(registryPath);
+  return { approvals_path, registry_updated: registryPath, flagged_count: selected.length, summary: `${prefix}: ${selected.length} interventions selected` };
+}
+
+module.exports = { estimates, assessmentEstimates, recordAssessmentApproval, interventions };

package/lib/workflow-control.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// Node host for workflow control-plane operations. Never ask an LLM to do I/O.
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const registry = require('./agent-registry');
+const ledger = require('./execution-ledger');
+const { spawnClaudeAgent } = require('./task-executor/claude-process');
+const CLI = path.join(__dirname, '..', 'bin', 'cli.js');
+
+
+// Runtime payload has no third-party dependencies. Only these two canonical
+// scalar fields are needed; reject ambiguous/duplicate declarations.
+function definitionFields(source) {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error('Agent frontmatter missing');
+  const fields = {};
+  for (const key of ['name', 'model']) {
+    const lines = match[1].split(/\r?\n/).filter(l => l.startsWith(key + ':'));
+    if (lines.length !== 1) throw new Error('Ambiguous agent field: ' + key);
+    fields[key] = lines[0].slice(key.length + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(fields.name) || !['haiku', 'sonnet', 'opus'].includes(fields.model)) throw new Error('Invalid agent name/model');
+  return fields;
+}
+
+function validateIdentity(id, record, kind = 'agent') {
+  const entry = registry.CATALOG.find(e => e.agentId === id);
+  if (!entry || (entry.role === 'orchestrator') !== (kind === 'workflow') ||
+      !record || record.agentId !== id || record.status !== 'verified' ||
+      record.nativeName !== entry.nativeNames.claude ||
+      !record.path || !/^sha256:[a-f0-9]{64}$/.test(record.sha256 || '')) {
+    throw new Error('Invalid verified ' + kind + ' identity: ' + id);
+  }
+  const bytes = fs.readFileSync(record.path);
+  if ('sha256:' + crypto.createHash('sha256').update(bytes).digest('hex') !== record.sha256) {
+    throw new Error('Definition hash changed: ' + id);
+  }
+  if (kind === 'agent' && definitionFields(bytes.toString()).name !== record.nativeName) {
+    throw new Error('Agent frontmatter/nativeName mismatch: ' + id);
+  }
+  return record;
+}
+
+function parseArgs(input) {
+  if (Array.isArray(input)) return input.slice();
+  const tokens = [];
+  let value = '', quote = null, started = false;
+  for (const ch of String(input || '')) {
+    if (quote) { if (ch === quote) quote = null; else value += ch; }
+    else if (ch === '"' || ch === "'") { quote = ch; started = true; }
+    else if (/\s/.test(ch)) { if (started) { tokens.push(value); value = ''; started = false; } }
+    else { value += ch; started = true; }
+  }
+  if (quote) throw new Error('Unterminated argument quote');
+  if (started) tokens.push(value);
+  return tokens;
+}
+
+function deriveFeatureDir(featurePath) {
+  return /[/\\]feature\.md$/i.test(featurePath)
+    ? featurePath.replace(/[/\\]feature\.md$/i, '')
+    : featurePath.replace(/[/\\]+$/, '')
+}
+
+function createControl(options) {
+  const root = path.resolve(options.projectDir);
+  const runId = crypto.randomUUID();
+  let context, spent = 0, sequence = 0;
+  const tokenLedger = [];
+  const pending = new Set();
+  const full = p => path.resolve(root, p);
+  const read = p => fs.readFileSync(full(p), 'utf8');
+  const exists = p => { try { return fs.statSync(full(p)).isFile(); } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+  const write = (p, content) => {
+    const dest = full(p);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const tmp = dest + '.tmp-' + crypto.randomUUID();
+    try { fs.writeFileSync(tmp, content, 'utf8'); fs.renameSync(tmp, dest); }
+    finally { if (fs.existsSync(tmp)) fs.unlinkSync(tmp); }
+  };
+  async function resolve(id, kind = 'agent') {
+    const record = await registry.resolveAgent({ projectDir: root, homeDir: options.home,
+      agentId: id, requireVerified: true });
+    return validateIdentity(id, record, kind);
+  }
+  function command(argv, accepted = [0]) {
+    if (!Array.isArray(argv) || argv.some(a => typeof a !== 'string')) throw new Error('CLI argv array required');
+    if (options.home && argv[0] === 'run-asset') {
+      argv = argv.slice();
+      const split = argv.indexOf('--');
+      argv.splice(split < 0 ? argv.length : split, 0, '--home', options.home);
+    }
+    const result = spawnSync(process.execPath, [CLI, ...argv], {
+      cwd: root, encoding: 'utf8', shell: false, windowsHide: true,
+      timeout: 120000, maxBuffer: 20 * 1024 * 1024,
+    });
+    if (result.error || !Number.isInteger(result.status) || !accepted.includes(result.status)) {
+      throw new Error('Deterministic command failed: ' + (result.error?.message || result.stderr || result.status));
+    }
+    return { exitCode: result.status, stdout: result.stdout, stderr: result.stderr };
+  }
+  async function activity(label, fn, model, usage = () => null, metadata) {
+    if (!context) throw new Error('Workflow ownership not established');
+    const key = `${context.name}:${label}:${runId}:${++sequence}`;
+    ledger.openOwned(context.dir, context.prefix, key, context.name, model, runId, metadata);
+    try {
+      const result = await fn();
+      ledger.finalizeOwned(context.dir, context.prefix, key, runId, 'done', undefined, usage());
+      return result;
+    } catch (error) {
+      try { ledger.finalizeOwned(context.dir, context.prefix, key, runId, 'failed', String(error), usage()); }
+      catch (persistError) { throw new AggregateError([error, persistError], 'Activity failed and ledger finalization failed'); }
+      throw error;
+    }
+  }
+  async function worker(id, prompt, opts = {}) {
+    let measuredTokens = null;
+    const identity = await resolve(id);
+    const definition = definitionFields(read(identity.path));
+    return activity(opts.label || id, async () => {
+      const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName];
+      if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
+      const result = await (options.dispatch || spawnClaudeAgent)({
+        claudePath: options.claudePath, cwd: root, args: cliArgs, prompt,
+        taskTimeoutMs: options.taskTimeoutMs || 1800000,
+      });
+      if (result.exitCode !== 0 || result.parseError || result.timedOut ||
+          !result.result || result.result.is_error !== false) throw new Error('Worker failed: ' + id);
+      const payload = opts.schema ? result.result.structured_output : result.result.result;
+      if (payload == null || (typeof payload === 'string' && !payload.trim())) {
+        if (opts.schema) {
+          const fields = (opts.schema.required || []).join(', ') || '(see requested schema)';
+          throw new Error('Worker returned no structured output: ' + id + '; expected fields: ' + fields + '. The --json-schema response must populate structured_output; a report file or plain-text result is not sufficient.');
+        }
+        throw new Error('Worker returned no result: ' + id);
+      }
+      if (opts.schema) validateSchema(payload, opts.schema);
+      const usage = result.result.usage;
+      const tokens = usage && [usage.input_tokens, usage.output_tokens].every(Number.isFinite)
+        ? usage.input_tokens + usage.output_tokens + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0) : null;
+      measuredTokens = Number.isInteger(tokens) && tokens > 0 ? tokens : null;
+      spent += measuredTokens || 0;
+      tokenLedger.push({ agent: identity.nativeName, model: definition.model, phase_delta_tokens: measuredTokens });
+      return payload;
+    }, definition.model, () => measuredTokens, { agentId: id, nativeAgentName: identity.nativeName, platform: 'claude', definitionHash: identity.sha256, resolutionScope: identity.scope, toolkitVersion: identity.toolkitVersion });
+  }
+  async function parallel(fns) {
+    // Drain every sibling before finalizing the owner, even if one rejects.
+    const work = Promise.allSettled(fns.map(fn => Promise.resolve().then(fn)));
+    pending.add(work);
+    try {
+      const results = await work;
+      const failed = results.filter(r => r.status === 'rejected');
+      if (failed.length) throw new AggregateError(failed.map(r => r.reason), 'Parallel workers failed');
+      return results.map(r => r.value);
+    } finally { pending.delete(work); }
+  }
+  async function run(name, dir, prefix, fn) {
+    if (context) throw new Error('Nested workflow ownership forbidden');
+    if (!/^(?:FTR|ASSESS|[A-Z]+)-\d+$/.test(prefix)) throw new Error('Invalid workflow prefix');
+    context = { name, dir: full(dir), prefix };
+    fs.mkdirSync(context.dir, { recursive: true });
+    const key = `${name}:self:${runId}`;
+    const runLockPath = path.join(context.dir, prefix + '-workflow.lock');
+    const runLock = ledger._acquireLock(runLockPath);
+    try {
+    ledger.openOwned(context.dir, prefix, key, name, null, runId);
+    try {
+      const result = await fn();
+      await Promise.allSettled([...pending]);
+      if (!result || result.error || result.errors?.length || result.gate2_payload?.gate2_blocked) {
+        throw new Error('Workflow returned unsuccessful result: ' + JSON.stringify(result));
+      }
+      // All work, output validation and serialization precede the terminal commit.
+      const serialized = JSON.stringify(result);
+      const committedResult = JSON.parse(serialized);
+      ledger.finalizeOwned(context.dir, prefix, key, runId, 'done');
+      return committedResult;
+    } catch (error) {
+      await Promise.allSettled([...pending]);
+      try { ledger.finalizeOwned(context.dir, prefix, key, runId, 'failed', String(error)); }
+      catch (persistError) { throw new AggregateError([error, persistError], 'Workflow failed; ledger finalization failed'); }
+      throw error;
+    }
+    } finally { ledger._releaseLock(runLockPath, runLock); }
+  }
+  function feature(p) {
+    if (!p) throw new Error('Feature path required');
+    const file = full(p), dir = deriveFeatureDir(file);
+    const match = path.basename(dir).match(/^([A-Z]+-\d+)(?:-|$)/);
+    if (!match) throw new Error('Cannot derive canonical feature prefix');
+    read(file);
+    return { featurePath: file, featureDir: dir, prefix: match[1] };
+  }
+  const api = { root, runId, read, exists, write, resolve, worker, parallel, run, command, activity,
+    feature, parseArgs, tokenLedger, spent: () => spent,
+    mtime: p => fs.statSync(full(p)).mtimeMs,
+    json: p => JSON.parse(read(p)),
+    log: text => (options.log || (() => {}))(String(text)),
+    append: (p, text) => { fs.mkdirSync(path.dirname(full(p)), { recursive: true }); fs.appendFileSync(full(p), text); },
+  };
+  const artifacts = require('./workflow-artifacts');
+  api.estimates = (...args) => artifacts.estimates(api, ...args);
+  api.assessmentEstimates = (...args) => artifacts.assessmentEstimates(api, ...args);
+  api.recordAssessmentApproval = (...args) => artifacts.recordAssessmentApproval(api, ...args);
+  return api;
+}
+
+function validateSchema(value, schema) {
+  if (schema.type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid structured object');
+    for (const key of schema.required || []) if (!(key in value)) throw new Error('Missing structured field: ' + key);
+    for (const [key, sub] of Object.entries(schema.properties || {})) if (key in value) validateSchema(value[key], sub);
+  } else if (schema.type === 'array') {
+    if (!Array.isArray(value)) throw new Error('Invalid structured array');
+    if (schema.items) value.forEach(v => validateSchema(v, schema.items));
+  } else if (schema.type && (typeof value !== schema.type || (schema.type === 'number' && !Number.isFinite(value)))) {
+    throw new Error('Invalid structured ' + schema.type);
+  }
+}
+
+module.exports = { createControl, validateIdentity, validateSchema, parseArgs, deriveFeatureDir };

package/lib/workflow-runner.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const fs = require('fs');
+const { createControl, parseArgs } = require('./workflow-control');
+const IDS = {
+  'pm-phase1': 'gaia.orchestrator.feature.phase1',
+  'pm-phase2': 'gaia.orchestrator.feature.phase2',
+  'am-phase1': 'gaia.orchestrator.assessment.phase1',
+  'am-phase2': 'gaia.orchestrator.assessment.phase2',
+};
+
+async function runWorkflow(name, args, options) {
+  if (!IDS[name]) throw new Error('Unsupported workflow: ' + name + '. For implementation use ai-toolkit tasks start/run (FTR-018).');
+  const control = createControl(options);
+  const identity = await control.resolve(IDS[name], 'workflow');
+  const source = fs.readFileSync(identity.path, 'utf8');
+  if (!/controlPlaneVersion:\s*1\b/.test(source)) throw new Error('Installed workflow does not support deterministic control-plane v1; reinstall toolkit assets.');
+  // Only verified toolkit scripts are evaluated. This host is not a security sandbox.
+  const body = source.replace(/^export const meta\s*=/m, 'const meta =');
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+  return new AsyncFunction('control', 'args', body)(control, parseArgs(args));
+}
+
+async function main(argv) {
+  if (argv[0] !== 'run') throw new Error('Usage: ai-toolkit workflow run NAME --project DIR --claude-path EXE -- ARGS');
+  const split = argv.indexOf('--');
+  if (split < 0) throw new Error('Workflow arguments must follow --');
+  const options = { projectDir: process.cwd(), log: s => process.stderr.write(s + '\n') };
+  const keys = { '--project': 'projectDir', '--home': 'home', '--claude-path': 'claudePath' };
+  for (let i = 2; i < split; i += 2) {
+    if (!keys[argv[i]] || !argv[i + 1] || argv[i + 1].startsWith('--')) throw new Error('Invalid workflow option: ' + argv[i]);
+    options[keys[argv[i]]] = argv[i + 1];
+  }
+  if (!options.claudePath && argv[1] !== 'am-phase2') throw new Error('--claude-path is required');
+  const result = await runWorkflow(argv[1], argv.slice(split + 1), options);
+  process.stdout.write(JSON.stringify(result) + '\n');
+}
+
+module.exports = { runWorkflow, main };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/gaia-intervention-documentation-standard.md

@@ -89,12 +89,12 @@ Other interventions that must be completed first (blocking) or should be coordin
 What to do if the intervention fails mid-way: rollback strategy, branch isolation, partial revert steps.
 
 ### 17. Suggested Agent Assignment
-Which agent type should execute this intervention:
-- `developer-backend` — backend/infrastructure implementation
-- `developer-frontend` — frontend/UI implementation
-- `developer-testing` — test writing
-- `review-solution` — post-intervention validation
-- Specialised agent (e.g. `security-hardening`) if available in `.claude/agents/`
+Which verified native agent should implement this intervention (recommendations only, never assessment dispatch):
+- `gaia-developer-backend` — backend/infrastructure implementation
+- `gaia-developer-frontend` — frontend/UI implementation
+- `gaia-developer-testing` — test writing
+- `gaia-review-solution` — post-intervention validation
+- Specialised agent (e.g. `gaia-security-hardening`) if available in `.claude/agents/`
 
 ### 18. Expected Outputs
 List of files to be created or modified. Each entry: `file path` → what changes.
@@ -124,9 +124,9 @@ After writing all intervention documents, produce `{ASSESS_PREFIX}-Interventions
 
 | ID | Title | Area | Criticality | Depends on | Suggested Agent |
 |---|---|---|---|---|---|
-| INT-001 | ... | Security | CRITICAL | — | developer-backend |
-| INT-002 | ... | Code Quality | HIGH | INT-003 | developer-backend |
-| INT-003 | ... | Architecture | HIGH | — | developer-backend |
+| INT-001 | ... | Security | CRITICAL | — | gaia-developer-backend |
+| INT-002 | ... | Code Quality | HIGH | INT-003 | gaia-developer-backend |
+| INT-003 | ... | Architecture | HIGH | — | gaia-developer-backend |
 ```
 
 Order by criticality (CRITICAL first), then by dependency (prerequisites before dependents).

package/src/claude/agents/gaia-validate-feature-docs.md

@@ -1,13 +1,13 @@
 ---
 name: gaia-validate-feature-docs
-description: "Validates Requirements and Tech-Spec documents against feature.md. Triggers targeted revision of failing documents if gaps are found. Input: path to feature.md"
+description: "Validates Requirements and Tech-Spec documents against feature.md. Writes a validation report and returns a structured verdict; the host owns revisions. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep, Write
 ---
 
 # Validate Feature Docs
 
-A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md` and `{PREFIX}-Tech-Spec.md`, identifies coverage gaps, and triggers targeted revisions until full coverage is achieved.
+A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md` and `{PREFIX}-Tech-Spec.md` and identifies coverage gaps in a single validation pass. The host workflow owns revisions and the three-cycle limit. Do not dispatch other agents or revise the input documents.
 
 ---
 
@@ -18,7 +18,7 @@ A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md`
    - `feature.md` — source of truth
    - `{PREFIX}-Requirements.md`
    - `{PREFIX}-Tech-Spec.md`
-3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /implement-feature first."
+3. If an input document is missing, record a finding identifying it, skip checks that require it, and complete Phases 6 and 7 with `valid: false`. Never claim full coverage when an input could not be read.
 
 ---
 
@@ -101,31 +101,21 @@ Result: ✅ Full coverage — all feature claims addressed in both documents
 
 ---
 
-## Phase 5 — Revision Loop
+## Phase 5 — Return Findings to the Host
 
-If gaps were found, trigger targeted revisions. **Only revise the documents that have gaps** — do not touch clean documents.
+Collect all remaining gaps for the host's revision loop. Do not invoke agents, edit Requirements or Tech-Spec, or run a revision loop yourself.
 
-### Revision instructions
+Each finding must be one string prefixed with `Requirements:` or `Tech-Spec:` to identify the affected document, followed by the exact section or claim and the missing coverage. If a gap affects both documents, emit one finding per document.
 
-For each document with gaps, invoke the corresponding agent with a **targeted revision prompt** that includes:
-1. The path to the existing document to revise (not regenerate from scratch)
-2. The exact list of gaps to address
-3. The instruction to revise only the affected sections
-
-### Revision rules
-
-- **Max iterations**: 3 revision cycles. If gaps persist after 3 rounds, write the remaining gaps to the report and stop.
-- **After each revision**: re-run Phase 3 on the updated document to verify gaps are resolved
-- **Document what changed**: after each revision, note which gaps were resolved
-- **Never revise a document that has no gaps** — even if the other document is being revised
+Use the same remaining gaps in the report and the structured verdict. Record a gap as resolved only when the current documents demonstrate that it is resolved.
 
 ---
 
-## Phase 6 — Write Validation Report (MANDATORY — your final action)
+## Phase 6 — Write Validation Report (MANDATORY — before returning the verdict)
 
 **This is not optional and not the same as the Phase 4 gap report.** The coverage report you produced in Phase 4 is on-screen text; it is NOT the deliverable. Your job is not complete until the file `{PREFIX}-Validation-Report.md` exists **on disk**. You MUST call the `Write` tool to create it — even when validation is clean and zero gaps were found. Returning a summary without having called `Write` is a failure.
 
-Execute this phase **last, always**, regardless of outcome. Downstream agents read this file as a hard precondition; if it is missing, the entire pipeline aborts.
+Execute this phase regardless of the validation outcome, then complete Phase 7. Downstream agents read this file as a hard precondition; if it is missing, the entire pipeline aborts.
 
 Write `{PREFIX}-Validation-Report.md` in the same directory:
 
@@ -154,23 +144,36 @@ Write `{PREFIX}-Validation-Report.md` in the same directory:
 
 ---
 
-## Clarification Protocol
+## Phase 7 — Structured Completion (MANDATORY — your final response)
+
+After writing the report, return a single JSON object with exactly these fields, without Markdown fences or explanatory prose:
+
+```json
+{"valid": true, "findings": []}
+```
+
+For remaining gaps:
 
-When a gap is found but the correct resolution is ambiguous (e.g., the feature.md itself is contradictory, or a gap could be filled in multiple valid ways), **stop and ask the user** before revising. Use the `AskUserQuestion` tool to present:
+```json
+{"valid": false, "findings": ["Requirements: UC-01 lacks an acceptance criterion", "Tech-Spec: POST /api/users lacks a response definition"]}
+```
 
-1. A clear description of the gap and why the resolution is uncertain
-2. Concrete options (2–4) representing valid ways to address it
-3. **Always include** an option: "Leave as open point to discuss later" — which records the gap in the Validation Report as unresolved (not a failure) and skips revision for that item
+- `valid` is a boolean: `true` only when all required inputs were read, coverage is complete, and no unresolved gaps remain.
+- `findings` is an array of strings, empty only for a clean validation. Missing inputs and ambiguous claims are unresolved findings.
+- When the caller supplies `--json-schema`, use the runtime's structured-output mechanism to return this object in `structured_output`. Plain-text JSON alone does not satisfy that contract.
+- Both deliverables are required: the report on disk **and** the structured verdict. Writing the report does not finish the task.
+
+## Clarification Protocol
 
-Do NOT guess how to fill ambiguous gaps. Ask first, then revise only with a clear direction.
+If a claim is contradictory or its correct resolution is ambiguous, do not guess or request interactive input inside this worker. Describe the ambiguity in the report and the affected document's finding, with `valid: false`, so the calling orchestration can surface it to the user. An open point must not be treated as clean coverage.
 
 ---
 
 ## Guidelines
 
-- **Always call `Write` for the Validation Report before finishing** (Phase 6) — the on-screen gap report is not the deliverable; the file on disk is. This is your last action, clean or not.
-- **Do not regenerate documents from scratch** — targeted revisions only
+- **Always call `Write` for the Validation Report before returning the structured verdict** (Phases 6 and 7), clean or not.
+- **Validate only** — the host owns document revisions and agent dispatch
 - **Be specific about gaps** — point to the exact section, claim, and what is missing
-- **Stop after 3 revision cycles** — if coverage is still incomplete, report remaining gaps and exit
+- **Perform one validation pass per invocation** — return remaining gaps to the host
 - **Out-of-scope items are also validated** — ensure they are not accidentally included in outputs
 - **Traceability is mandatory** — every Use Case ID in Requirements must appear in Tech-Spec