@worca/app 0.0.1

package/src/core/protocol.mjs

@@ -0,0 +1,257 @@
+// src/core/protocol.mjs
+// JSON contracts + validators shared by agents and the orchestrator.
+//
+// All readers are tolerant: a missing or malformed file yields a safe empty
+// shape rather than throwing. Writers serialize canonical JSON shapes that the
+// agent prompts (agents/*.md) are instructed to produce.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Severity ranking used throughout the pipeline. Order is significant:
+ * earlier entries are more severe. "critical" and "major" are *blocking*.
+ */
+export const SEVERITIES = ['critical', 'major', 'minor', 'suggestion'];
+
+const BLOCKING = new Set(['critical', 'major']);
+
+/** Normalize an arbitrary value to one of SEVERITIES (default "minor"). */
+function normalizeSeverity(value) {
+  if (typeof value !== 'string') return 'minor';
+  const v = value.trim().toLowerCase();
+  return SEVERITIES.includes(v) ? v : 'minor';
+}
+
+/** Coerce any value to a trimmed string (empty string for null/undefined). */
+function asString(value) {
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+/**
+ * Tolerant JSON parser.
+ * - Accepts plain JSON.
+ * - Strips ```json ... ``` (or bare ``` ... ```) fences.
+ * - Falls back to extracting the first balanced {...} object found in the text
+ *   (handles models that wrap JSON in prose).
+ * Returns the parsed object/array, or null if nothing parseable is found.
+ *
+ * @param {string} text
+ * @returns {object|Array|null}
+ */
+export function safeParseJson(text) {
+  if (text === null || text === undefined) return null;
+  let raw = String(text).trim();
+  if (!raw) return null;
+
+  // 1) Direct parse.
+  const direct = tryParse(raw);
+  if (direct !== undefined) return direct;
+
+  // 2) Strip code fences (```json\n...\n``` or ```\n...\n```).
+  const fence = raw.match(/```(?:json|JSON)?\s*([\s\S]*?)```/);
+  if (fence && fence[1]) {
+    const inner = tryParse(fence[1].trim());
+    if (inner !== undefined) return inner;
+    raw = fence[1].trim();
+  }
+
+  // 3) Find the first balanced JSON object or array in the remaining text.
+  const balanced = extractFirstBalanced(raw);
+  if (balanced !== null) {
+    const parsed = tryParse(balanced);
+    if (parsed !== undefined) return parsed;
+  }
+
+  return null;
+}
+
+function tryParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Scan `text` for the first balanced {...} or [...] region, respecting strings
+ * and escapes so braces inside string literals do not confuse the matcher.
+ * Returns the substring (inclusive of the delimiters) or null.
+ */
+function extractFirstBalanced(text) {
+  const startIdx = firstIndexOfEither(text, '{', '[');
+  if (startIdx === -1) return null;
+
+  const open = text[startIdx];
+  const close = open === '{' ? '}' : ']';
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let i = startIdx; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === open) {
+      depth++;
+    } else if (ch === close) {
+      depth--;
+      if (depth === 0) {
+        return text.slice(startIdx, i + 1);
+      }
+    }
+  }
+  return null;
+}
+
+function firstIndexOfEither(text, a, b) {
+  const ia = text.indexOf(a);
+  const ib = text.indexOf(b);
+  if (ia === -1) return ib;
+  if (ib === -1) return ia;
+  return Math.min(ia, ib);
+}
+
+// Hard caps so a single clarify round can never overwhelm the user, regardless of
+// what the clarify agent emits. Tunable; pairs with the prompt guidance in
+// agents/worca-cc-clarify.md (up to 8 questions, 2–4 options each).
+const MAX_CLARIFY_QUESTIONS = 8;
+const MAX_CLARIFY_OPTIONS = 4;
+
+/**
+ * Coerce arbitrary parsed data into the canonical clarify shape:
+ *   { questions: [ { id, question, options:[2–4 strings], allowFreeText:true } ] }
+ * Always returns at least { questions: [] }. Caps questions at MAX_CLARIFY_QUESTIONS
+ * and options at MAX_CLARIFY_OPTIONS; blank options are trimmed away (the UI/CLI also
+ * filter them), so binary/assumption questions keep exactly their real choices —
+ * nothing is padded.
+ */
+export function normalizeClarify(data) {
+  if (!data || typeof data !== 'object') return { questions: [] };
+  const list = Array.isArray(data.questions) ? data.questions : [];
+  const questions = [];
+  for (let i = 0; i < list.length; i++) {
+    const q = list[i];
+    if (!q || typeof q !== 'object') continue;
+    const id = asString(q.id).trim() || `q${i + 1}`;
+    const question = asString(q.question).trim();
+    if (!question) continue;
+    // Allow 2–4 options: trim, drop blanks, cap at MAX_CLARIFY_OPTIONS. No padding.
+    // asString does not trim, so trim explicitly here before dropping empties.
+    const options = (Array.isArray(q.options) ? q.options.map(asString) : [])
+      .map((o) => o.trim())
+      .filter(Boolean)
+      .slice(0, MAX_CLARIFY_OPTIONS);
+    questions.push({ id, question, options, allowFreeText: true });
+  }
+  return { questions: questions.slice(0, MAX_CLARIFY_QUESTIONS) };
+}
+
+/**
+ * Read clarify.json from a pipeline directory. Missing/invalid => { questions: [] }.
+ * @param {string} pipelineDir
+ * @returns {Promise<{questions: Array}>}
+ */
+export async function readClarify(pipelineDir) {
+  const file = join(pipelineDir, 'clarify.json');
+  let text;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch {
+    return { questions: [] };
+  }
+  const parsed = safeParseJson(text);
+  return normalizeClarify(parsed);
+}
+
+/**
+ * Read one ask-then-resume questions file (per-step user questions, spec
+ * 2026-07-11) from an ABSOLUTE path. Same schema, caps, and tolerance as
+ * clarify.json. Missing file => { questions: [], malformed: false } (the agent
+ * chose not to ask); present-but-unparseable => malformed: true so the caller
+ * can audit-warn while proceeding.
+ * @param {string} absPath
+ * @returns {Promise<{questions: Array, malformed: boolean}>}
+ */
+export async function readQuestionsFile(absPath) {
+  let text;
+  try {
+    text = await readFile(absPath, 'utf8');
+  } catch {
+    return { questions: [], malformed: false };
+  }
+  const parsed = safeParseJson(text);
+  if (parsed === null) return { questions: [], malformed: true };
+  return { ...normalizeClarify(parsed), malformed: false };
+}
+
+/**
+ * Coerce arbitrary parsed data into the canonical review shape:
+ *   { issues: [ { severity, title, detail, location } ], summary }
+ * Always returns { issues: [], summary: '' } on bad input.
+ */
+function normalizeReview(data) {
+  if (!data || typeof data !== 'object') return { issues: [], summary: '' };
+  const list = Array.isArray(data.issues) ? data.issues : [];
+  const issues = [];
+  for (const it of list) {
+    if (!it || typeof it !== 'object') continue;
+    issues.push({
+      severity: normalizeSeverity(it.severity),
+      title: asString(it.title).trim(),
+      detail: asString(it.detail).trim(),
+      location: asString(it.location).trim(),
+    });
+  }
+  return { issues, summary: asString(data.summary).trim() };
+}
+
+/**
+ * Read a review JSON file from an absolute path.
+ * Missing/invalid => { issues: [], summary: '' }.
+ * @param {string} jsonPath
+ * @returns {Promise<{issues: Array, summary: string}>}
+ */
+export async function readReview(jsonPath) {
+  let text;
+  try {
+    text = await readFile(jsonPath, 'utf8');
+  } catch {
+    return { issues: [], summary: '' };
+  }
+  return normalizeReview(safeParseJson(text));
+}
+
+/**
+ * True if a review contains any critical or major issue.
+ * @param {{issues: Array}} review
+ * @returns {boolean}
+ */
+export function hasBlocking(review) {
+  if (!review || !Array.isArray(review.issues)) return false;
+  return review.issues.some((i) => BLOCKING.has(normalizeSeverity(i?.severity)));
+}
+
+/**
+ * The subset of issues that are critical or major.
+ * @param {{issues: Array}} review
+ * @returns {Array}
+ */
+export function blockingIssues(review) {
+  if (!review || !Array.isArray(review.issues)) return [];
+  return review.issues.filter((i) => BLOCKING.has(normalizeSeverity(i?.severity)));
+}

