@dtlabs/ai-toolkit 0.13.0 → 0.14.0

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,219 @@
+'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())) 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.0",
   "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/skills/assess-codebase/SKILL.md

@@ -9,8 +9,7 @@ Orchestrates the full codebase assessment pipeline by invoking two sequential wo
 (`am-phase1`, `am-phase2`), handling the Findings Gate in the main loop between the phases,
 and recording the real token consumption at the end.
 
-Each workflow phase runs as a real subagent boundary, ensuring assessment agents are dispatched
-with accurate per-agent `usage` data and their declared `model:` frontmatter honoured.
+Run workflows through the deterministic Node host. Workflows are not agent types. Resolve the absolute Claude executable path using docs/task-executor-bootstrap.md.
 
 ---
 
@@ -25,16 +24,14 @@ found, or start at `ASSESS-001`. This prefix is used for all output files in thi
 
 Invoke the `am-phase1` workflow:
 
-```
-subagent_type: am-phase1
-prompt: <path> [--scope=<areas>] --prefix ASSESS-NNN [--force]
+```bash
+ai-toolkit workflow run am-phase1 --project . --claude-path "{ABSOLUTE_CLAUDE_EXE}" -- "<path>" [--scope=<areas>] --prefix ASSESS-NNN
 ```
 
 If no path was provided by the user, use `.` (current working directory).
 Always pass `--prefix ASSESS-NNN` with the prefix determined in Step 1.
 
-Wait for the workflow to complete. Capture its full result, including the `<usage>` block
-(format: `subagent_tokens: N`). Extract from the result:
+Wait for exit 0, then parse stdout JSON. A nonzero exit is a HARD STOP; do not present a successful Findings Gate. The host owns ledger transitions. Extract from the result:
 - `prefix` — confirmed assessment prefix
 - `output_dir` — path to `docs/assessments/ASSESS-NNN/`
 - `assessment_summaries` — list of `{ agent, output_file }` for each completed assessment
@@ -46,8 +43,7 @@ Wait for the workflow to complete. Capture its full result, including the `<usag
 - `token_estimate_path` — path to `{PREFIX}-Token-Estimate.md`
 - `errors` — any agent failures during phase 1
 
-If `errors` is non-empty, report them to the user before presenting the Findings Gate.
-Partial assessments are acceptable — present the Findings Gate with available data.
+If any worker fails, stop. Partial assessments must not be represented as a completed workflow.
 
 ---
 
@@ -112,9 +108,8 @@ Capture the flagged identifiers (as a comma-separated string, or "none").
 
 Invoke the `am-phase2` workflow:
 
-```
-subagent_type: am-phase2
-prompt: --prefix {prefix} --output-dir {output_dir} --flagged {flagged_ids} --ack "{acknowledgement_text}"
+```bash
+ai-toolkit workflow run am-phase2 --project . -- "--prefix" "{prefix}" --output-dir "{output_dir}" --flagged "{flagged_ids}" --ack "{acknowledgement_text}"
 ```
 
 Where `{flagged_ids}` is the comma-separated list of INT-NNN identifiers (or "none").
@@ -126,95 +121,6 @@ Wait for the workflow to complete. Extract from the result:
 
 ---
 
-## Step 5 — Complete Token Estimate file
-
-From the `<usage>` block of the am-phase1 result, read:
-- `subagent_tokens` — total tokens consumed by the am-phase1 workflow
-- `duration_ms` — wall-clock duration of am-phase1
-
-If the `<usage>` block is missing: log warning
-`"am-phase1 produced no <usage> block; orchestrator token data unavailable"`
-and set `actual_tokens = "N/A"`.
-
-Read `{token_estimate_path}`. Append the following in order:
-
-### 5a — Orchestrator row (for use in 5b only)
-
-Compute values:
-- Estimated tokens: 80,000 (baseline from estimation model)
-- Estimated cost: $0.4320 — `80,000 × $0.005400 / 1,000` using sonnet blended rate
-- Actual tokens: `subagent_tokens` from `<usage>` block; `"N/A"` if missing
-- Actual cost: `(actual_tokens / 1,000) × 0.005400` at 4 decimal places; `"N/A"` if unavailable
-
-### 5b — Actuals vs Estimate section
-
-Append a horizontal rule (`---`) followed by:
-
-```markdown
-## Actuals vs Estimate
-
-| Agent | Task/Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
-|-------|------------|-------|-------------|---------------|-------|---------------|-----------------|----------|
-| {agent} | {scope} | {model} | {est} | {actual} | {±delta} | {est_cost} | {actual_cost} | {Xmin Ys} |
-...
-| am-phase1 (orchestrator) | — | sonnet | 80,000 | {actual} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
-```
-
-Column rules:
-- **Delta**: `actual_tokens − est_tokens`; show as `+N` or `−N`. Show `"N/A"` if either missing.
-- **Duration**: convert `duration_ms` to `Xmin Ys` where available; use `"—"` where not.
-- Rows with `"N/A"` actual tokens are still shown but excluded from aggregate calculations.
-
-### 5c — Estimation accuracy by agent type (conditional)
-
-If 2+ distinct model tiers appear with non-N/A actuals, append:
-
-```markdown
-## Estimation accuracy by agent type
-
-| Model | Count | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
-|-------|-------|-----------------|-------------------|-----------|-------|
-| {model} | {N} | {avg_est} | {avg_actual} | {avg_delta} | {trend} |
-```
-
-- One row per model tier (e.g., `haiku`, `sonnet`)
-- Exclude N/A rows from averages
-- **Trend**: `"over-target"` if avg delta > +20% of avg est; `"under-target"` if < −20%; else `"on-target"`
-
-### 5d — Grand Total section
-
-Update the Grand Total section: replace `"partial — updated at pipeline end"` with Final values:
-
-```markdown
-## Grand Total (Final)
-
-| Metric | Estimated | Actual | Delta | Delta % |
-|--------|-----------|--------|-------|---------|
-| Total tokens (all agents) | {sum_est} | {sum_actual} | ±{delta} | {delta_pct} |
-| Total cost ($) | ${sum_est_cost} | ${sum_actual_cost} | ±${delta_cost} | {delta_cost_pct} |
-| Total wall-clock | — | {Xmin Ys} | — | — |
-```
-
-- **Delta %**: `(delta / estimated) × 100` at 1 decimal place; `"N/A"` if estimated is 0
-- Sum all agents' tokens and costs; exclude `"N/A"` rows from sums
-- Cost: 2 decimal places for totals; 4 decimal places for per-row costs
-- The "Remediation" section contains a static note — leave it as-is
-- Wall-clock: convert `duration_ms` from am-phase1 `<usage>` to minutes/seconds
-
----
-
-## Step 6 — Report to user
-
-After writing to the Token Estimate file, report:
-
-```
-Assessment pipeline complete.
-   Token estimate + actuals → {token_estimate_path}
-   Approvals                → {approvals_path}
-   Process log              → {output_dir}/{prefix}-process-log.txt
-
-{summary from am-phase2}
-```
+## Step 5 — Report results
 
-If the Token Estimate file does not exist (am-phase1 failed before writing it):
-note this in the report but do not halt — the skill has completed its work.
+Use the deterministic Token-Estimate and Effort-Estimate files returned by am-phase1, and the summary returned by am-phase2. Worker usage is in token_ledger; missing usage remains unavailable. Do not invent an orchestrator usage block or overwrite the host-generated metrics.