@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/orchestrators/ship.js

@@ -0,0 +1,339 @@
+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 { gateStatus } from './gate.js';
+
+const STAGE_INDEX = { ship: '07' };
+
+export async function shipCycle(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  if (!opts.sessionId) throw new Error('ship requires --session <id> from a verified 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('ship requires an implement handoff. Run harness work first, using the same --session.');
+  }
+
+  const latestCodexReview = latestStageHandoff(priorHandoffs, 'codex-review');
+  if (!latestCodexReview) {
+    throw new Error('ship requires Codex verification. Run harness verify first, using the same --session.');
+  }
+
+  fs.mkdirSync(handoffDir, { recursive: true });
+
+  const gate = gateStatus({ sessionId, projectRoot });
+  const existingGate = gate.humanGateReason;
+  const gateApproved = gate.status === 'approved' && Boolean(existingGate);
+  if (gate.status === 'blocked') {
+    return writeBlockedSummary({
+      sessionId,
+      sessionDir,
+      task: opts.task,
+      priorHandoffs,
+      reason: gate.reason,
+      source: 'gate-blocked',
+    });
+  }
+  if (existingGate && !gateApproved) {
+    return writeBlockedSummary({
+      sessionId,
+      sessionDir,
+      task: opts.task,
+      priorHandoffs,
+      reason: existingGate,
+      source: 'existing-human-gate',
+    });
+  }
+
+  const riskPolicy = classifyRisk({ task: opts.task, files: latestImplement.files || [] });
+  if (riskPolicy.requiresHumanGate && !gateApproved) {
+    const reason = `risk policy requires human gate (${riskPolicy.tags.join(',') || riskPolicy.risk})`;
+    writeHumanGate(sessionDir, reason);
+    return writeBlockedSummary({
+      sessionId,
+      sessionDir,
+      task: opts.task,
+      priorHandoffs,
+      reason,
+      source: 'risk-policy',
+    });
+  }
+
+  const verificationHandoffs = [latestCodexReview, latestStageHandoff(priorHandoffs, 'codex-challenge')].filter(Boolean);
+  const gateReason = humanGateReason(verificationHandoffs);
+  if (gateReason && !gateApproved) {
+    writeHumanGate(sessionDir, gateReason);
+    return writeBlockedSummary({
+      sessionId,
+      sessionDir,
+      task: opts.task,
+      priorHandoffs,
+      reason: gateReason,
+      source: 'verification-gate',
+    });
+  }
+
+  const dispatcher = opts.dispatcher || dispatch;
+  const live = !!opts.live;
+  const prd = readJsonIfExists(path.join(sessionDir, 'prd.json'));
+  const acceptance = ensureAcceptanceCriteria({ sessionDir, task: opts.task });
+  const classification = riskPolicy;
+  const verificationVerdict = finalVerificationVerdict(verificationHandoffs);
+  const verdict = gateApproved ? 'approve' : verificationVerdict;
+  const shipReady = verdict === 'approve';
+  const round = nextRound(priorHandoffs, 'ship');
+
+  const h7 = await dispatcher({
+    agent: 'doc-writer',
+    stage: 'ship',
+    task: opts.task || `ship session ${sessionId}`,
+    live,
+    harnessRoot,
+    projectRoot,
+    sessionDir,
+    sessionId,
+    sandboxOverride: 'read-only',
+    context: {
+      round,
+      prd,
+      acceptanceCriteria: acceptance.criteria,
+      priorHandoffs: priorHandoffs.slice(-8),
+      shipOnly: true,
+      shipReady,
+      gateApproved,
+      gateStatus: gate.status,
+      verificationVerdict,
+      effectiveVerdict: verdict,
+      noProjectMutation: true,
+      riskClassification: classification,
+    },
+  });
+  h7.round = round;
+  h7.session_id = sessionId;
+  h7.verdict = shipReady ? 'approve' : 'approve_with_fixes';
+  h7.risks = appendText(h7.risks, shipReady
+    ? gateApproved
+      ? `Human gate approved (${gate.approvalReason || 'no reason recorded'}). Human still controls PR, release, publish, and deploy.`
+      : 'Human still controls PR, release, publish, and deploy.'
+    : 'Codex reported fixable findings; create a no-ship handoff until they are resolved.');
+  h7.remaining = shipReady
+    ? 'human may create PR/release using this handoff'
+    : 'resolve Codex findings, rerun verify, then rerun ship';
+  assertValidHandoff(harnessRoot, h7);
+  writeHandoff(handoffDir, h7);
+
+  if (shipReady) writeMarker(sessionDir, 'SHIP_READY', 'ready');
+  else writeMarker(sessionDir, 'NO_SHIP', `verification verdict: ${verdict}`);
+
+  const result = {
+    sessionId,
+    sessionDir,
+    handoffs: [...priorHandoffs, h7],
+    shipHandoff: h7,
+    shipReady,
+    noShip: !shipReady,
+    humanGate: false,
+    reason: shipReady ? null : `verification verdict is ${verdict}`,
+    verdict,
+    gateApproved,
+    verificationVerdict,
+  };
+  writeSummary(sessionDir, {
+    sessionId,
+    task: opts.task,
+    mode: 'ship-readiness',
+    shipReady,
+    noShip: !shipReady,
+    humanGate: false,
+    reason: result.reason,
+    verdict,
+    gate,
+    gateApproved,
+    verificationVerdict,
+    acceptance,
+    classification,
+    implementHandoff: latestImplement,
+    verificationHandoffs,
+    shipHandoff: h7,
+  });
+  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 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 readJsonIfExists(file) {
+  if (!fs.existsSync(file)) return null;
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+const humanGateReason = gateReasonFromFindings;
+
+function writeHumanGate(sessionDir, reason) {
+  fs.writeFileSync(path.join(sessionDir, 'HUMAN_GATE'), `reason: ${reason}\nat: ${new Date().toISOString()}\n`);
+}
+
+function finalVerificationVerdict(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 writeBlockedSummary({ sessionId, sessionDir, task, priorHandoffs, reason, source }) {
+  const latestImplement = latestStageHandoff(priorHandoffs, 'implement');
+  const verificationHandoffs = [
+    latestStageHandoff(priorHandoffs, 'codex-review'),
+    latestStageHandoff(priorHandoffs, 'codex-challenge'),
+  ].filter(Boolean);
+  writeSummary(sessionDir, {
+    sessionId,
+    task,
+    mode: 'ship-readiness',
+    shipReady: false,
+    noShip: true,
+    humanGate: true,
+    reason,
+    source,
+    verdict: 'block',
+    implementHandoff: latestImplement,
+    verificationHandoffs,
+    shipHandoff: null,
+  });
+  return {
+    sessionId,
+    sessionDir,
+    handoffs: priorHandoffs,
+    shipHandoff: null,
+    shipReady: false,
+    noShip: true,
+    humanGate: true,
+    reason,
+    verdict: 'block',
+  };
+}
+
+function writeSummary(sessionDir, summary) {
+  fs.writeFileSync(path.join(sessionDir, 'ship-summary.json'), JSON.stringify({
+    sessionId: summary.sessionId,
+    task: summary.task || null,
+    mode: summary.mode,
+    implement_round: summary.implementHandoff?.round || null,
+    implement_files: summary.implementHandoff?.files || [],
+    codex_review_verdict: summary.verificationHandoffs.find(h => h.stage === 'codex-review')?.verdict || null,
+    codex_challenge_verdict: summary.verificationHandoffs.find(h => h.stage === 'codex-challenge')?.verdict || null,
+    acceptance_required: true,
+    acceptance_count: summary.acceptance?.criteria?.length || 0,
+    acceptance_source: summary.acceptance?.source || null,
+    risk_level: summary.classification?.risk || null,
+    risk_tags: summary.classification?.tags || [],
+    ship_handoff_run: Boolean(summary.shipHandoff),
+    ship_ready: summary.shipReady,
+    no_ship: summary.noShip,
+    human_gate: summary.humanGate,
+    reason: summary.reason || null,
+    verdict: summary.verdict,
+    verification_verdict: summary.verificationVerdict || summary.verdict,
+    gate_status: summary.gate?.status || null,
+    gate_approved: Boolean(summary.gateApproved),
+    target_project_mutated: false,
+    next_step: summary.humanGate
+      ? 'human review required before ship'
+      : summary.shipReady
+        ? 'human may create PR/release/deploy from the ship handoff'
+        : 'resolve findings, rerun verify, then rerun ship',
+  }, null, 2));
+}
+
+function writeMarker(sessionDir, name, reason) {
+  fs.writeFileSync(path.join(sessionDir, name), `reason: ${reason}\nat: ${new Date().toISOString()}\n`);
+}
+
+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})` : ''}`);
+  lines.push('');
+  lines.push('<sub>ship mode: readiness handoff only; target project not mutated; human owns PR/release/deploy</sub>');
+  return lines.join('\n') + '\n';
+}
+
+function appendText(a = '', b = '') {
+  return [a, b].filter(Boolean).join(a && b ? ' ' : '');
+}
+
+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(`ship handoff schema validation failed: ${detail}`);
+  }
+}
+
+export {
+  readPriorHandoffs as _readPriorHandoffs,
+  latestStageHandoff as _latestStageHandoff,
+  humanGateReason as _humanGateReason,
+  finalVerificationVerdict as _finalVerificationVerdict,
+};