package/src/core/recoverable-error.mjs

@@ -0,0 +1,51 @@
+// src/core/recoverable-error.mjs
+// Single source of truth for "is this pipeline error recoverable, and which class".
+// Recoverable errors are user/transient-fixable (re-auth, wait, top up, retry),
+// NOT bugs. The orchestrator uses the class to drive a retry gate; a null result
+// means "fail as today". Classification reads the thrown message because the real
+// runner (src/core/claude-runner.mjs) folds the underlying headless cause — incl.
+// the 401 auth string captured from the terminal result(is_error:true) event —
+// into its reject text: `claude exited with code N: <cause>` (claude-runner.mjs:298).
+//
+// CAVEAT (accepted, see YAGNI): detection is message-based unless the producer
+// stamped `errorClass` (claude-runner does, on the non-zero-exit path only —
+// spawn-failure errors stay unstamped and keep message-sniff classification), so
+// a genuine bug whose message happens to contain a recoverable keyword (e.g. an
+// app error literally mentioning "network" or "quota") will be classed
+// recoverable and retried. Structured error-code detection is out of scope.
+//
+// @param {Error|string|unknown} err
+// @returns {'auth'|'usage_limit'|'rate_limit'|'quota'|'network'|null}
+export function classifyError(err) {
+  // A producer that saw MORE evidence than the message carries stamps the
+  // verdict directly: claude-runner classifies the FULL stderr stream line-by-
+  // line, then tail-caps the message. Re-sniffing the capped message here could
+  // only lose an early marker (or mint a fake one at the slice boundary), so a
+  // stamp — including an explicit null — is authoritative.
+  if (err && typeof err === 'object' && err.errorClass !== undefined) return err.errorClass;
+  const msg = String((err && err.message) || err || '');
+  if (/\b401\b|invalid authentication|authentication_error|please run .*login|not logged in/i.test(msg)) return 'auth';
+  // Session/usage caps that only clear after a multi-hour reset (the CLI prints
+  // "You've hit your session limit · resets 6pm"). Distinct from rate_limit (a
+  // few-second 429/overloaded burst) because retrying is futile — the orchestrator
+  // PAUSES on this class instead of burning the retry budget. Kept narrow enough
+  // not to swallow the generic "usage limit reached" billing case (-> quota).
+  if (/\bsession limit\b|hit your[^.]*\blimit\b|reached your[^.]*\blimit\b|\blimit\b[^.]*\bresets?\b/i.test(msg)) return 'usage_limit';
+  if (/\b429\b|\b529\b|rate.?limit|overloaded/i.test(msg)) return 'rate_limit';
+  if (/credit balance|usage limit|quota|insufficient_quota|billing/i.test(msg)) return 'quota';
+  if (/ECONNRESET|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|EAI_AGAIN|EPIPE|socket hang up|fetch failed|network|connection (refused|reset|closed|error)|closed mid-response|response above may be incomplete/i.test(msg)) return 'network';
+  return null;
+}
+
+// Precedence for folding per-line classes into the one whole-text class — the
+// SAME order as the regex chain above. First-match-wins there equals
+// strongest-class-wins here, because every per-line match (the patterns are
+// unanchored) is also a whole-text match.
+const CLASS_ORDER = ['auth', 'usage_limit', 'rate_limit', 'quota', 'network'];
+
+/** Fold two classification results, keeping the higher-precedence class. */
+export function strongestClass(a, b) {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  return CLASS_ORDER.indexOf(a) <= CLASS_ORDER.indexOf(b) ? a : b;
+}

