@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/orchestrators/team.js

@@ -0,0 +1,244 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { dispatch } from '../agents/dispatch.js';
+
+const DEFAULT_WORKERS = ['planner', 'research', 'product', 'security', 'test'];
+
+const WORKER_SPECS = {
+  planner: {
+    agent: 'planner',
+    stage: 'plan',
+    owner: 'planning',
+    purpose: 'implementation shape, acceptance criteria, and scope boundaries',
+  },
+  research: {
+    agent: 'research',
+    stage: 'ideate',
+    owner: 'research',
+    purpose: 'external patterns, prior art, and uncertainty reduction',
+  },
+  product: {
+    agent: 'architect',
+    stage: 'plan',
+    owner: 'product',
+    purpose: 'product tradeoffs, scope pressure, and user-facing acceptance',
+  },
+  design: {
+    agent: 'architect',
+    stage: 'plan',
+    owner: 'design',
+    purpose: 'interaction structure, UI states, and design constraints',
+  },
+  security: {
+    agent: 'security-reviewer',
+    stage: 'self-review',
+    owner: 'security',
+    purpose: 'security-sensitive assumptions, gate triggers, and abuse cases',
+  },
+  test: {
+    agent: 'test-engineer',
+    stage: 'plan',
+    owner: 'testing',
+    purpose: 'test plan, regression risks, and evidence required before work',
+  },
+  codex: {
+    agent: 'codex-reviewer',
+    stage: 'codex-review',
+    owner: 'codex',
+    purpose: 'independent review angle before any mutation phase',
+  },
+};
+
+export function parseWorkers(value) {
+  const raw = value ? String(value).split(',') : DEFAULT_WORKERS;
+  const workers = raw.map(w => w.trim()).filter(Boolean);
+  const unknown = workers.filter(w => !WORKER_SPECS[w]);
+  if (unknown.length) {
+    throw new Error(`unknown team worker: ${unknown.join(', ')}. available: ${Object.keys(WORKER_SPECS).join(', ')}`);
+  }
+  return [...new Set(workers)];
+}
+
+export async function teamCycle(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  const sessionId = opts.sessionId || `team-${Date.now()}`;
+  const sessionDir = path.join(projectRoot, '.harness', 'state', 'sessions', sessionId);
+  const handoffDir = path.join(sessionDir, 'handoffs');
+  fs.mkdirSync(handoffDir, { recursive: true });
+
+  const workers = parseWorkers(opts.workers);
+  const dispatcher = opts.dispatcher || dispatch;
+  const live = !!opts.live;
+  const handoffs = [];
+  const tasks = workers.map((worker, index) => createTask(worker, index));
+
+  writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+
+  for (const task of tasks) {
+    task.status = 'running';
+    task.started_at = new Date().toISOString();
+    writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+
+    try {
+      const handoff = await dispatcher({
+        agent: task.agent,
+        stage: task.stage,
+        task: opts.task,
+        live,
+        harnessRoot,
+        projectRoot,
+        sessionDir,
+        sessionId,
+        context: {
+          priorHandoffs: handoffs.slice(-3),
+          teamPurpose: task.purpose,
+          readOnly: true,
+        },
+        executionMode: 'read-only',
+        sandboxOverride: 'read-only',
+      });
+
+      handoff.team_stage = `team-${task.worker}`;
+      removeUndefined(handoff);
+      assertValidHandoff(harnessRoot, handoff);
+      handoffs.push(handoff);
+      writeHandoff(handoffDir, handoff, handoffs.length);
+
+      task.status = 'done';
+      task.completed_at = new Date().toISOString();
+      task.handoff = path.relative(sessionDir, handoffJsonPath(handoffDir, handoff, handoffs.length)).replace(/\\/g, '/');
+      task.verdict = handoff.verdict || null;
+    } catch (e) {
+      task.status = 'failed';
+      task.completed_at = new Date().toISOString();
+      task.error = e.message || String(e);
+      writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+      throw new Error(`team worker ${task.worker} failed: ${task.error}`);
+    }
+
+    writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+  }
+
+  const result = {
+    sessionId,
+    sessionDir,
+    workers,
+    tasks,
+    handoffs,
+    recommendedNextStep: recommendedNextStep(tasks, handoffs),
+  };
+  writeSummary(sessionDir, result, opts.task);
+  return result;
+}
+
+function createTask(worker, index) {
+  const spec = WORKER_SPECS[worker];
+  return {
+    id: `team-${worker}`,
+    worker,
+    owner: spec.owner,
+    agent: spec.agent,
+    stage: spec.stage,
+    purpose: spec.purpose,
+    status: 'pending',
+    order: index + 1,
+    mutation: 'read-only',
+  };
+}
+
+function recommendedNextStep(tasks, handoffs) {
+  if (tasks.some(t => t.status === 'failed')) return 'fix-team-failure';
+  if (handoffs.some(h => h.verdict === 'block')) return 'human-gate-or-replan';
+  if (handoffs.some(h => h.verdict === 'approve_with_fixes')) return 'plan-or-work-after-fixes';
+  return 'plan-or-work-with-single-executor';
+}
+
+function writeTeamState(sessionDir, sessionId, task, tasks, handoffs) {
+  fs.writeFileSync(path.join(sessionDir, 'team.json'), JSON.stringify({
+    sessionId,
+    task,
+    mode: 'read-only',
+    updated_at: new Date().toISOString(),
+    invariants: [
+      'Multi-worker phases are read-only by default.',
+      'Only one executor may mutate project files in a later work cycle.',
+      'Codex verification and human gate policy still apply after team handoffs.',
+    ],
+    tasks,
+    handoffs: handoffs.map(h => ({
+      team_stage: h.team_stage,
+      agent: h.agent,
+      stage: h.stage,
+      verdict: h.verdict || null,
+      files: h.files || [],
+    })),
+  }, null, 2));
+}
+
+function writeSummary(sessionDir, result, task) {
+  fs.writeFileSync(path.join(sessionDir, 'team-summary.json'), JSON.stringify({
+    sessionId: result.sessionId,
+    task,
+    mode: 'read-only',
+    workers: result.workers,
+    task_statuses: result.tasks.map(t => ({ worker: t.worker, status: t.status })),
+    handoff_count: result.handoffs.length,
+    recommended_next_step: result.recommendedNextStep,
+  }, null, 2));
+}
+
+function writeHandoff(handoffDir, h, index) {
+  const base = handoffBase(h, index);
+  fs.writeFileSync(handoffJsonPath(handoffDir, h, index), JSON.stringify(h, null, 2));
+  fs.writeFileSync(path.join(handoffDir, `${base}.md`), renderFiveFieldHandoff(h));
+}
+
+function handoffJsonPath(handoffDir, h, index) {
+  return path.join(handoffDir, `${handoffBase(h, index)}.json`);
+}
+
+function handoffBase(h, index) {
+  return `${String(index).padStart(2, '0')}-${h.team_stage}`;
+}
+
+function renderFiveFieldHandoff(h) {
+  return [
+    `# Handoff: ${h.team_stage}`,
+    '',
+    `Decided: ${h.decided || ''}`,
+    `Rejected: ${h.rejected || ''}`,
+    `Risks: ${h.risks || ''}`,
+    `Files: ${(h.files || []).join(', ')}`,
+    `Remaining: ${h.remaining || ''}`,
+    h.verdict ? `Verdict: ${h.verdict}` : '',
+    '',
+  ].filter(Boolean).join('\n');
+}
+
+function removeUndefined(obj) {
+  for (const [k, v] of Object.entries(obj)) {
+    if (v === undefined) delete obj[k];
+  }
+}
+
+function assertValidHandoff(root, handoff) {
+  const schemaPath = path.join(root, 'schemas', 'handoff.schema.json');
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  if (!validate(handoff)) {
+    const detail = (validate.errors || [])
+      .map(e => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(`team handoff schema validation failed: ${detail}`);
+  }
+}
+
+export {
+  WORKER_SPECS,
+  DEFAULT_WORKERS,
+};

package/scripts/orchestrators/verify.js

@@ -0,0 +1,306 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { dispatch } from '../agents/dispatch.js';
+import { ensureAcceptanceCriteria } from '../lib/acceptance-criteria.js';
+import { classifyRisk, gateReasonFromFindings } from '../lib/risk-classifier.js';
+import { acceptanceCoverage, acceptanceCoverageWarnings, evidenceFieldWarnings, profilePolicy } from '../lib/profile-policy.js';
+
+const STAGE_INDEX = { 'codex-review': '05', 'codex-challenge': '06' };
+
+export async function verifyCycle(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  if (!opts.sessionId) throw new Error('verify requires --session <id> from a prior work cycle');
+
+  const sessionId = opts.sessionId;
+  const sessionDir = path.join(projectRoot, '.harness', 'state', 'sessions', sessionId);
+  const handoffDir = path.join(sessionDir, 'handoffs');
+
+  const priorHandoffs = readPriorHandoffs(handoffDir);
+  const latestImplement = latestStageHandoff(priorHandoffs, 'implement');
+  if (!latestImplement) {
+    throw new Error('verify requires an implement handoff. Run harness work first, using the same --session.');
+  }
+  fs.mkdirSync(handoffDir, { recursive: true });
+
+  const prd = readJsonIfExists(path.join(sessionDir, 'prd.json'));
+  const acceptance = ensureAcceptanceCriteria({ sessionDir, task: opts.task });
+  const policy = profilePolicy(opts.profile || readSessionProfile(sessionDir));
+  const diff = readDiffForHandoff(sessionDir, latestImplement);
+  const dispatcher = opts.dispatcher || dispatch;
+  const live = !!opts.live;
+  const classification = classifyRisk({ task: opts.task, files: latestImplement.files || [] });
+  const secureActive = !!opts.secure || classification.requiresCodexChallenge;
+
+  const context = {
+    round: nextRound(priorHandoffs, 'codex-review'),
+    profile: policy.profile,
+    qualityChecklist: policy.checklist,
+    evidencePolicy: {
+      evidenceWarningRequired: policy.evidenceWarningRequired,
+      acceptanceCoverageWarning: policy.acceptanceCoverageWarning,
+      strictQuality: Boolean(opts.strictQuality && policy.strictQualitySupported),
+    },
+    prd,
+    acceptanceCriteria: acceptance.criteria,
+    priorHandoffs: priorHandoffs.slice(-6),
+    diff,
+    verifyOnly: true,
+    riskClassification: classification,
+  };
+
+  const h5 = await dispatcher({
+    agent: 'codex-reviewer',
+    stage: 'codex-review',
+    task: opts.task,
+    live,
+    harnessRoot,
+    projectRoot,
+    sessionDir,
+    sessionId,
+    context,
+  });
+  h5.round = context.round;
+  h5.session_id = sessionId;
+  if (policy.profile) h5.profile = policy.profile;
+  assertValidHandoff(harnessRoot, h5);
+  writeHandoff(handoffDir, h5);
+
+  const handoffs = [...priorHandoffs, h5];
+  let h6 = null;
+  if (secureActive) {
+    h6 = await dispatcher({
+      agent: 'codex-challenger',
+      stage: 'codex-challenge',
+      task: opts.task,
+      live,
+      harnessRoot,
+      projectRoot,
+      sessionDir,
+      sessionId,
+      context: {
+        ...context,
+        round: nextRound(handoffs, 'codex-challenge'),
+        priorHandoffs: handoffs.slice(-6),
+      },
+    });
+    h6.round = nextRound(handoffs, 'codex-challenge');
+    h6.session_id = sessionId;
+    if (policy.profile) h6.profile = policy.profile;
+    assertValidHandoff(harnessRoot, h6);
+    writeHandoff(handoffDir, h6);
+    handoffs.push(h6);
+  }
+
+  const gateReason = gateReasonFromFindings([h5, h6].filter(Boolean)) ||
+    (classification.requiresHumanGate ? `risk policy requires human gate (${classification.tags.join(',') || classification.risk})` : null);
+  if (gateReason) writeHumanGate(sessionDir, gateReason);
+  const verificationHandoffs = [h5, h6].filter(Boolean);
+  const coverage = acceptanceCoverage(acceptance.criteria, verificationHandoffs, policy.profile);
+  const qualityWarnings = [
+    ...evidenceFieldWarnings(verificationHandoffs, policy.profile),
+    ...acceptanceCoverageWarnings(acceptance.criteria, verificationHandoffs, policy.profile),
+  ];
+  const strictQuality = Boolean(opts.strictQuality && policy.strictQualitySupported);
+  const strictQualityBlocked = Boolean(strictQuality && qualityWarnings.length);
+  if (strictQualityBlocked) {
+    h5.issues = [
+      ...(h5.issues || []),
+      strictQualityIssue(qualityWarnings),
+    ];
+    h5.verdict = h5.verdict === 'block' ? 'block' : 'approve_with_fixes';
+    h5.remaining = appendText(h5.remaining, 'Resolve strict quality warnings before ship.');
+    writeHandoff(handoffDir, h5);
+  }
+
+  const result = {
+    sessionId,
+    sessionDir,
+    handoffs,
+    codexReview: h5,
+    codexChallenge: h6,
+    secureActive,
+    humanGate: Boolean(gateReason),
+    reason: gateReason || null,
+    profile: policy.profile,
+    qualityChecklist: policy.checklist,
+    qualityWarnings,
+    acceptanceCoverage: coverage,
+    strictQuality,
+    strictQualityBlocked,
+    verdict: finalVerdict(verificationHandoffs),
+  };
+  writeSummary(sessionDir, result, opts.task, latestImplement, diff, acceptance, classification);
+  return result;
+}
+
+function readPriorHandoffs(handoffDir) {
+  if (!fs.existsSync(handoffDir)) return [];
+  return fs.readdirSync(handoffDir)
+    .filter(f => f.endsWith('.json'))
+    .sort()
+    .map(f => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(handoffDir, f), 'utf8'));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function latestStageHandoff(handoffs, stage) {
+  return handoffs
+    .filter(h => h.stage === stage)
+    .sort((a, b) => Number(b.round || 1) - Number(a.round || 1))
+    .at(0) || null;
+}
+
+function readJsonIfExists(file) {
+  if (!fs.existsSync(file)) return null;
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+function readSessionProfile(sessionDir) {
+  return readJsonIfExists(path.join(sessionDir, 'ask.json'))?.profile || null;
+}
+
+function readDiffForHandoff(sessionDir, handoff) {
+  const candidates = [];
+  if (handoff.diffPath) candidates.push(handoff.diffPath);
+  const diffDir = path.join(sessionDir, 'diffs');
+  if (fs.existsSync(diffDir)) {
+    candidates.push(...fs.readdirSync(diffDir).filter(f => f.endsWith('.diff')).sort().reverse().map(f => path.join(diffDir, f)));
+  }
+  for (const f of candidates) {
+    try {
+      if (fs.existsSync(f)) return fs.readFileSync(f, 'utf8');
+    } catch {}
+  }
+  return '';
+}
+
+function strictQualityIssue(warnings) {
+  return {
+    severity: 'high',
+    category: 'test',
+    summary: 'strict quality warnings require fixes before ship',
+    claim: 'Strict quality mode found missing evidence or acceptance coverage.',
+    evidence: warnings.join('; '),
+    required_fix: 'Resolve the quality warnings, rerun verify, then rerun ship.',
+    confidence: 1,
+    gate_required: false,
+  };
+}
+
+function nextRound(handoffs, stage) {
+  const rounds = handoffs
+    .filter(h => h.stage === stage)
+    .map(h => Number(h.round || 1))
+    .filter(Number.isFinite);
+  return rounds.length ? Math.max(...rounds) + 1 : 1;
+}
+
+function writeHumanGate(sessionDir, reason) {
+  fs.writeFileSync(path.join(sessionDir, 'HUMAN_GATE'), `reason: ${reason}\nat: ${new Date().toISOString()}\n`);
+}
+
+function finalVerdict(handoffs) {
+  if (handoffs.some(h => h.verdict === 'block')) return 'block';
+  if (handoffs.some(h => h.verdict === 'approve_with_fixes')) return 'approve_with_fixes';
+  return 'approve';
+}
+
+function writeSummary(sessionDir, result, task, implementHandoff, diff, acceptance, classification) {
+  fs.writeFileSync(path.join(sessionDir, 'verify-summary.json'), JSON.stringify({
+    sessionId: result.sessionId,
+    task,
+    mode: 'verify-only',
+    implement_round: implementHandoff.round || 1,
+    implement_files: implementHandoff.files || [],
+    diff_present: Boolean(String(diff || '').trim()),
+    acceptance_required: true,
+    acceptance_count: acceptance?.criteria?.length || 0,
+    acceptance_source: acceptance?.source || null,
+    profile: result.profile || null,
+    quality_checklist: result.qualityChecklist || [],
+    quality_warnings: result.qualityWarnings || [],
+    strict_quality: Boolean(result.strictQuality),
+    strict_quality_blocked: Boolean(result.strictQualityBlocked),
+    acceptance_coverage: result.acceptanceCoverage || [],
+    evidence_warning_required: Boolean(result.profile && ['quality', 'security'].includes(result.profile)),
+    risk_level: classification?.risk || null,
+    risk_tags: classification?.tags || [],
+    codex_review_run: true,
+    codex_challenge_run: Boolean(result.codexChallenge),
+    secure_active: result.secureActive,
+    human_gate: result.humanGate,
+    reason: result.reason,
+    verdict: result.verdict,
+    ship_run: false,
+    target_project_mutated: false,
+    next_step: result.humanGate ? 'human review required' : 'fix findings or prepare an apply/ship gate',
+  }, null, 2));
+}
+
+function appendText(a = '', b = '') {
+  return [a, b].filter(Boolean).join(a && b ? ' ' : '');
+}
+
+function writeHandoff(handoffDir, h) {
+  const base = handoffBase(h);
+  fs.writeFileSync(path.join(handoffDir, `${base}.json`), JSON.stringify(h, null, 2));
+  fs.writeFileSync(path.join(handoffDir, `${base}.md`), renderHandoff(h));
+}
+
+function handoffBase(h) {
+  const nn = STAGE_INDEX[h.stage] || '00';
+  const round = Number(h.round || 1);
+  const roundSuffix = round > 1 ? `-r${round}` : '';
+  return `${nn}-${h.stage}${roundSuffix}`;
+}
+
+function renderHandoff(h) {
+  const lines = [];
+  lines.push(`# Handoff: ${h.stage}  (round ${h.round || 1}, agent: ${h.agent}, ${h.provider}/${h.model})`);
+  lines.push('');
+  lines.push(`**Decided**: ${h.decided || ''}`);
+  if (h.rejected) lines.push(`**Rejected**: ${h.rejected}`);
+  if (h.risks) lines.push(`**Risks**: ${h.risks}`);
+  lines.push(`**Files**: ${(h.files || []).join(', ')}`);
+  if (h.remaining) lines.push(`**Remaining**: ${h.remaining}`);
+  if (h.verdict) lines.push(`**Verdict**: ${h.verdict}${h.confidence != null ? ` (confidence ${h.confidence})` : ''}`);
+  if (h.issues?.length) {
+    lines.push('');
+    lines.push('## Issues');
+    for (const i of h.issues) {
+      lines.push(`- [${i.severity}/${i.category}] ${i.file || ''}${i.line ? ':' + i.line : ''} - ${i.summary}`);
+    }
+  }
+  lines.push('');
+  lines.push('<sub>verify mode: Codex only; implement not run; ship not run</sub>');
+  return lines.join('\n') + '\n';
+}
+
+function assertValidHandoff(root, handoff) {
+  const schemaPath = path.join(root, 'schemas', 'handoff.schema.json');
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  if (!validate(handoff)) {
+    const detail = (validate.errors || [])
+      .map(e => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(`verify handoff schema validation failed: ${detail}`);
+  }
+}
+
+export {
+  readPriorHandoffs as _readPriorHandoffs,
+  latestStageHandoff as _latestStageHandoff,
+  readDiffForHandoff as _readDiffForHandoff,
+  gateReasonFromFindings as _humanGateReason,
+};