@dtlabs/ai-toolkit 0.13.0 → 0.14.1

package/src/claude/workflows/am-phase1.js

@@ -1,301 +1,50 @@
 export const meta = {
+  controlPlaneVersion: 1,
   name: 'am-phase1',
-  description: 'Assessment pipeline phase 1: discover assessment agents → scope filter → parallel assessment → intervention-documentation-standard → Token-Estimate → Effort-Estimate → findings_gate_payload.',
-  phases: [
-    { title: 'Discovery',      detail: 'Run ai-toolkit list-assets --category agents --format json, apply scope filter' },
-    { title: 'Assessment',     detail: 'Dispatch all assessment agents in parallel' },
-    { title: 'Interventions',  detail: 'Run intervention-documentation-standard on all findings' },
-    { title: 'Estimates',      detail: 'Write Token-Estimate and Effort-Estimate files' },
-  ],
-}
-
-// args: "<target_path> [--scope=area1,area2] --prefix ASSESS-NNN [--force]"
-const argStr    = typeof args === 'string' ? args : '.'
-const parts     = argStr.trim().split(/\s+/)
-
-let targetPath  = '.'
-let scope       = null
-let prefix      = null
-let force       = false
-
-for (const part of parts) {
-  if (part.startsWith('--scope='))   { scope  = part.slice('--scope='.length).split(',').map(s => s.trim()) }
-  else if (part === '--force')        { force  = true }
-  else if (part === '--prefix')       { /* next part is value */ }
-  else if (prefix === null && parts[parts.indexOf(part) - 1] === '--prefix') { prefix = part }
-  else if (!part.startsWith('--'))   { targetPath = part }
-}
-
-// Re-parse prefix properly
-const prefixMatch = argStr.match(/--prefix\s+(\S+)/)
-if (prefixMatch) prefix = prefixMatch[1]
-
-if (!prefix) prefix = 'ASSESS-001'
-
-const outputDir = `docs/assessments/${prefix}`
-
-// ── Discovery ─────────────────────────────────────────────────────────────────
-phase('Discovery')
-
-const DISCOVERY_SCHEMA = {
-  type: 'object',
-  properties: {
-    assessment_agents: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          name:        { type: 'string' },
-          description: { type: 'string' },
-        },
-        required: ['name'],
-      },
-    },
-  },
-  required: ['assessment_agents'],
+  description: 'Read-only assessment using verified assessors and deterministic artifact recording.',
+  phases: [{ title: 'Discovery' }, { title: 'Assessment' }, { title: 'Interventions' }, { title: 'Estimates' }],
 }
 
