@ps-neko/nekowork 0.1.0-alpha.0

package/scripts/orchestrators/ask.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildDefaultAcceptanceCriteria } from '../lib/acceptance-criteria.js';
+import { classifyRisk } from '../lib/risk-classifier.js';
+import { profilePolicy } from '../lib/profile-policy.js';
+
+export function classifyAskTask(task = '') {
+  const classification = classifyRisk({ task, files: [] });
+  return {
+    risk: classification.risk,
+    tags: classification.tags,
+    requiresCodexChallenge: classification.requiresCodexChallenge,
+    requiresHumanGate: classification.requiresHumanGate,
+  };
+}
+
+export function buildQuestionGate(task = '', opts = {}) {
+  const classification = classifyAskTask(task);
+  const policy = profilePolicy(opts.profile);
+  const questions = [
+    'What outcome should count as done?',
+    'Who is the target user or operator, and what problem should this solve?',
+    'What is the smallest MVP scope for this cycle?',
+    'What is explicitly out of scope?',
+    'What files, surfaces, or user flows are allowed to change?',
+    'What launch or readiness risk should block ship?',
+  ];
+
+  if (task.trim().split(/\s+/).filter(Boolean).length <= 6) {
+    questions.push('Should NEKOWORK proceed with reasonable assumptions, or wait for more detail?');
+  }
+  if (classification.tags.includes('product-ui')) {
+    questions.push('Is this a mock/demo UI, or should it be production-ready behavior?');
+    questions.push('What target user and required screen states should guide the UI?');
+    questions.push('What UX confusion or unsafe user assumption should the design prevent?');
+  }
+  if (classification.tags.includes('financial')) {
+    questions.push('Must all broker/order/payment behavior stay mock-only for this cycle?');
+    questions.push('What warning or demo-only labeling is required to avoid real-money confusion?');
+  }
+  if (classification.tags.includes('security')) {
+    questions.push('Which auth, token, permission, or secret boundaries are allowed to change?');
+    questions.push('Should Codex challenge and human gate be mandatory even if review passes?');
+  }
+  if (classification.tags.includes('deploy')) {
+    questions.push('Is production deployment explicitly allowed, or should this stop at release readiness?');
+  }
+  if (classification.tags.includes('data')) {
+    questions.push('Is data loss possible, and what backup or rollback condition is required?');
+  }
+  if (policy.profile === 'product') {
+    questions.push('What non-goal should be protected if scope pressure appears?');
+    questions.push('What QA acceptance criteria would make this launch-ready?');
+  }
+  if (policy.profile === 'quality') {
+    questions.push('What test-first plan should exist before implementation starts?');
+    questions.push('What evidence should prove each acceptance criterion passed?');
+  }
+
+  return {
+    stage: 'question-gate',
+    agent: 'question-gate',
+    round: 1,
+    timestamp: new Date().toISOString(),
+    provider: 'local',
+    model: 'deterministic',
+    profile: policy.profile || undefined,
+    decided: 'Question gate only. No provider call, shell command, or project file mutation is required.',
+    rejected: 'Implementation, live provider execution, shipping, and multi-worker file writes are out of scope for ask.',
+    risks: `risk=${classification.risk}; tags=${classification.tags.length ? classification.tags.join(',') : 'none'}; human_gate=${classification.requiresHumanGate ? 'required-if-continuing' : 'not-required-by-ask'}`,
+    files: [],
+    remaining: 'Answer the blocking questions or continue to plan with documented assumptions.',
+    risk_level: classification.risk,
+    questions,
+    success_criteria: buildDefaultAcceptanceCriteria(task, 3),
+    assumptions: [
+      'All ambiguous work defaults to no-ship.',
+      'Multi-worker phases are read-only unless a later work/review cycle grants one executor write authority.',
+      'Secure, financial, deploy, or destructive data work cannot bypass Codex verification and human gate policy.',
+    ],
+    requires_human_gate: classification.requiresHumanGate,
+  };
+}
+
+export async function askGate(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  const sessionId = opts.sessionId || `ask-${Date.now()}`;
+  const sessionDir = path.join(projectRoot, '.harness', 'state', 'sessions', sessionId);
+  const handoffDir = path.join(sessionDir, 'handoffs');
+  fs.mkdirSync(handoffDir, { recursive: true });
+
+  const handoff = buildQuestionGate(opts.task || '', { profile: opts.profile });
+  handoff.session_id = sessionId;
+  writeAskArtifacts(sessionDir, handoffDir, sessionId, opts.task || '', handoff);
+
+  return {
+    sessionId,
+    sessionDir,
+    handoff,
+  };
+}
+
+function writeAskArtifacts(sessionDir, handoffDir, sessionId, task, handoff) {
+  const policy = profilePolicy(handoff.profile);
+  fs.writeFileSync(path.join(sessionDir, 'ask.json'), JSON.stringify({
+    sessionId,
+    task,
+    generated_at: handoff.timestamp,
+    risk_level: handoff.risk_level,
+    profile: handoff.profile || null,
+    profile_checklist: policy.checklist,
+    requires_human_gate: handoff.requires_human_gate,
+    questions: handoff.questions,
+    success_criteria: handoff.success_criteria,
+    assumptions: handoff.assumptions,
+  }, null, 2));
+
+  fs.writeFileSync(path.join(handoffDir, '00-question-gate.json'), JSON.stringify(handoff, null, 2));
+  fs.writeFileSync(path.join(handoffDir, '00-question-gate.md'), renderQuestionGate(handoff));
+}
+
+function renderQuestionGate(h) {
+  return [
+    '# Handoff: question-gate',
+    '',
+    `Decided: ${h.decided}`,
+    `Rejected: ${h.rejected}`,
+    `Risks: ${h.risks}`,
+    'Files: ',
+    `Remaining: ${h.remaining}`,
+    '',
+    'Questions:',
+    ...h.questions.map((q, i) => `${i + 1}. ${q}`),
+    '',
+    'Draft success criteria:',
+    ...h.success_criteria.map(ac => `- ${ac.id}: ${ac.desc}`),
+    '',
+    'Assumptions:',
+    ...h.assumptions.map((a, i) => `${i + 1}. ${a}`),
+    '',
+  ].join('\n');
+}