package/src/core/results.mjs

@@ -0,0 +1,188 @@
+// src/core/results.mjs
+// Layer 1 (mechanical) results view: pure deterministic assembler + git-backed
+// builder + persistence/read accessors. No model call in this path — rebuilding
+// assembleResults on the same patch + reviews yields byte-identical JSON.
+import { writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { recordArtifact, resolvePipelineId, readPipelineExtras } from './artifacts.mjs';
+
+const NEW_STATUS = new Set(['A', 'C']);
+
+export const RESULTS_FILE = 'results.json';
+export const DIFF_PATCH_FILE = 'diff-patch.patch';
+export const OVERVIEW_FILE = 'overview.json';
+
+/** Canonical retained-work patch filename; a null/empty key yields the bare name. */
+export function retainedWorkPatchName(projectKey = null) {
+  const suffix = projectKey ? `-${String(projectKey).replace(/[^a-zA-Z0-9._-]+/g, '-')}` : '';
+  return `retained-work${suffix}.patch`;
+}
+
+/** Bucket name-status rows into new/changed and sum line counts from numstat. */
+export function bucketFiles(nameStatus, numstat) {
+  const newFiles = [];
+  const changedFiles = [];
+  let linesAdded = 0, linesRemoved = 0, filesDeleted = 0;
+  for (const row of nameStatus) {
+    const n = numstat.get(row.path) || { added: 0, removed: 0, binary: false };
+    linesAdded += n.added; linesRemoved += n.removed;
+    if (row.status === 'D') filesDeleted += 1;
+    const base = { path: row.path, status: row.status };
+    if (!n.binary) { base.added = n.added; base.removed = n.removed; } else base.binary = true;
+    if (NEW_STATUS.has(row.status)) {
+      newFiles.push(base);
+    } else {
+      if (row.from) base.from = row.from;
+      base.issues = [];
+      changedFiles.push(base);
+    }
+  }
+  newFiles.sort((a, b) => a.path.localeCompare(b.path));
+  changedFiles.sort((a, b) => a.path.localeCompare(b.path));
+  return {
+    newFiles,
+    changedFiles,
+    counts: {
+      filesNew: newFiles.length,
+      filesChanged: changedFiles.length,
+      filesDeleted,
+      linesAdded,
+      linesRemoved,
+    },
+  };
+}
+
+/** Keep only the highest-cycle review row per kind. */
+function latestPerKind(reviews) {
+  const byKind = new Map();
+  for (const r of reviews) {
+    const cur = byKind.get(r.kind);
+    if (!cur || r.cycle > cur.cycle) byKind.set(r.kind, r);
+  }
+  return [...byKind.values()];
+}
+
+const SEV_RANK = { critical: 0, major: 1 };
+
+/** Critical+major issues, latest cycle per kind, deduped by severity|title, sorted. */
+export function selectKeyChecks(reviews) {
+  const latest = latestPerKind(reviews);
+  const seen = new Map(); // key -> check
+  let seq = 0;
+  for (const row of latest) {
+    for (const iss of row.issues || []) {
+      if (iss.severity !== 'critical' && iss.severity !== 'major') continue;
+      const key = `${iss.severity}|${(iss.title || '').toLowerCase()}`;
+      const existing = seen.get(key);
+      if (existing) {
+        if (!existing.kind.split(',').includes(row.kind)) existing.kind += `,${row.kind}`;
+        continue;
+      }
+      seen.set(key, {
+        id: `check-${seq++}`,
+        severity: iss.severity,
+        title: iss.title,
+        detail: iss.detail,
+        location: iss.location,
+        kind: row.kind,
+        cycle: row.cycle,
+      });
+    }
+  }
+  return [...seen.values()].sort((a, b) =>
+    (SEV_RANK[a.severity] - SEV_RANK[b.severity]) ||
+    (Number(a.id.slice(6)) - Number(b.id.slice(6))));
+}
+
+/** Minor+suggestion issues from the latest cycle per kind. */
+export function splitNitpicks(reviews) {
+  const out = [];
+  for (const row of latestPerKind(reviews)) {
+    for (const iss of row.issues || []) {
+      if (iss.severity === 'minor' || iss.severity === 'suggestion') {
+        out.push({ severity: iss.severity, title: iss.title, kind: row.kind });
+      }
+    }
+  }
+  return out;
+}
+
+function basename(p) { const i = p.lastIndexOf('/'); return i < 0 ? p : p.slice(i + 1); }
+
+/** Best-effort substring link of checks to changed/new files. Mutates both. */
+export function linkIssues(checks, files) {
+  const all = [...files.changedFiles, ...files.newFiles];
+  for (const c of checks) {
+    if (!c.location) continue;
+    const hit = all.find((f) => c.location.includes(f.path) || c.location.includes(basename(f.path)));
+    if (hit) {
+      c.file = hit.path;
+      if (Array.isArray(hit.issues)) hit.issues.push(c.id);
+    }
+  }
+}
+
+/** Build the full single-project results object. Pure + deterministic. */
+export function assembleResults({ nameStatus, numstat, reviews }) {
+  const files = bucketFiles(nameStatus, numstat);
+  const keyThingsToCheck = selectKeyChecks(reviews);
+  const nitpicks = splitNitpicks(reviews);
+  linkIssues(keyThingsToCheck, files);
+  return {
+    summary: {
+      ...files.counts,
+      blockingIssues: keyThingsToCheck.length,
+      nitpicks: nitpicks.length,
+    },
+    newFiles: files.newFiles,
+    changedFiles: files.changedFiles,
+    keyThingsToCheck,
+    nitpicks,
+  };
+}
+
+/** Map [{projectKey, results}] -> { <projectKey>: results }. */
+export function buildPerProject(members) {
+  const out = {};
+  for (const m of members) out[m.projectKey] = m.results;
+  return out;
+}
+
+/** Sum member summaries into one workspace-level summary. */
+export function rollupSummary(perProject) {
+  const keys = ['filesNew', 'filesChanged', 'filesDeleted', 'linesAdded', 'linesRemoved', 'blockingIssues', 'nitpicks'];
+  const s = Object.fromEntries(keys.map((k) => [k, 0]));
+  for (const r of Object.values(perProject)) for (const k of keys) s[k] += (r.summary?.[k] || 0);
+  return s;
+}
+
+/** Write results.json into the pipeline dir and index it (best-effort index). */
+export async function persistResults(pipelineDir, results) {
+  if (!pipelineDir || !results) return;
+  await writeFile(join(pipelineDir, RESULTS_FILE), JSON.stringify(results, null, 2));
+  const id = resolvePipelineId(pipelineDir);
+  if (id) recordArtifact(id, 'results', RESULTS_FILE);
+}
+
+/** Write the unified diff patch into the pipeline dir and index it. */
+export async function persistDiffPatch(pipelineDir, patch) {
+  if (!pipelineDir || patch == null) return;
+  await writeFile(join(pipelineDir, DIFF_PATCH_FILE), String(patch));
+  const id = resolvePipelineId(pipelineDir);
+  if (id) recordArtifact(id, 'diff-patch', DIFF_PATCH_FILE);
+}
+
+/**
+ * Spec §6 shared context bundle for a finished run — the substrate for the
+ * overview agent and a future Q&A agent. `dir` is the absolute pipeline dir.
+ */
+export async function readRunContextBundle(dir, pipelineId) {
+  const read = async (f) => { try { return await readFile(join(dir, f), 'utf8'); } catch { return null; } };
+  const resultsTxt = await read(RESULTS_FILE);
+  return {
+    diffPatch: await read(DIFF_PATCH_FILE),
+    results: resultsTxt ? JSON.parse(resultsTxt) : null,
+    reviews: readPipelineExtras(pipelineId).reviews || [],
+    audit: null, // audit markdown is rebuilt by buildAuditMarkdown at the API layer
+  };
+}