package/scripts/orchestrators/team-lite.js

@@ -0,0 +1,270 @@
+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 TEAM_LITE_STAGES = [
+  { id: 'team-plan', agent: 'planner', stage: 'plan', owner: 'planner' },
+  { id: 'team-prd', agent: 'architect', stage: 'plan', owner: 'architect' },
+  { id: 'team-exec', agent: 'executor', stage: 'implement', owner: 'executor' },
+  { id: 'team-verify', agent: 'code-reviewer', stage: 'self-review', owner: 'verifier' },
+  { id: 'team-fix', agent: 'executor', stage: 'implement', owner: 'executor', conditional: true },
+];
+
+const TERMINAL_STATUSES = new Set(['done', 'skipped', 'failed']);
+
+export async function teamLiteCycle(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  const sessionId = opts.sessionId || `team-lite-${Date.now()}`;
+  const sessionDir = path.join(projectRoot, '.harness', 'state', 'sessions', sessionId);
+  const handoffDir = path.join(sessionDir, 'handoffs');
+  const heartbeatDir = path.join(sessionDir, 'heartbeats');
+  fs.mkdirSync(handoffDir, { recursive: true });
+  fs.mkdirSync(heartbeatDir, { recursive: true });
+
+  const live = !!opts.live;
+  const handoffs = [];
+  const dispatcher = opts.dispatcher || dispatch;
+  const tasks = createTasks();
+  assertTaskGraph(tasks);
+
+  writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+  writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs);
+
+  for (const spec of TEAM_LITE_STAGES) {
+    const task = tasks.find(t => t.id === spec.id);
+    if (spec.conditional && teamVerifyVerdict(handoffs) === 'approve') {
+      task.status = 'skipped';
+      task.reason = 'team-verify approved';
+      task.completed_at = new Date().toISOString();
+      writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+      writeHeartbeat(sessionDir, sessionId, spec.id, 'skipped');
+      writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs);
+      continue;
+    }
+
+    task.status = 'running';
+    task.started_at = new Date().toISOString();
+    writeHeartbeat(sessionDir, sessionId, spec.id, 'running');
+    writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+    writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs);
+
+    let handoff;
+    try {
+      handoff = await runStage({
+        harnessRoot,
+        projectRoot,
+        live,
+        sessionDir,
+        sessionId,
+        spec,
+        task: opts.task,
+        priorHandoffs: handoffs.slice(-3),
+        dispatcher,
+      });
+
+      handoff.team_stage = spec.id;
+      removeUndefined(handoff);
+      assertValidHandoff(harnessRoot, handoff);
+      handoffs.push(handoff);
+      writeHandoff(handoffDir, handoff, handoffs.length);
+    } catch (e) {
+      task.status = 'failed';
+      task.completed_at = new Date().toISOString();
+      task.error = e.message || String(e);
+      writeHeartbeat(sessionDir, sessionId, spec.id, 'failed');
+      writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+      writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs);
+      throw new Error(`${spec.id} failed: ${task.error}`);
+    }
+
+    task.status = 'done';
+    task.completed_at = new Date().toISOString();
+    task.verdict = handoff.verdict || null;
+    task.handoff = path.relative(sessionDir, handoffJsonPath(handoffDir, handoff, handoffs.length)).replace(/\\/g, '/');
+    writeHeartbeat(sessionDir, sessionId, spec.id, 'done');
+    writeTeamState(sessionDir, sessionId, opts.task, tasks, handoffs);
+    writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs);
+  }
+
+  writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs);
+  return {
+    sessionId,
+    sessionDir,
+    mode: 'advanced-team-lite-handoff',
+    tasks,
+    handoffs,
+    verdict: lastVerdict(handoffs) || 'unknown',
+    targetProjectMutated: false,
+    nextStep: 'use work/run for single-executor implementation, then verify and ship',
+  };
+}
+
+async function runStage({ harnessRoot, projectRoot, live, sessionDir, sessionId, spec, task, priorHandoffs, dispatcher }) {
+  return dispatcher({
+    agent: spec.agent,
+    stage: spec.stage,
+    task,
+    live,
+    harnessRoot,
+    projectRoot,
+    sessionDir,
+    sessionId,
+    sandboxOverride: 'read-only',
+    context: {
+      priorHandoffs,
+      teamLite: true,
+      readOnlyHandoff: true,
+      noProjectMutation: true,
+      recommendedNextStep: 'work/run -> verify -> ship',
+    },
+  });
+}
+
+function createTasks() {
+  return TEAM_LITE_STAGES.map(s => ({
+    id: s.id,
+    owner: s.owner,
+    agent: s.agent,
+    stage: s.stage,
+    status: 'pending',
+    depends_on: previousStageId(s.id),
+    conditional: Boolean(s.conditional),
+  }));
+}
+
+function assertTaskGraph(tasks) {
+  const ids = new Set(tasks.map(t => t.id));
+  for (const task of tasks) {
+    if (!task.owner || !task.agent || !task.stage) {
+      throw new Error(`team-lite task contract incomplete: ${task.id}`);
+    }
+    if (!['pending', 'running', 'done', 'skipped', 'failed'].includes(task.status)) {
+      throw new Error(`team-lite task has invalid status: ${task.id}=${task.status}`);
+    }
+    for (const dep of task.depends_on || []) {
+      if (!ids.has(dep)) throw new Error(`team-lite task ${task.id} depends on unknown task ${dep}`);
+    }
+  }
+}
+
+function previousStageId(id) {
+  const idx = TEAM_LITE_STAGES.findIndex(s => s.id === id);
+  return idx > 0 ? [TEAM_LITE_STAGES[idx - 1].id] : [];
+}
+
+function lastVerdict(handoffs) {
+  return [...handoffs].reverse().find(h => h.verdict)?.verdict || null;
+}
+
+function teamVerifyVerdict(handoffs) {
+  return handoffs.find(h => h.team_stage === 'team-verify')?.verdict || null;
+}
+
+function writeTeamState(sessionDir, sessionId, task, tasks, handoffs) {
+  const state = {
+    sessionId,
+    task,
+    mode: 'advanced-team-lite-handoff',
+    mutation: 'read-only-handoffs',
+    target_project_mutated: false,
+    recommended_next_step: 'use work/run for single-executor implementation, then verify and ship',
+    updated_at: new Date().toISOString(),
+    pipeline: TEAM_LITE_STAGES.map(s => s.id),
+    terminal_statuses: [...TERMINAL_STATUSES],
+    tasks,
+    handoffs: handoffs.map(h => ({
+      team_stage: h.team_stage,
+      agent: h.agent,
+      stage: h.stage,
+      verdict: h.verdict || null,
+      files: h.files || [],
+    })),
+  };
+  fs.writeFileSync(path.join(sessionDir, 'team-lite.json'), JSON.stringify(state, null, 2));
+}
+
+function writeHeartbeat(sessionDir, sessionId, stage, status) {
+  const beat = {
+    sessionId,
+    stage,
+    status,
+    at: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(sessionDir, 'heartbeat.json'), JSON.stringify(beat, null, 2));
+  fs.writeFileSync(path.join(sessionDir, 'heartbeats', `${stage}.json`), JSON.stringify(beat, null, 2));
+  fs.appendFileSync(path.join(sessionDir, 'heartbeat.jsonl'), JSON.stringify(beat) + '\n');
+}
+
+function writeMonitorSnapshot(sessionDir, sessionId, tasks, handoffs) {
+  fs.writeFileSync(path.join(sessionDir, 'monitor.json'), JSON.stringify({
+    sessionId,
+    at: new Date().toISOString(),
+    pipeline: TEAM_LITE_STAGES.map(s => s.id),
+    pending: tasks.filter(t => t.status === 'pending').length,
+    running: tasks.filter(t => t.status === 'running').length,
+    done: tasks.filter(t => t.status === 'done').length,
+    skipped: tasks.filter(t => t.status === 'skipped').length,
+    failed: tasks.filter(t => t.status === 'failed').length,
+    terminal: tasks.filter(t => TERMINAL_STATUSES.has(t.status)).length,
+    non_terminal: tasks.filter(t => !TERMINAL_STATUSES.has(t.status)).length,
+    last_verdict: lastVerdict(handoffs),
+    last_team_stage: handoffs.at(-1)?.team_stage || null,
+  }, 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-lite handoff schema validation failed: ${detail}`);
+  }
+}
+
+export {
+  TEAM_LITE_STAGES,
+  createTasks as _createTasks,
+  assertTaskGraph as _assertTaskGraph,
+};