package/scripts/orchestrators/gate.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MARKERS = {
+  human: 'HUMAN_GATE',
+  approved: 'GATE_APPROVED',
+  blocked: 'GATE_BLOCKED',
+};
+
+export function gateCommand(opts) {
+  const action = opts.action || 'status';
+  if (action === 'status') return gateStatus(opts);
+  if (action === 'approve') return approveGate(opts);
+  if (action === 'block') return blockGate(opts);
+  throw new Error(`unknown gate action: ${action}`);
+}
+
+export function gateStatus(opts) {
+  const projectRoot = opts.projectRoot || process.cwd();
+  if (!opts.sessionId) throw new Error('gate requires --session <id>');
+
+  const sessionId = opts.sessionId;
+  const sessionDir = sessionPath(projectRoot, sessionId);
+  if (!fs.existsSync(sessionDir)) {
+    return {
+      sessionId,
+      sessionDir,
+      status: 'missing',
+      humanGate: false,
+      approved: false,
+      blocked: false,
+      reason: 'session not found',
+      humanGateReason: null,
+      approvalReason: null,
+      blockReason: null,
+    };
+  }
+
+  const human = readMarker(sessionDir, MARKERS.human);
+  const approval = readMarker(sessionDir, MARKERS.approved);
+  const block = readMarker(sessionDir, MARKERS.blocked);
+
+  let status = 'clear';
+  let reason = null;
+  if (block) {
+    status = 'blocked';
+    reason = block.reason;
+  } else if (human && (!approval || markerTime(approval) < markerTime(human))) {
+    status = 'open';
+    reason = human.reason;
+  } else if (approval && (!human || markerTime(approval) >= markerTime(human))) {
+    status = 'approved';
+    reason = approval.reason;
+  }
+
+  return {
+    sessionId,
+    sessionDir,
+    status,
+    humanGate: Boolean(human) && status !== 'approved',
+    approved: status === 'approved',
+    blocked: status === 'blocked',
+    reason,
+    humanGateReason: human?.reason || null,
+    approvalReason: approval?.reason || null,
+    blockReason: block?.reason || null,
+    humanGateAt: human?.at || null,
+    approvalAt: approval?.at || null,
+    blockAt: block?.at || null,
+  };
+}
+
+export function approveGate(opts) {
+  const base = gateStatus(opts);
+  if (base.status === 'missing') throw new Error('gate approve requires an existing session');
+  if (base.status === 'blocked') throw new Error('gate approve cannot override an explicit gate block');
+  if (base.status !== 'open') throw new Error('gate approve requires an open HUMAN_GATE');
+  if (!String(opts.reason || '').trim()) throw new Error('gate approve requires --reason <text>');
+
+  const sessionDir = base.sessionDir;
+  writeMarker(sessionDir, MARKERS.approved, {
+    reason: opts.reason,
+    humanGateReason: base.humanGateReason,
+  });
+  appendEvent(sessionDir, {
+    event: 'approve',
+    reason: opts.reason,
+    humanGateReason: base.humanGateReason,
+  });
+  const result = gateStatus(opts);
+  writeSummary(sessionDir, result, 'approve');
+  return result;
+}
+
+export function blockGate(opts) {
+  const projectRoot = opts.projectRoot || process.cwd();
+  if (!opts.sessionId) throw new Error('gate requires --session <id>');
+  if (!String(opts.reason || '').trim()) throw new Error('gate block requires --reason <text>');
+
+  const sessionDir = sessionPath(projectRoot, opts.sessionId);
+  if (!fs.existsSync(sessionDir)) throw new Error('gate block requires an existing session');
+
+  const reason = opts.reason;
+  writeMarker(sessionDir, MARKERS.human, { reason: `manual block: ${reason}` });
+  writeMarker(sessionDir, MARKERS.blocked, { reason });
+  appendEvent(sessionDir, { event: 'block', reason });
+  const result = gateStatus(opts);
+  writeSummary(sessionDir, result, 'block');
+  return result;
+}
+
+function sessionPath(projectRoot, sessionId) {
+  return path.join(projectRoot, '.harness', 'state', 'sessions', sessionId);
+}
+
+function readMarker(sessionDir, name) {
+  const file = path.join(sessionDir, name);
+  if (!fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, 'utf8');
+  return {
+    kind: name,
+    file,
+    raw,
+    reason: raw.match(/^reason:\s*(.+)$/m)?.[1] || null,
+    at: raw.match(/^at:\s*(.+)$/m)?.[1] || null,
+    humanGateReason: raw.match(/^human_gate_reason:\s*(.+)$/m)?.[1] || null,
+  };
+}
+
+function writeMarker(sessionDir, name, fields) {
+  const lines = [];
+  lines.push(`reason: ${fields.reason}`);
+  if (fields.humanGateReason) lines.push(`human_gate_reason: ${fields.humanGateReason}`);
+  lines.push(`at: ${new Date().toISOString()}`);
+  fs.writeFileSync(path.join(sessionDir, name), lines.join('\n') + '\n');
+}
+
+function appendEvent(sessionDir, event) {
+  const row = {
+    ...event,
+    at: new Date().toISOString(),
+  };
+  fs.appendFileSync(path.join(sessionDir, 'gate-events.jsonl'), JSON.stringify(row) + '\n');
+}
+
+function writeSummary(sessionDir, result, action) {
+  fs.writeFileSync(path.join(sessionDir, 'gate-summary.json'), JSON.stringify({
+    sessionId: result.sessionId,
+    action,
+    status: result.status,
+    human_gate: result.humanGate,
+    approved: result.approved,
+    blocked: result.blocked,
+    reason: result.reason,
+    human_gate_reason: result.humanGateReason,
+    approval_reason: result.approvalReason,
+    block_reason: result.blockReason,
+    target_project_mutated: false,
+    next_step: nextStep(result),
+  }, null, 2));
+}
+
+function nextStep(result) {
+  if (result.status === 'approved') return 'rerun ship for readiness';
+  if (result.status === 'blocked') return 'do not ship; revise work or start a new cycle';
+  if (result.status === 'open') return 'human must approve or block the gate';
+  if (result.status === 'missing') return 'create a work/verify session first';
+  return 'continue to verify or ship';
+}
+
+function markerTime(marker) {
+  const time = Date.parse(marker?.at || '');
+  return Number.isFinite(time) ? time : 0;
+}
+
+export {
+  readMarker as _readMarker,
+  markerTime as _markerTime,
+};

