@dtlabs/ai-toolkit 0.1.6 → 0.2.0

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

@@ -0,0 +1,304 @@
+export const meta = {
+  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: 'Scan .claude/agents/ for assessment agents, 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'],
+}
+
+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(
+  `Scan .claude/agents/ and list all assessment agents.
+
+An assessment agent is a .md file whose name or description contains one of: "assessment", "audit", "analysis".
+Exclude orchestrators (files containing "manager" in their name).
+Exclude remediation-only agents (files containing "refactoring", "hardening", "decomposition" in their name UNLESS they also contain "assessment" or "audit").
+
+For each matching agent, read its frontmatter and extract:
+- name (from the name: field in frontmatter)
+- description (from the description: field)
+
+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',
+  }
+)
+const intTokens = budget.spent() - beforeInt
+tokenLedger.push({
+  agent:              'intervention-documentation-standard',
+  model:              'sonnet',
+  phase_delta_tokens: intTokens,
+  note:               'exact phase delta',
+})
+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/.claude/workflows/am-phase2.js

@@ -0,0 +1,166 @@
+export const meta = {
+  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,
+}

package/.claude/workflows/pm-phase1.js

@@ -0,0 +1,163 @@
+export const meta = {
+  name: 'pm-phase1',
+  description: 'Feature delivery phase 1: discovery → generate-requirements → generate-tech-spec → validate-feature-docs (revision loop) → Effort-Estimate stub. Returns gate1_payload.',
+  phases: [
+    { title: 'Discovery', detail: 'Read feature.md, check existing outputs' },
+    { title: 'Requirements', detail: 'Run generate-requirements' },
+    { title: 'Tech-Spec', detail: 'Run generate-tech-spec' },
+    { title: 'Validation', detail: 'Run validate-feature-docs (revision loop, max 3×)' },
+  ],
+}
+
+// ── Parse args ────────────────────────────────────────────────────────────────
+// args is the raw prompt string: "<path-to-feature.md> [--force]"
+const featurePath = args.split(/\s+/)[0]
+const force       = typeof args === 'string' && args.includes('--force')
+
+// ── Discovery ─────────────────────────────────────────────────────────────────
+phase('Discovery')
+
+const discoveryResult = await agent(
+  `You are a discovery agent for the feature delivery pipeline.
+
+Read the feature.md file at: ${featurePath}
+
+Extract:
+1. The feature PREFIX from the directory name (pattern [A-Z]+-[0-9]+, e.g. FTR-009)
+2. The feature directory path (parent of feature.md)
+3. Whether these files exist and are NOT stale vs feature.md (stale = older mtime):
+   - {PREFIX}-Requirements.md
+   - {PREFIX}-Tech-Spec.md
+   - {PREFIX}-Validation-Report.md
+
+Return a JSON object:
+{
+  "prefix": "FTR-009",
+  "feature_dir": "internal_docs/features/FTR-009-workflow-orchestrators",
+  "needs_requirements": true,
+  "needs_tech_spec": true,
+  "needs_validation": true,
+  "force": ${force}
+}
+
+If force=true, set all needs_* to true regardless of file state.
+If feature.md does not exist, return { "error": "feature.md not found: ${featurePath}" }.`,
+  {
+    label: 'discovery',
+    phase: 'Discovery',
+    schema: {
+      type: 'object',
+      properties: {
+        prefix:             { type: 'string' },
+        feature_dir:        { type: 'string' },
+        needs_requirements: { type: 'boolean' },
+        needs_tech_spec:    { type: 'boolean' },
+        needs_validation:   { type: 'boolean' },
+        force:              { type: 'boolean' },
+        error:              { type: 'string' },
+      },
+      required: ['prefix', 'feature_dir'],
+    },
+  }
+)
+
+if (discoveryResult.error) {
+  return { error: discoveryResult.error }
+}
+
+const { prefix, feature_dir } = discoveryResult
+
+log(`Prefix: ${prefix} | Dir: ${feature_dir}`)
+log(`needs_requirements=${discoveryResult.needs_requirements} needs_tech_spec=${discoveryResult.needs_tech_spec}`)
+
+// ── generate-requirements ─────────────────────────────────────────────────────
+phase('Requirements')
+
+const tokenLedger = []
+const errors      = []
+
+if (discoveryResult.needs_requirements) {
+  const beforeReq = budget.spent()
+  const reqResult = await agent(featurePath, { agentType: 'generate-requirements', label: 'generate-requirements', phase: 'Requirements' })
+  const reqTokens = budget.spent() - beforeReq
+  tokenLedger.push({ agent: 'generate-requirements', model: 'haiku', phase_delta_tokens: reqTokens })
+  log(`generate-requirements done — phase delta: ${reqTokens} tokens`)
+} else {
+  log('generate-requirements: fresh — skipped')
+}
+
+// ── generate-tech-spec ────────────────────────────────────────────────────────
+phase('Tech-Spec')
+
+if (discoveryResult.needs_tech_spec) {
+  const beforeSpec = budget.spent()
+  const specResult = await agent(featurePath, { agentType: 'generate-tech-spec', label: 'generate-tech-spec', phase: 'Tech-Spec' })
+  const specTokens = budget.spent() - beforeSpec
+  tokenLedger.push({ agent: 'generate-tech-spec', model: 'haiku', phase_delta_tokens: specTokens })
+  log(`generate-tech-spec done — phase delta: ${specTokens} tokens`)
+} else {
+  log('generate-tech-spec: fresh — skipped')
+}
+
+// ── validate-feature-docs (revision loop, max 3 cycles) ──────────────────────
+phase('Validation')
+
+let validationSummary = 'skipped'
+const MAX_CYCLES = 3
+
+for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
+  log(`validate-feature-docs cycle ${cycle}`)
+  const beforeVal = budget.spent()
+  const valResult = await agent(featurePath, { agentType: 'validate-feature-docs', label: `validate-feature-docs (cycle ${cycle})`, phase: 'Validation' })
+  const valTokens = budget.spent() - beforeVal
+  tokenLedger.push({ agent: `validate-feature-docs (cycle ${cycle})`, model: 'haiku', phase_delta_tokens: valTokens })
+
+  // valResult is the agent's text output — check for gap indicators
+  const resultText = typeof valResult === 'string' ? valResult : JSON.stringify(valResult)
+  const hasGaps    = resultText.includes('MISSING:') || resultText.toLowerCase().includes('gaps found')
+
+  if (!hasGaps) {
+    validationSummary = `0 gaps (clean on cycle ${cycle})`
+    log(`Validation clean on cycle ${cycle}`)
+    break
+  }
+
+  log(`Validation cycle ${cycle}: gaps found`)
+
+  if (cycle < MAX_CYCLES) {
+    // Re-run failing docs before next validation cycle
+    if (resultText.includes('Requirements')) {
+      await agent(featurePath, { agentType: 'generate-requirements', label: `generate-requirements (revision ${cycle})`, phase: 'Validation' })
+    }
+    if (resultText.includes('Tech-Spec')) {
+      await agent(featurePath, { agentType: 'generate-tech-spec', label: `generate-tech-spec (revision ${cycle})`, phase: 'Validation' })
+    }
+  } else {
+    validationSummary = 'gaps remain after 3 cycles'
+    errors.push('validate-feature-docs: gaps remain after 3 revision cycles')
+  }
+}
+
+// ── Build gate1_payload ───────────────────────────────────────────────────────
+const gate1Payload = {
+  prefix,
+  feature_dir,
+  feature_path: featurePath,
+  requirements: {
+    path:    `${feature_dir}/${prefix}-Requirements.md`,
+    summary: `${prefix}-Requirements.md — generated`,
+  },
+  tech_spec: {
+    path:    `${feature_dir}/${prefix}-Tech-Spec.md`,
+    summary: `${prefix}-Tech-Spec.md — generated`,
+  },
+  validation: {
+    path:    `${feature_dir}/${prefix}-Validation-Report.md`,
+    summary: validationSummary,
+  },
+  token_ledger: tokenLedger,
+  errors,
+}
+
+log(`pm-phase1 complete — gate1_payload ready`)
+return gate1Payload