+const c = control
+const option = key => { const i = args.indexOf(key); return i < 0 ? null : args[i + 1] }
+const prefix = option('--prefix')
+if (!/^ASSESS-\d+$/.test(prefix || '')) throw new Error('Explicit ASSESS-NNN prefix required')
+const targetPath = args[0] && !args[0].startsWith('--') ? args[0] : '.'
+const scopeArg = args.find(a => a.startsWith('--scope='))
+const scope = scopeArg ? scopeArg.slice(8).split(',') : ['quality', 'architecture', 'concurrency']
 const SCOPE_AGENT_MAP = {
-  architecture:   ['layered-architecture-assessment'],
-  security:       ['security-hardening'],
-  quality:        ['generic-software-assessment'],
-  concurrency:    ['concurrency-safety-assessment'],
-  devops:         [],
-  'domain-model': ['domain-model-refactoring'],
-  dependencies:   ['dependency-supply-chain-security'],
-}
-
-const discovery = await agent(
-  `Run this command and parse its output:\n` +
-  `ai-toolkit list-assets --category agents --format json\n\n` +
-  `The command outputs a JSON array of installed agent file paths (e.g. [".claude/agents/foo.md", ...]).\n` +
-  `For each path in the array, read the file and extract the YAML frontmatter fields: name, description.\n\n` +
-  `An assessment agent is one whose file name or description contains one of: "assessment", "audit", "analysis".\n` +
-  `Exclude orchestrators (files containing "manager" in their name).\n` +
-  `Exclude remediation-only agents (files containing "refactoring", "hardening", "decomposition" in their name UNLESS they also contain "assessment" or "audit").\n\n` +
-  `Return { "assessment_agents": [ { "name": "...", "description": "..." }, ... ] }`,
-  {
-    label:  'discover-assessment-agents',
-    phase:  'Discovery',
-    schema: DISCOVERY_SCHEMA,
-  }
-)
-
-let assessmentAgents = discovery.assessment_agents || []
-
-// Apply scope filter
-if (scope && scope.length > 0) {
-  const allowed = new Set(scope.flatMap(s => SCOPE_AGENT_MAP[s] || []))
-  assessmentAgents = assessmentAgents.filter(a => allowed.has(a.name))
-  log(`Scope filter applied (${scope.join(', ')}): ${assessmentAgents.length} agents selected`)
-} else {
-  log(`No scope filter: ${assessmentAgents.length} assessment agents discovered`)
-}
-
-if (assessmentAgents.length === 0) {
-  log('WARNING: No assessment agents to run — proceeding with empty assessment')
-}
-
-// ── Assessment (parallel) ─────────────────────────────────────────────────────
-phase('Assessment')
-
-log(`Dispatching ${assessmentAgents.length} assessment agents in parallel`)
-
-const tokenLedger   = []
-const beforeAssess  = budget.spent()
-
-const assessmentResults = await parallel(
-  assessmentAgents.map(a => () =>
-    agent(
-      `${targetPath} --prefix ${prefix} --output-dir ${outputDir}`,
-      {
-        agentType: a.name,
-        label:     a.name,
-        phase:     'Assessment',
-      }
-    ).then(result => ({ agent: a.name, success: true,  result }))
-     .catch(err   => ({ agent: a.name, success: false, error: String(err) }))
-  )
-)
-
-const assessTokens = budget.spent() - beforeAssess
-log(`Assessment phase complete — ${assessmentResults.filter(r => r?.success).length}/${assessmentAgents.length} succeeded | total phase delta: ${assessTokens} tokens`)
-
-// Proportional token distribution across agents
-const perAgentTokens = assessmentAgents.length > 0
-  ? Math.round(assessTokens / assessmentAgents.length)
-  : 0
-
-for (const r of assessmentResults.filter(Boolean)) {
-  tokenLedger.push({
-    agent:              r.agent,
-    model:              'sonnet',
-    phase_delta_tokens: perAgentTokens,
-    note:               'proportional distribution of assessment phase total',
-    success:            r.success,
-    error:              r.error || null,
-  })
-}
-
-const failedAgents    = assessmentResults.filter(r => r && !r.success)
-const completedAgents = assessmentResults.filter(r => r &&  r.success)
-
-// ── Interventions ─────────────────────────────────────────────────────────────
-phase('Interventions')
-
-log('Running intervention-documentation-standard')
-
-const beforeInt = budget.spent()
-await agent(
-  `--prefix ${prefix} --output-dir ${outputDir} --target ${targetPath}`,
-  {
-    agentType: 'intervention-documentation-standard',
-    label:     'intervention-documentation-standard',
-    phase:     'Interventions',
+  architecture: 'gaia.agent.assessment.layered-architecture',
+  concurrency: 'gaia.agent.assessment.concurrency',
+  quality: 'gaia.agent.assessment.generic',
+  security: 'gaia.agent.assessment.generic',
+  devops: 'gaia.agent.assessment.generic',
+  'domain-model': 'gaia.agent.assessment.generic',
+  dependencies: 'gaia.agent.assessment.generic',
+}
+for (const area of scope) if (!Object.hasOwn(SCOPE_AGENT_MAP, area)) throw new Error('Unknown assessment scope: ' + area)
+const outputDir = `docs/assessments/${prefix}`
+return c.run(meta.name, outputDir, prefix, async () => {
+  const groups = new Map()
+  for (const area of scope) {
+    const id = SCOPE_AGENT_MAP[area]
+    groups.set(id, [...(groups.get(id) || []), area])
   }
-)
-const intTokens = budget.spent() - beforeInt
-tokenLedger.push({
-  agent:              'intervention-documentation-standard',
-  model:              'sonnet',
-  phase_delta_tokens: intTokens,
-  note:               'exact phase delta',
+  const assessmentResults = await c.parallel([...groups].map(([id, areas]) => async () => {
+    const result = await c.worker(id,
+      `${targetPath} --prefix ${prefix} --output-dir ${outputDir}\n` +
+      `Read-only assessment. Explicit scope: ${areas.join(', ')}. Inspect risks, evidence, severity and recommendations for EACH listed scope. ` +
+      'For security inspect trust boundaries and authorization; devops: build/deploy/observability; domain-model: invariants and ownership; dependencies: versions, provenance and supply-chain risks. ' +
+      'Do not remediate code or dispatch remediation agents. Write your assessment report in the output directory.')
+    const suffix = { 'gaia.agent.assessment.generic': 'Generic', 'gaia.agent.assessment.layered-architecture': 'Layer', 'gaia.agent.assessment.concurrency': 'Concurrency' }[id]
+    const output_file = `${outputDir}/${prefix}-${suffix}-Assessment.md`
+    if (!c.read(output_file).trim()) throw new Error('Assessment report empty: ' + output_file)
+    return { agent: id, scopes: areas, result, output_file }
+  }))
+  await c.worker('gaia.agent.assessment.intervention-documentation',
+    `--prefix ${prefix} --output-dir ${outputDir} --target ${targetPath}\nUse only the reports from these assessors: ${[...groups.keys()].join(', ')}.\n` +
+    assessmentResults.map(r => `${r.agent}: ${typeof r.result === 'string' ? r.result : JSON.stringify(r.result)}`).join('\n'))
+  const metrics = c.assessmentEstimates(outputDir, prefix)
+  return { prefix, output_dir: outputDir, target_path: targetPath,
+    assessment_summaries: assessmentResults.map(({ agent, scopes, output_file }) => ({ agent, scopes, output_file })),
+    ...metrics, token_ledger: c.tokenLedger, errors: [] }
 })
-log(`intervention-documentation-standard done — phase delta: ${intTokens} tokens`)
-
-// ── Estimates ─────────────────────────────────────────────────────────────────
-phase('Estimates')
-
-const ESTIMATES_SCHEMA = {
-  type: 'object',
-  properties: {
-    severity_counts: {
-      type: 'object',
-      properties: {
-        CRITICAL: { type: 'number' },
-        HIGH:     { type: 'number' },
-        MEDIUM:   { type: 'number' },
-        LOW:      { type: 'number' },
-      },
-    },
-    total_interventions:      { type: 'number' },
-    interventions_index_path: { type: 'string' },
-    token_estimate_path:      { type: 'string' },
-    effort_estimate_path:     { type: 'string' },
-    remediation_hours_est:    { type: 'number' },
-  },
-  required: ['severity_counts', 'total_interventions'],
-}
-
-const totalPhaseTokens = tokenLedger.reduce((s, e) => s + (e.phase_delta_tokens || 0), 0)
-
-const estimatesResult = await agent(
-  `You are the estimates recorder for the assessment pipeline.
-
-Prefix: ${prefix}
-Output directory: ${outputDir}
-Assessment agents that ran: ${assessmentAgents.map(a => a.name).join(', ') || 'none'}
-Failed agents: ${failedAgents.map(r => r.agent).join(', ') || 'none'}
-
-Token ledger (phase-level measurements):
-${JSON.stringify(tokenLedger, null, 2)}
-
-TASK 1 — Read ${prefix}-Interventions-Index.md from ${outputDir}.
-Count rows by Criticality column: CRITICAL, HIGH, MEDIUM, LOW.
-Compute remediation_hours_est = CRITICAL×8 + HIGH×4 + MEDIUM×2 + LOW×1.
-
-TASK 2 — Write Token-Estimate file at ${outputDir}/${prefix}-Token-Estimate.md.
-
-Use this template (fill in all values):
-
-# Token Estimate — ${prefix} — Assessment Pipeline
-
-> Phase totals are exact measurements from budget tracking.
-> Per-agent values within the assessment phase are proportional distributions of the phase total.
-> Pricing model: docs/pricing.md (80% input / 20% output split).
-> ⚠️ Per-agent values marked (proportional) are estimated distributions, not exact measurements.
-
-## Estimation model
-
-| Parameter | Value |
-|-----------|-------|
-| Avg chars per token | 4 |
-| Sonnet system prompt | ~3,000 tokens |
-| Base overhead per call | ~5,000 tokens |
-| Input/output split | 80% / 20% |
-
-## Assessment agents (Phase 1)
-
-| Agent | Model | Phase delta tokens | Note | Status |
-|-------|-------|--------------------|------|--------|
-{one row per agent from token ledger — use phase_delta_tokens and note fields}
-
-## Phase subtotals
-
-| Phase | Tokens (exact) |
-|-------|---------------|
-| Assessment agents (parallel) | {sum of assessment agent phase_delta_tokens} |
-| intervention-documentation-standard | {its phase_delta_tokens} |
-| Total am-phase1 | ${totalPhaseTokens} |
-
-## Grand total
-
-> Updated at pipeline end by assess-codebase skill.
-
-| Metric | Value |
-|--------|-------|
-| Total tokens (am-phase1) | ${totalPhaseTokens} (exact) |
-
-TASK 3 — Write Effort-Estimate file at ${outputDir}/${prefix}-Effort-Estimate.md.
-
-Use this template:
-
-# Effort Estimate — ${prefix} — Assessment Pipeline
-
-> Wall-clock effort tracking for the assessment pipeline.
-> Remediation effort: CRITICAL=8h, HIGH=4h, MEDIUM=2h, LOW=1h (human hours, sequential).
-
-## Assessment phase
-
-| Agent | Status |
-|-------|--------|
-{one row per assessment agent}
-| intervention-documentation-standard | complete |
-
-## Remediation effort estimate
-
-| Severity | Count | Rate | Subtotal |
-|----------|-------|------|---------|
-| CRITICAL | {count} | 8h | {subtotal}h |
-| HIGH | {count} | 4h | {subtotal}h |
-| MEDIUM | {count} | 2h | {subtotal}h |
-| LOW | {count} | 1h | {subtotal}h |
-| **Total** | **{total}** | — | **{total_hours}h** |
-
-Human sequential total: {total_hours}h
-
-Return the structured metrics.`,
-  {
-    label:  'write-estimates',
-    phase:  'Estimates',
-    schema: ESTIMATES_SCHEMA,
-  }
-)
-
-log(`Estimates written — ${estimatesResult.total_interventions} interventions: CRITICAL=${estimatesResult.severity_counts?.CRITICAL} HIGH=${estimatesResult.severity_counts?.HIGH} MEDIUM=${estimatesResult.severity_counts?.MEDIUM} LOW=${estimatesResult.severity_counts?.LOW}`)
-log(`Remediation estimate: ${estimatesResult.remediation_hours_est}h human sequential`)
-
-return {
-  prefix,
-  output_dir:              outputDir,
-  target_path:             targetPath,
-  assessment_summaries:    completedAgents.map(r => ({ agent: r.agent })),
-  interventions_index_path: estimatesResult.interventions_index_path || `${outputDir}/${prefix}-Interventions-Index.md`,
-  severity_counts:         estimatesResult.severity_counts  || { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 },
-  total_interventions:     estimatesResult.total_interventions || 0,
-  remediation_hours_est:   estimatesResult.remediation_hours_est || 0,
-  effort_estimate_path:    estimatesResult.effort_estimate_path || `${outputDir}/${prefix}-Effort-Estimate.md`,
-  token_estimate_path:     estimatesResult.token_estimate_path  || `${outputDir}/${prefix}-Token-Estimate.md`,
-  token_ledger:            tokenLedger,
-  errors:                  failedAgents.map(r => ({ agent: r.agent, error: r.error })),
-}

package/src/claude/workflows/am-phase2.js

@@ -1,166 +1,12 @@
 export const meta = {
+  controlPlaneVersion: 1,
   name: 'am-phase2',
-  description: 'Assessment pipeline phase 2: write Approvals file → update Assessment Registry → return summary. Runs after Findings Gate is completed in the main loop.',
-  phases: [
-    { title: 'Approvals', detail: 'Write {PREFIX}-Approvals.md with gate acknowledgement and flagged interventions' },
-    { title: 'Registry',  detail: 'Append row to docs/assessments/registry.md' },
-    { title: 'Summary',   detail: 'Build and return run summary' },
-  ],
-}
-
-// args: "--prefix ASSESS-NNN --output-dir <path> --flagged INT-001,INT-003 --ack \"text\""
-const argStr = typeof args === 'string' ? args : ''
-
-const prefixMatch    = argStr.match(/--prefix\s+(\S+)/)
-const outputDirMatch = argStr.match(/--output-dir\s+(\S+)/)
-const flaggedMatch   = argStr.match(/--flagged\s+([^\s"]+)/)
-const ackMatch       = argStr.match(/--ack\s+"([^"]*)"/)
-
-const prefix    = prefixMatch    ? prefixMatch[1]    : 'ASSESS-001'
-const outputDir = outputDirMatch ? outputDirMatch[1] : `docs/assessments/${prefix}`
-const flaggedRaw = flaggedMatch  ? flaggedMatch[1]   : 'none'
-const ackText    = ackMatch      ? ackMatch[1]        : 'Acknowledged'
-
-const flaggedIds = flaggedRaw.toLowerCase() === 'none'
-  ? []
-  : flaggedRaw.split(',').map(s => s.trim().toUpperCase())
-
-// ── Approvals ─────────────────────────────────────────────────────────────────
-phase('Approvals')
-
-const APPROVALS_SCHEMA = {
-  type: 'object',
-  properties: {
-    approvals_path: { type: 'string' },
-    written:        { type: 'boolean' },
-  },
-  required: ['approvals_path', 'written'],
-}
-
-log(`Writing Approvals file for ${prefix} — flagged: ${flaggedIds.join(', ') || 'none'}`)
-
-const approvalsResult = await agent(
-  `Write the Approvals file for assessment ${prefix}.
-
-Output path: ${outputDir}/${prefix}-Approvals.md
-
-Read the Interventions Index at: ${outputDir}/${prefix}-Interventions-Index.md
-Extract all INT-NNN identifiers and their titles.
-
-Flagged interventions (to mark as Yes): ${flaggedIds.join(', ') || 'none'}
-Acknowledgement text: "${ackText}"
-Today's date: use the current date in YYYY-MM-DD format.
-
-Write the file with this exact structure:
-
-# Assessment Approvals — ${prefix}
-
-## Findings Gate Acknowledgement
-
-| Field | Value |
-|-------|-------|
-| Acknowledged by | Toolkit user |
-| Date | {today} |
-| Acknowledgement | ${ackText} |
-
-## Interventions Flagged for Feature Delivery
-
-| Intervention | Flagged | Date | Notes |
-|---|---|---|---|
-{one row per intervention: | INT-NNN — {title} | Yes/No | {today} | — or "Not selected" |}
-
-Rules:
-- Mark "Yes" for interventions whose ID is in: ${flaggedIds.join(', ') || '(none)'}
-- Mark "No" for all others, Notes = "Not selected"
-- "Flagged" column values must be exactly "Yes" or "No" (case-sensitive)
-
-After writing, verify the file exists and is non-empty.
-Return { "approvals_path": "<full path>", "written": true }.`,
-  {
-    label:  'write-approvals',
-    phase:  'Approvals',
-    schema: APPROVALS_SCHEMA,
-  }
-)
-
-log(`Approvals written: ${approvalsResult.approvals_path}`)
-
-// ── Registry ──────────────────────────────────────────────────────────────────
-phase('Registry')
-
-const REGISTRY_SCHEMA = {
-  type: 'object',
-  properties: {
-    registry_result: { type: 'string' },
-  },
-  required: ['registry_result'],
-}
-
-log(`Updating Assessment Registry`)
-
-const registryResult = await agent(
-  `Update the Assessment Registry at: docs/assessments/registry.md
-
-Prefix: ${prefix}
-Output directory: ${outputDir}
-
-STEP 1 — Read severity counts from ${outputDir}/${prefix}-Interventions-Index.md.
-Count rows by Criticality column: CRITICAL, HIGH, MEDIUM, LOW, compute total.
-
-STEP 2 — Count flagged interventions from ${outputDir}/${prefix}-Approvals.md.
-Find the "## Interventions Flagged for Feature Delivery" section.
-Count rows where the Flagged column value is exactly "Yes" (case-sensitive).
-
-STEP 3 — Build the registry row:
-| {today-YYYY-MM-DD} | [${prefix}](${prefix}/) | {total} | {CRITICAL} | {HIGH} | {MEDIUM} | {LOW} | {flagged_count} |
-
-STEP 4 — Write to docs/assessments/registry.md:
-- If the file does not exist: create it with header + the new row:
-  # Assessment Registry
-  | Date | Prefix | Total | CRITICAL | HIGH | MEDIUM | LOW | Flagged |
-  |------|--------|-------|----------|------|--------|-----|---------|
-  {row}
-- If the file exists: read it, strip trailing whitespace, append the new row, write back.
-
-STEP 5 — Verify the file is readable after writing.
-
-Return { "registry_result": "docs/assessments/registry.md [created]" }
-  or    { "registry_result": "docs/assessments/registry.md [updated — row N appended]" }
-  or    { "registry_result": "docs/assessments/registry.md [ERROR — {reason}]" }`,
-  {
-    label:  'update-registry',
-    phase:  'Registry',
-    schema: REGISTRY_SCHEMA,
-  }
-)
-
-log(`Registry: ${registryResult.registry_result}`)
-
-// ── Summary ───────────────────────────────────────────────────────────────────
-phase('Summary')
-
-const summaryText = [
-  `Assessment Manager — Run Summary`,
-  `─────────────────────────────────────────────────────`,
-  `Target: ${argStr.split('--')[0].trim() || '.'}  |  Prefix: ${prefix}`,
-  `─────────────────────────────────────────────────────`,
-  `Approvals:           ${approvalsResult.approvals_path}`,
-  `Registry:            ${registryResult.registry_result}`,
-  `Effort Estimate:     ${outputDir}/${prefix}-Effort-Estimate.md`,
-  `Token Estimate:      ${outputDir}/${prefix}-Token-Estimate.md`,
-  `Process log:         ${outputDir}/${prefix}-process-log.txt`,
-  `─────────────────────────────────────────────────────`,
-  `Flagged interventions (${flaggedIds.length}): ${flaggedIds.join(', ') || 'none'}`,
-  `Flagged interventions can be actioned via /define-feature`,
-  `referencing the INT-NNN document.`,
-  `─────────────────────────────────────────────────────`,
-].join('\n')
-
-log('am-phase2 complete')
-
-return {
-  approvals_path:   approvalsResult.approvals_path,
-  registry_updated: registryResult.registry_result,
-  flagged_count:    flaggedIds.length,
-  summary:          summaryText,
-}
+  description: 'Record explicit Findings Gate acknowledgement and registry deterministically.',
+  phases: [{ title: 'Approvals' }, { title: 'Registry' }],
+}
+const c = control
+const option = key => { const i = args.indexOf(key); return i < 0 ? null : args[i + 1] }
+const prefix = option('--prefix'), ack = option('--ack'), flagged = option('--flagged')
+if (!/^ASSESS-\d+$/.test(prefix || '') || !ack?.trim() || flagged == null) throw new Error('Explicit prefix, acknowledgement and flagged selection required')
+const outputDir = option('--output-dir') || `docs/assessments/${prefix}`
+return c.run(meta.name, outputDir, prefix, async () => c.recordAssessmentApproval(outputDir, prefix, ack, flagged))