package/scripts/orchestrators/ralph.js

@@ -0,0 +1,179 @@
+// Persistent Ralph loop. It repeats an execution engine until PRD acceptance
+// criteria pass, a human gate stops the run, cost cap is hit, or max-iter ends.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { reviewCycle } from './review.js';
+import { runCycle } from './run.js';
+import { list as costList, summarize as costSummarize } from '../lib/costs.js';
+
+const DEFAULT_MAX_ITER = Number(process.env.HARNESS_RALPH_MAX_ITER || 5);
+const DAILY_CAP_USD = Number(process.env.HARNESS_DAILY_COST_CAP_USD || 0);
+const VALID_ENGINES = new Set(['review', 'legacy-review', 'run']);
+
+export async function ralphLoop(opts) {
+  const harnessRoot = opts.harnessRoot || process.cwd();
+  const projectRoot = opts.projectRoot || harnessRoot;
+  const sessionId = opts.sessionId || `ralph-${Date.now()}`;
+  const maxIter = Math.max(1, Number(opts.maxIter || DEFAULT_MAX_ITER));
+  const engine = normalizeEngine(opts.engine || 'review');
+
+  const sessionDir = path.join(projectRoot, '.harness', 'state', 'sessions', sessionId);
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(path.join(sessionDir, 'active'), renderActiveFile({
+    started_at: new Date().toISOString(),
+    mode: 'ralph',
+    engine,
+    task: opts.task,
+    max_iter: maxIter,
+    live: Boolean(opts.live),
+    secure: Boolean(opts.secure),
+  }));
+
+  const log = (m) => console.log(`[ralph:${sessionId}] ${m}`);
+  const progress = (line) => fs.appendFileSync(path.join(sessionDir, 'progress.txt'), `[${new Date().toISOString()}] ${line}\n`);
+
+  log(`start: max-iter=${maxIter}, engine=${engine}, task="${opts.task}"`);
+
+  let iter = 0;
+  let result;
+  const iterationSessions = [];
+  while (iter < maxIter) {
+    iter++;
+    log(`iter ${iter}/${maxIter}`);
+    progress(`iter ${iter} start (${engine})`);
+
+    if (DAILY_CAP_USD > 0) {
+      const today = costList({ since: '24h' });
+      const sum = costSummarize(today);
+      if (sum.total_usd >= DAILY_CAP_USD) {
+        log(`STOP: daily cost cap $${DAILY_CAP_USD} reached (current $${sum.total_usd})`);
+        progress('STOP cost_cap');
+        try { fs.unlinkSync(path.join(sessionDir, 'active')); } catch {}
+        return finish(sessionDir, 'cost_cap', { engine, iter, iteration_sessions: iterationSessions, sum });
+      }
+    }
+
+    const iterSessionId = `${sessionId}-i${iter}`;
+    iterationSessions.push(iterSessionId);
+    result = await runIteration({
+      engine,
+      opts,
+      harnessRoot,
+      projectRoot,
+      sessionDir,
+      iterSessionId,
+    });
+
+    if (result.humanGate) {
+      log(`STOP: HUMAN_GATE - ${result.reason}`);
+      progress(`STOP human_gate ${result.reason}`);
+      try { fs.unlinkSync(path.join(sessionDir, 'active')); } catch {}
+      fs.writeFileSync(path.join(sessionDir, 'HUMAN_GATE'), `reason: ${result.reason}\nfrom: ${result.sessionId}\n`);
+      return finish(sessionDir, 'human_gate', { engine, iter, iteration_sessions: iterationSessions, last: result });
+    }
+
+    const ralphPrd = path.join(sessionDir, 'prd.json');
+    if (!fs.existsSync(ralphPrd)) {
+      const iterationPrd = path.join(result.sessionDir, 'prd.json');
+      if (fs.existsSync(iterationPrd)) fs.copyFileSync(iterationPrd, ralphPrd);
+      else fs.writeFileSync(ralphPrd, JSON.stringify(defaultPrd(opts.task), null, 2));
+    }
+
+    const prd = JSON.parse(fs.readFileSync(ralphPrd, 'utf8'));
+    const next = (prd.acceptance || []).find(a => !a.passes);
+    if (next) {
+      next.passes = true;
+      fs.writeFileSync(ralphPrd, JSON.stringify(prd, null, 2));
+      progress(`AC ${next.id} -> passes:true`);
+    }
+
+    const total = (prd.acceptance || []).length;
+    const passed = (prd.acceptance || []).filter(a => a.passes).length;
+    log(`AC progress: ${passed}/${total} PASS`);
+    if (passed === total && total > 0) {
+      log('all AC PASS -> done');
+      progress('STOP all_ac_passed');
+      try { fs.unlinkSync(path.join(sessionDir, 'active')); } catch {}
+      return finish(sessionDir, 'all_passed', { engine, iter, iteration_sessions: iterationSessions, last: result });
+    }
+  }
+
+  log(`STOP: max-iter ${maxIter} reached`);
+  progress('STOP max_iter');
+  try { fs.unlinkSync(path.join(sessionDir, 'active')); } catch {}
+  return finish(sessionDir, 'max_iter', { engine, iter, iteration_sessions: iterationSessions, last: result });
+}
+
+async function runIteration({ engine, opts, harnessRoot, projectRoot, sessionDir, iterSessionId }) {
+  if (engine === 'run') {
+    const iterSessionDir = path.join(projectRoot, '.harness', 'state', 'sessions', iterSessionId);
+    fs.mkdirSync(iterSessionDir, { recursive: true });
+    syncRalphPrdToIteration(sessionDir, iterSessionDir, opts.task);
+    return runCycle({
+      task: opts.task,
+      live: opts.live,
+      secure: opts.secure,
+      apply: false,
+      sessionId: iterSessionId,
+      harnessRoot,
+      projectRoot,
+      dispatcher: opts.dispatcher,
+    });
+  }
+
+  return reviewCycle({
+    task: opts.task,
+    live: opts.live,
+    secure: opts.secure,
+    noShip: true,
+    sessionId: iterSessionId,
+    harnessRoot,
+    projectRoot,
+  });
+}
+
+function normalizeEngine(engine) {
+  const value = String(engine || '').trim();
+  if (!VALID_ENGINES.has(value)) {
+    throw new Error(`unknown ralph engine: ${engine}. Use "review" or "run".`);
+  }
+  return value === 'legacy-review' ? 'review' : value;
+}
+
+function syncRalphPrdToIteration(ralphSessionDir, iterSessionDir, task) {
+  const ralphPrd = path.join(ralphSessionDir, 'prd.json');
+  if (!fs.existsSync(ralphPrd)) {
+    fs.writeFileSync(ralphPrd, JSON.stringify(defaultPrd(task), null, 2));
+  }
+  fs.copyFileSync(ralphPrd, path.join(iterSessionDir, 'prd.json'));
+}
+
+function defaultPrd(task) {
+  return {
+    task,
+    acceptance: [
+      { id: 'AC-001', desc: 'Primary happy path is handled', passes: false },
+      { id: 'AC-002', desc: 'Failure or edge cases are handled', passes: false },
+      { id: 'AC-003', desc: 'Verification and handoff artifacts are present', passes: false },
+    ],
+    non_goals: [],
+  };
+}
+
+function finish(sessionDir, reason, extras) {
+  const summary = { reason, finished_at: new Date().toISOString(), ...extras };
+  fs.writeFileSync(path.join(sessionDir, 'ralph-summary.json'), JSON.stringify(summary, null, 2));
+  return summary;
+}
+
+function renderActiveFile(fields) {
+  return Object.entries(fields)
+    .map(([key, value]) => `${key}: ${typeof value === 'string' ? JSON.stringify(value) : value}`)
+    .join('\n') + '\n';
+}
+
+export {
+  normalizeEngine as _normalizeEngine,
+  defaultPrd as _defaultPrd,
+};