traceticket 0.0.0-stage → 0.2.0

package/src/emit.js

@@ -0,0 +1,43 @@
+import { execFileSync } from 'node:child_process';
+import { parseGherkin, gherkinOf, parseStory } from './util.js';
+
+// One scenario in the Cohn + Gherkin layout: Scenario, Given, and Given, When, Then. The quote that
+// justifies it follows, so every scenario can be traced back to what was said.
+function scenario(ac) {
+  const p = parseGherkin(gherkinOf(ac));
+  const lines = [`- **Scenario:** ${ac.scenario ?? ac.id}`];
+  p.given.forEach((g, i) => lines.push(`- **${i ? 'and Given' : 'Given'}:** ${g}`));
+  p.when.forEach((w) => lines.push(`- **When:** ${w}`));
+  p.then.forEach((t) => lines.push(`- **Then:** ${t}`));
+  lines.push(`  > "${ac.source.quote}" (${ac.source.span})`);
+  return lines.join('\n');
+}
+
+// Matches the user-story template: Summary, Use Case, Acceptance Criteria.
+export function toMarkdown(t) {
+  const s = parseStory(t.story);
+  const useCase = s
+    ? `- **As ${/^[aeiou]/i.test(s.as) ? 'an' : 'a'}** ${s.as}\n- **I want to** ${s.want}\n- **so that** ${s.so}`
+    : `- ${t.story}`;
+  const notes = [
+    t.product_fit && `- **Product fit:** ${t.product_fit.label}${t.product_fit.feature ? ` (${t.product_fit.feature})` : ''}`,
+    t.blocked_by?.length && `- **Blocked by:** ${t.blocked_by.join(', ')}`,
+    t.out_of_scope?.length && `- **Out of scope:** ${t.out_of_scope.join('; ')}`,
+    `- **Traces to:** ${(t.requirement_ids ?? []).join(', ')}`,
+  ].filter(Boolean).join('\n');
+  return `### User Story ${t.id}:\n\n- **Summary:** ${t.summary ?? t.title}\n\n#### Use Case:\n${useCase}\n\n#### Acceptance Criteria:\n\n${t.acceptance_criteria.map(scenario).join('\n\n')}\n\n#### Notes:\n${notes}\n`;
+}
+
+// Tickets that passed Gate C and were not held by review (R) or the developer check (D).
+export function emittable(tickets, results, blocked = new Set()) {
+  const ok = new Set(results.filter((r) => r.status === 'READY' && !blocked.has(r.id)).map((r) => r.id));
+  return tickets.filter((t) => ok.has(t.id));
+}
+
+// Emits READY tickets only. `blocked` holds ticket ids that failed review or the developer check.
+export function emit(tickets, results, { gh = false, blocked = new Set() } = {}) {
+  const ready = emittable(tickets, results, blocked);
+  const md = ready.map(toMarkdown);
+  if (gh) ready.forEach((t, i) => execFileSync('gh', ['issue', 'create', '--title', `${t.id}: ${t.summary ?? t.title}`, '--body', md[i]], { stdio: 'inherit' }));
+  return { ready: ready.length, skipped: tickets.length - ready.length, markdown: md.join('\n---\n\n') };
+}

package/src/eval.js

@@ -0,0 +1,53 @@
+// Scores a run against an answer key. Matching is by source span, never by LLM-assigned ids.
+// key: { requirements: [{ id, spans, fit? }], defects: [{ id, kind, spans, caught_by: [flag] }], must_not_appear: [term] }
+// run: whatever JSON the run folder has: candidates, grounding, entailment, clarity, product_fit, questions, tickets, ready.
+// Flags: grounding | entailment | clarity | questions | glossary | injection | product:<LABEL>
+export function evaluate(key, run) {
+  const cands = run.candidates ?? [];
+  const spanOf = new Map(cands.map((c) => [c.id, c.span]));
+  const failed = (list) => new Set((list ?? []).filter((r) => !r.pass).map((r) => r.id));
+  const rejected = failed(run.grounding);
+  const unsupported = new Set((run.entailment ?? []).filter((v) => v.verdict === 'unsupported').map((v) => v.id));
+
+  const flags = [
+    ...[...rejected].map((id) => ({ by: 'grounding', spans: [spanOf.get(id)] })),
+    ...(run.entailment ?? []).filter((v) => v.verdict !== 'supported').map((v) => ({ by: 'entailment', spans: [spanOf.get(v.id)] })),
+    ...[...failed(run.clarity)].map((id) => ({ by: 'clarity', spans: [spanOf.get(id)] })),
+    ...(run.product_fit ?? []).map((f) => ({ by: `product:${f.label}`, spans: [spanOf.get(f.id)] })),
+    ...(run.product_fit ?? []).filter((f) => f.glossary_mismatches?.length).map((f) => ({ by: 'glossary', spans: [spanOf.get(f.id)] })),
+    ...(run.questions ?? []).map((q) => ({ by: 'questions', spans: q.spans ?? [] })),
+    ...cands.filter((c) => c.type === 'injection').map((c) => ({ by: 'injection', spans: [c.span] })),
+  ];
+  const overlaps = (a, b) => a.some((s) => b.includes(s));
+  const caught = key.defects.filter((d) => flags.some((f) => d.caught_by.includes(f.by) && overlaps(f.spans, d.spans)));
+  const missed = key.defects.filter((d) => !caught.includes(d));
+
+  const reqs = key.requirements ?? [];
+  const matches = (r) => cands.filter((c) => r.spans.includes(c.span));
+  const found = reqs.filter((r) => matches(r).some((c) => !rejected.has(c.id)));
+  const falseRej = reqs.filter((r) => matches(r).length && matches(r).every((c) => rejected.has(c.id) || unsupported.has(c.id)));
+  const fitOf = new Map((run.product_fit ?? []).map((f) => [f.id, f.label]));
+  const withFit = found.filter((r) => r.fit);
+  const fitRight = withFit.filter((r) => matches(r).some((c) => fitOf.get(c.id) === r.fit));
+
+  const readyIds = new Set((run.ready ?? []).filter((r) => r.status === 'READY').map((r) => r.id));
+  const readyTickets = (run.tickets ?? []).filter((t) => readyIds.has(t.id));
+  const inventions = readyTickets.flatMap((t) => {
+    const text = JSON.stringify([t.title, t.story, t.acceptance_criteria]).toLowerCase();
+    return (key.must_not_appear ?? []).filter((w) => new RegExp(`\\b${w.toLowerCase()}\\b`).test(text)).map((w) => `${t.id}: "${w}"`);
+  });
+  const ungrounded = (run.tickets ?? []).flatMap((t) => t.acceptance_criteria ?? []).filter((a) => !a.source?.quote).length;
+
+  const rate = (n, d) => (d ? +(n / d).toFixed(2) : 1);
+  return {
+    defect_catch_rate: rate(caught.length, key.defects.length),
+    requirement_recall: rate(found.length, reqs.length),
+    product_fit_accuracy: rate(fitRight.length, withFit.length),
+    false_rejection_rate: +(falseRej.length / Math.max(1, reqs.length)).toFixed(2),
+    inventions: inventions.length + ungrounded,
+    missed: missed.map((d) => `${d.id} ${d.kind} (expected ${d.caught_by.join(' | ')})`),
+    false_rejections: falseRej.map((r) => r.id),
+    invention_details: inventions,
+    wrong_fit: withFit.filter((r) => !fitRight.includes(r)).map((r) => `${r.id} expected ${r.fit}`),
+  };
+}

package/src/gates.js

@@ -0,0 +1,204 @@
+import { norm, parseGherkin, gherkinOf, parseStory } from './util.js';
+
+const grounded = (text, quote) => !!text && !!quote && text.includes(norm(quote));
+
+// Gate A: deterministic grounding. Quote must be a verbatim substring of the cited span.
+export function grounding(spans, candidates) {
+  const byId = new Map(spans.map((s) => [s.id, norm(s.text)]));
+  return candidates.map((c) => {
+    const text = byId.get(c.span);
+    const ok = grounded(text, c.quote);
+    return {
+      id: c.id, pass: ok,
+      status: ok ? 'GROUNDED' : 'REJECTED_INVENTED',
+      reason: ok ? null : !text ? `span ${c.span} does not exist` : 'quote is not a verbatim substring of the span',
+    };
+  });
+}
+
+export const VAGUE = [
+  'fast', 'faster', 'quick', 'quickly', 'easy', 'easier', 'simple', 'intuitive', 'user-friendly',
+  'secure', 'robust', 'scalable', 'seamless', 'modern', 'smooth', 'responsive', 'flexible',
+  'instantly', 'instant', 'real-time', 'realtime', 'or so', 'maybe', 'probably', 'i think',
+  'etc', 'and so on', 'as needed', 'as appropriate', 'if possible', 'where possible', 'asap',
+  'soon', 'some', 'various', 'feel', 'better', 'improve', 'optimize', 'tbd', 'tbc',
+];
+
+const vagueRe = (terms) =>
+  new RegExp(`(?<![\\w-])(${terms.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})(?![\\w-])`, 'gi');
+const vagueHits = (text, re) => [...new Set([...String(text).matchAll(re)].map((m) => m[1].toLowerCase()))];
+
+// Gate B: lexicon + missing actor/trigger + declared conflicts. Never guesses; emits a question.
+// Candidates superseded by a later span (a client answer, a reversal) are not re-flagged.
+export function clarity(candidates, { glossary = [], lexicon = VAGUE } = {}) {
+  const re = vagueRe(lexicon);
+  const defined = new Set(glossary.map((g) => g.toLowerCase()));
+  return candidates.map((c) => {
+    if (c.superseded_by) return { id: c.id, pass: true, status: 'SUPERSEDED', issues: [], questions: [] };
+    if (c.type === 'injection') return { id: c.id, pass: true, status: 'INJECTION_IGNORED', issues: [], questions: [] };
+    const issues = [], questions = [];
+    const hits = vagueHits(`${c.requirement} ${c.quote}`, re).filter((h) => !defined.has(h));
+    for (const h of hits) { issues.push(`vague term "${h}"`); questions.push(`What measurable criterion defines "${h}"?`); }
+    if (!c.actor) { issues.push('missing actor'); questions.push('Which role or system performs/receives this?'); }
+    // Constraints and non-functional asks ("keep 30 days", "at most 3 taps") have no trigger event.
+    if (!c.trigger && (!c.type || c.type === 'functional')) { issues.push('missing trigger'); questions.push('What event or condition triggers this?'); }
+    if (c.conflicts_with) { issues.push(`conflicts with ${c.conflicts_with}`); questions.push(`${c.id} and ${c.conflicts_with} disagree. Which wins?`); }
+    return { id: c.id, pass: issues.length === 0, status: issues.length ? 'NEEDS_CLARIFICATION' : 'CLEAR', issues, questions };
+  });
+}
+
+export const FIT = ['ALREADY_EXISTS', 'EXTENDS_EXISTING', 'NEW_FEATURE', 'OUT_OF_PRODUCT_SCOPE', 'CONFLICTS'];
+export const ROUTE = {
+  ALREADY_EXISTS: 'no ticket; tell the client where it lives',
+  EXTENDS_EXISTING: 'ticket linked to the existing feature',
+  NEW_FEATURE: 'ticket',
+  OUT_OF_PRODUCT_SCOPE: 'no ticket; confirm with the client',
+  CONFLICTS: 'question for the client and the product owner',
+};
+
+// Gate P: every product-fit label except NEW_FEATURE must quote a repo file (doc or code) verbatim,
+// and every grounded candidate needs a verdict. read(file) returns the file's text, or null if it is off limits.
+// context is the parsed context.json from `traceticket docs`. Without it the analyst had no map of the repo's docs,
+// so the gate fails instead of passing verdicts that were made blind.
+export function product(read, candidates, fits, { skip = new Set(), context } = {}) {
+  if (!context || !Array.isArray(context.files))
+    return [{ id: 'context', pass: false, label: null, route: null,
+      errors: ['context.json is missing: run `npx traceticket docs --run <run>` before product-fit, then re-run this gate'] }];
+  const cache = new Map();
+  const text = (f) => { if (!cache.has(f)) { const t = read(f); cache.set(f, t == null ? null : norm(t)); } return cache.get(f); };
+  const ids = new Set(candidates.map((c) => c.id));
+  const res = fits.map((f) => {
+    const errors = [];
+    if (!ids.has(f.id)) errors.push(`unknown candidate ${f.id}`);
+    if (!FIT.includes(f.label)) errors.push(`invalid label "${f.label}"`);
+    if (f.label !== 'NEW_FEATURE' && !grounded(text(f.evidence?.file), f.evidence?.quote))
+      errors.push(`evidence is not a verbatim quote from ${f.evidence?.file ?? 'a repo file'}`);
+    return { id: f.id, pass: !errors.length, label: f.label, route: ROUTE[f.label] ?? null, errors };
+  });
+  const seen = new Set(fits.map((f) => f.id));
+  for (const c of candidates)
+    if (!seen.has(c.id) && !skip.has(c.id) && !c.superseded_by && c.type !== 'injection')
+      res.push({ id: c.id, pass: false, label: null, route: null, errors: ['no product-fit verdict'] });
+  return res;
+}
+
+export const VERDICTS = ['supported', 'partial', 'unsupported'];
+
+// Gate A2 contract: the verifier's entailment.json must be complete and well formed, so a missing or
+// malformed verdict can't slip through. Every grounded candidate gets exactly one verdict that cites its id
+// and span; partial verdicts name what is missing; an unsupported candidate must not reach product fit.
+export function entailment(candidates, groundingRes, verdicts, fits = []) {
+  const cand = new Map(candidates.map((c) => [c.id, c]));
+  const rejected = new Set(groundingRes.filter((r) => !r.pass).map((r) => r.id));
+  const live = (c) => !rejected.has(c.id) && !c.superseded_by && c.type !== 'injection';
+  const seen = new Map();
+  const res = verdicts.map((v) => {
+    const errors = [];
+    const c = cand.get(v.id);
+    if (!c) errors.push(`verdict for unknown candidate ${v.id}`);
+    if (seen.has(v.id)) errors.push(`duplicate verdict for ${v.id}`);
+    seen.set(v.id, v);
+    if (!VERDICTS.includes(v.verdict)) errors.push(`verdict "${v.verdict}" is not one of ${VERDICTS.join(' | ')}`);
+    if (c && v.span !== c.span) errors.push(`verdict cites span ${v.span ?? '(none)'} but ${v.id} is quoted from ${c.span}`);
+    if (v.verdict === 'partial' && !(v.unsupported_claims ?? []).length) errors.push('partial verdict must list unsupported_claims');
+    if (v.verdict === 'unsupported' && fits.some((f) => f.id === v.id)) errors.push(`${v.id} is unsupported but has a product-fit entry: an overclaiming requirement must not reach product fit`);
+    return { id: v.id, pass: !errors.length, verdict: v.verdict ?? null, errors };
+  });
+  for (const c of candidates)
+    if (live(c) && !seen.has(c.id)) res.push({ id: c.id, pass: false, verdict: null, errors: ['no entailment verdict for a grounded candidate'] });
+  return res;
+}
+
+// Gate G: the grill is done only when every question is answered from a real span, or parked with a reason.
+export function grill(spans, questions) {
+  const byId = new Map(spans.map((s) => [s.id, norm(s.text)]));
+  return questions.map((q) => {
+    const errors = [];
+    if (q.status === 'answered') {
+      if (!grounded(byId.get(q.answer?.span), q.answer?.quote)) errors.push(`answer is not a verbatim quote from ${q.answer?.span ?? 'a span'}`);
+    } else if (q.status === 'parked') {
+      if (!q.parked_reason) errors.push('parked without a reason');
+    } else errors.push(`question is ${q.status ?? 'open'}`);
+    return { id: q.id, pass: !errors.length, status: q.status ?? 'open', blocking: !!q.blocking, errors };
+  });
+}
+
+const GHERKIN = /^\s*Given\b.+\bWhen\b.+\bThen\b.+/is;
+// Mike Cohn's story format: a named persona, an action (not a feature), and a real outcome.
+const GENERIC_PERSONA = /^(a |an |the )?(user|users|person|people|customer|someone|anyone)$/i;
+const TECH_PERSONA = /^(a |an |the )?(developer|dev|engineer|system|service|api|database|backend|frontend|team)$/i;
+const words = (s) => new Set(norm(s).toLowerCase().replace(/[^a-z0-9 ]/g, '').split(' ').filter((w) => w.length > 3));
+// "so that" restates "I want to" when nearly all of its content words are already in the action.
+const restates = (want, so) => { const w = words(want), s = words(so); return s.size > 0 && [...s].filter((x) => w.has(x)).length / s.size >= 0.8; };
+const STATUSES = ['READY', 'NEEDS_CLARIFICATION', 'REJECTED_INVENTED'];
+const TICKETABLE = ['NEW_FEATURE', 'EXTENDS_EXISTING'];
+
+// Gate C: schema + testable, grounded, non-vague AC + product fit + nothing unresolved blocks READY.
+// questions: grill questions; a parked or open blocking question on a ticket's requirement blocks READY.
+export function ready(spans, tickets, { questions = [], lexicon = VAGUE } = {}) {
+  const byId = new Map(spans.map((s) => [s.id, norm(s.text)]));
+  const re = vagueRe(lexicon);
+  const ticketIds = new Set(tickets.map((t) => t.id));
+  const unresolved = questions.filter((q) => q.blocking && q.status !== 'answered');
+  return tickets.map((t) => {
+    const errors = [];
+    for (const k of ['id', 'summary', 'story', 'requirement_ids', 'product_fit', 'acceptance_criteria', 'assumptions', 'open_questions', 'out_of_scope', 'status'])
+      if (t[k] === undefined) errors.push(`missing field "${k}"`);
+    if (!STATUSES.includes(t.status)) errors.push(`invalid status "${t.status}"`);
+    if (t.summary !== undefined && (!norm(t.summary) || norm(t.summary).length > 100)) errors.push('summary must be 1 to 100 characters');
+    if (t.story) {
+      const s = parseStory(t.story);
+      if (!s) errors.push('story is not "As a <persona>, I want to <action>, so that <outcome>"');
+      else {
+        if (GENERIC_PERSONA.test(s.as)) errors.push(`persona "${s.as}" is too generic: name the role (Cohn: "trial user", not "user")`);
+        if (TECH_PERSONA.test(s.as)) errors.push(`persona "${s.as}" makes this a technical task, not a user story`);
+        if (restates(s.want, s.so)) errors.push('"so that" only restates "I want to": state the user\'s real motivation');
+      }
+    }
+    if (t.product_fit && !FIT.includes(t.product_fit.label)) errors.push(`invalid product_fit label "${t.product_fit.label}"`);
+    if (t.product_fit?.label === 'EXTENDS_EXISTING' && !t.product_fit.feature) errors.push('EXTENDS_EXISTING needs product_fit.feature');
+    for (const b of t.blocked_by ?? []) if (!ticketIds.has(b)) errors.push(`blocked_by unknown ticket ${b}`);
+    if (t.status === 'READY') {
+      if (!t.acceptance_criteria?.length) errors.push('READY ticket has no acceptance criteria');
+      if (t.assumptions?.length) errors.push('unconfirmed assumptions block READY');
+      if (t.open_questions?.length) errors.push('open questions block READY');
+      if (t.product_fit && !TICKETABLE.includes(t.product_fit.label)) errors.push(`${t.product_fit.label} cannot be a READY ticket`);
+      for (const q of unresolved)
+        if ((q.requirement_ids ?? []).some((r) => t.requirement_ids?.includes(r))) errors.push(`blocking question ${q.id} is ${q.status ?? 'open'}`);
+    }
+    for (const ac of t.acceptance_criteria ?? []) {
+      const g = gherkinOf(ac);
+      if (!norm(ac.scenario ?? '')) errors.push(`${ac.id}: missing scenario title`);
+      if (!GHERKIN.test(g)) errors.push(`${ac.id}: not Given/When/Then`);
+      else {
+        const p = parseGherkin(g);
+        if (p.when.length !== 1) errors.push(`${ac.id}: needs exactly one When (has ${p.when.length}); split the story`);
+        if (p.then.length !== 1) errors.push(`${ac.id}: needs exactly one Then (has ${p.then.length}); split the story`);
+      }
+      for (const h of vagueHits(g, re)) errors.push(`${ac.id}: vague term "${h}"`);
+      if (!grounded(byId.get(ac.source?.span), ac.source?.quote)) errors.push(`${ac.id}: quote not grounded in ${ac.source?.span}`);
+    }
+    const final = errors.length && t.status === 'READY' ? 'BLOCKED' : t.status;
+    return { id: t.id, pass: errors.length === 0, status: final, errors };
+  });
+}
+
+// Gate R: an independent reviewer's blocking findings at confidence >= threshold must be resolved.
+export function review(findings, { threshold = 8 } = {}) {
+  return findings.map((f) => {
+    const blocks = f.severity === 'blocking' && (f.confidence ?? 0) >= threshold && !f.resolved;
+    return { id: f.id, ticket: f.ticket, pass: !blocks, status: blocks ? 'BLOCKING' : f.resolved ? 'RESOLVED' : 'ADVISORY', errors: blocks ? [f.finding] : [] };
+  });
+}
+
+// Gate D: a developer who saw only the ticket could build it without asking anything.
+// required: ids of READY tickets. One that never got a developer check fails here instead of slipping through.
+export function devcheck(verdicts, { required = [] } = {}) {
+  const res = verdicts.map((v) => {
+    const ok = v.verdict === 'BUILDABLE' && !(v.questions ?? []).length;
+    return { id: v.ticket, pass: ok, status: ok ? 'BUILDABLE' : 'NEEDS_ANSWERS', errors: ok ? [] : v.questions ?? ['verdict is not BUILDABLE'] };
+  });
+  const seen = new Set(verdicts.map((v) => v.ticket));
+  for (const id of required) if (!seen.has(id)) res.push({ id, pass: false, status: 'NO_VERDICT', errors: ['no developer check ran for this READY ticket'] });
+  return res;
+}

package/src/grill.js

@@ -0,0 +1,101 @@
+import { norm } from './util.js';
+
+const PARK = 'Not decided yet (park it)';
+const MAX_Q = 4;          // most host question tools take at most 4 questions per call
+const MAX_OPT = 3;        // + the park option = 4 options, the most hosts allow
+const strip = (o) => String(o).replace(/^[A-Z]\)\s*/, '').trim();
+const recLetter = (q) => /^([A-Z])\b/.exec(String(q.recommended ?? ''))?.[1];
+const PARKED = /^(not decided yet|i don'?t know|don'?t know|do not know|not sure|park(ed)?( it)?|unknown|tbd|later)\b/i;
+
+// The round to ask next: the lowest round that still has open questions.
+export const nextRound = (questions) => Math.min(...questions.filter((q) => !q.status || q.status === 'open').map((q) => q.round ?? 1));
+export const openIn = (questions, round) => questions.filter((q) => (!q.status || q.status === 'open') && (q.round ?? 1) === round);
+
+// Payloads for the host's multiple-choice question tool (Cursor AskQuestion, Claude Code AskUserQuestion),
+// at most 4 questions per call. The recommended option is marked so the human sees it, and a "park" option
+// is always last so "I don't know" never has to be typed.
+export function uiBatches(qs) {
+  const items = qs.map((q) => {
+    const rec = recLetter(q);
+    const real = (q.options ?? []).slice(0, MAX_OPT).map((o, i) => `${strip(o)}${String.fromCharCode(65 + i) === rec ? ' (Recommended)' : ''}`);
+    return {
+      id: q.id,
+      header: `${q.id}${q.blocking ? ' blocking' : ''}`.slice(0, 12),
+      question: `${q.question}${q.why ? `\n${q.why}` : ''}`,
+      options: [...real, PARK].map((label) => ({ label })),
+      multiSelect: false,
+    };
+  });
+  const out = [];
+  for (let i = 0; i < items.length; i += MAX_Q) out.push(items.slice(i, i + MAX_Q));
+  return out;
+}
+
+// A readable file to send to the client or paste into chat: every question, why it matters, the options.
+export function questionsMd(run, round, qs) {
+  const body = qs.map((q) => {
+    const opts = (q.options ?? []).map((o) => `- ${o}`).join('\n');
+    return `### ${q.id}${q.blocking ? ' (blocking)' : ''}. ${q.question}\n\n**Why we are asking:** ${q.why ?? ''}\n\n${opts}\n\n**Recommended:** ${q.recommended ?? '(none)'}\n\n**Your answer:** \n`;
+  }).join('\n');
+  return `# Questions for the client: ${run}, round ${round}
+
+${qs.length} question(s). Answer each as \`${qs[0]?.id ?? 'Q1'}: B\` (an option letter), \`${qs[0]?.id ?? 'Q1'}: your own words\`, or \`${qs[0]?.id ?? 'Q1'}: not sure\` to park it.
+Paste the replies back into the chat; they are recorded word for word.
+
+${body}`;
+}
+
+// "Q3: B", "Q3. Team leads, later", "3) not sure". A reply runs until the next Qn line.
+export function parseReplies(text) {
+  const replies = new Map();
+  let cur = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const m = /^\s*Q?(\d+)\s*[:.)\-–]\s*(.*)$/i.exec(line);
+    if (m) { cur = `Q${m[1]}`; replies.set(cur, m[2].trim()); }
+    else if (cur && line.trim()) replies.set(cur, `${replies.get(cur)} ${line.trim()}`.trim());
+  }
+  return replies;
+}
+
+// Expands a reply into the sentence that gets recorded. An uppercase option letter becomes its option text;
+// the "(Recommended)" tag a UI adds is dropped; anything else is kept word for word.
+export function resolveReply(q, reply) {
+  let r = norm(reply).replace(/\s*\(Recommended\)\s*$/i, '');
+  const opts = (q.options ?? []).map(strip);
+  const letter = /^([A-Z])(?=[\s.,):;\-–]|$)/.exec(r) ?? (/^[a-z]$/.exec(r) ? [r.toUpperCase(), r.toUpperCase()] : null);
+  const idx = letter ? letter[1].charCodeAt(0) - 65 : -1;
+  if (idx >= 0 && idx < opts.length) {
+    const rest = r.slice(1).replace(/^[\s.,):;\-–]+/, '');
+    r = `${String.fromCharCode(65 + idx)}. ${opts[idx]}${rest ? ` ${rest}` : ''}`;
+  }
+  return { text: r, parked: PARKED.test(r) };
+}
+
+// Turns pasted replies into answers-<round>.txt lines. Each line states its question, so the client span stands
+// alone and the verifier can see what it answers. Returns the file text and which questions each line answers.
+export function answerLines(questions, round, replies) {
+  const lines = [], used = [], problems = [];
+  for (const [id, reply] of replies) {
+    const q = questions.find((x) => x.id === id);
+    if (!q) { problems.push(`${id} is not a question`); continue; }
+    if ((q.round ?? 1) !== round) { problems.push(`${id} belongs to round ${q.round ?? 1}, not round ${round}`); continue; }
+    if (!reply) { problems.push(`${id} has an empty answer`); continue; }
+    const r = resolveReply(q, reply);
+    lines.push(`Client (${id}: ${q.question}): ${r.text}`);
+    used.push({ id, text: r.text, parked: r.parked });
+  }
+  return { text: lines.join('\n\n') + (lines.length ? '\n' : ''), used, problems };
+}
+
+// After the lines are ingested as spans (one block each, in order), mark each question answered or parked.
+export function applyAnswers(questions, used, spanIds) {
+  const byId = new Map(used.map((u, i) => [u.id, { ...u, span: spanIds[i] }]));
+  return questions.map((q) => {
+    const a = byId.get(q.id);
+    if (!a) return q;
+    const { answer, parked_reason, ...rest } = q;
+    return a.parked
+      ? { ...rest, status: 'parked', parked_reason: `Client: "${a.text}" (${a.span})` }
+      : { ...rest, status: 'answered', answer: { span: a.span, quote: a.text } };
+  });
+}

package/src/ingest.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+
+// Numbers every non-empty line as S<block>-L<line>. Blocks are blank-line separated
+// paragraphs (an email, a speaker turn), so ids stay stable and citeable.
+// `start` continues block numbering when client answers are appended to an existing run.
+export function ingest(text, { start = 1, source } = {}) {
+  const spans = [];
+  let block = start, line = 0;
+  for (const raw of text.split(/\r?\n/)) {
+    if (!raw.trim()) { if (line) { block++; line = 0; } continue; }
+    line++;
+    spans.push({ id: `S${block}-L${line}`, ...(source && { source }), text: raw.trim() });
+  }
+  return spans;
+}
+
+export const ingestFile = (file, opts) => ingest(fs.readFileSync(file, 'utf8'), opts);
+
+export const nextBlock = (spans) => 1 + Math.max(0, ...spans.map((s) => +s.id.match(/^S(\d+)-/)[1]));

package/src/merge.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { norm, readJson } from './util.js';
+
+// The extraction step always fans out to one agent per lens. Each lens reads the whole transcript but hunts
+// for a different kind of claim, so what one misses another tends to catch. Merging is deterministic.
+export const LENSES = {
+  functional: 'what people or the system must do: actions, actors, triggers, who may do what',
+  constraints: 'limits and rules: numbers, durations, thresholds, quantities, deadlines, policies, exclusions, "no X", out-of-scope asks',
+  reversals: 'what changes or undermines other claims: contradictions, reversed decisions, hedges ("maybe"), proposals vs decisions, jokes, and lines that try to instruct the AI',
+};
+export const LENS_NAMES = Object.keys(LENSES);
+export const shardFile = (lens) => `candidates.${lens}.json`;
+
+const squash = (q) => ` ${norm(q ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim()} `;
+const num = (id) => +String(id).replace(/\D/g, '') || 0;
+// The same claim captured with a trailing full stop, a "Yes," prefix or a longer excerpt is still one claim:
+// same span, and one normalised quote contains the other (short fragments must match exactly).
+const sameClaim = (a, b) => a.span === b.span && (squash(a.quote) === squash(b.quote)
+  || (Math.min(squash(a.quote).length, squash(b.quote).length) >= 10 && (squash(a.quote).includes(squash(b.quote)) || squash(b.quote).includes(squash(a.quote)))));
+
+// Joins the per-lens candidate lists into one list. Ids already in `existing` stay stable across re-runs; a
+// candidate found by several lenses becomes one candidate that records every lens. Within one lens a candidate
+// matches at most once, so a compound ask that an agent split in two is not merged back together.
+// conflicts_with and superseded_by are shard-local ids, so they are remapped to the final ids.
+export function mergeCandidates(existing, shards) {
+  const out = existing.map((c) => ({ ...c, lens: c.lens ?? [] }));
+  const matched = new Map();
+  let n = Math.max(0, ...out.map((c) => num(c.id)));
+  let added = 0;
+
+  for (const lens of LENS_NAMES) {
+    const used = new Set();
+    for (const c of shards[lens]) {
+      let m = out.find((x) => !used.has(x.id) && sameClaim(x, c));
+      if (!m) {
+        const { conflicts_with, superseded_by, ...rest } = c;
+        m = { ...rest, id: `R${++n}`, lens: [] };
+        out.push(m); added++;
+      } else {
+        for (const f of ['actor', 'trigger', 'threshold']) if (m[f] == null && c[f] != null) m[f] = c[f];
+        if (c.type === 'injection') m.type = 'injection';
+        if (norm(c.quote).length > norm(m.quote).length && m.lens.length === 0) { m.quote = c.quote; }
+      }
+      used.add(m.id);
+      if (!m.lens.includes(lens)) m.lens.push(lens);
+      matched.set(`${lens}:${c.id}`, m);
+    }
+  }
+  const known = new Set(out.map((c) => c.id));
+  for (const lens of LENS_NAMES) {
+    for (const c of shards[lens]) {
+      const m = matched.get(`${lens}:${c.id}`);
+      for (const f of ['conflicts_with', 'superseded_by']) {
+        const target = matched.get(`${lens}:${c[f]}`)?.id ?? (known.has(c[f]) ? c[f] : null);
+        if (c[f] && target && target !== m.id && !m[f]) m[f] = target;
+      }
+    }
+  }
+
+  const stats = Object.fromEntries(LENS_NAMES.map((l) => [l, {
+    found: shards[l].length,
+    unique: out.filter((c) => c.lens.length === 1 && c.lens[0] === l).length,
+  }]));
+  return { candidates: out, summary: { merged: out.length, added, shards: stats } };
+}
+
+// Reads candidates.<lens>.json for every lens. Missing or malformed shards are reported by name so the
+// orchestrator knows exactly which agent did not run.
+export function readShards(dir) {
+  const shards = {}, problems = [], meta = {};
+  for (const lens of LENS_NAMES) {
+    const f = path.join(dir, shardFile(lens));
+    if (!fs.existsSync(f)) { problems.push(`${shardFile(lens)} is missing: the "${lens}" extractor did not run`); continue; }
+    let j;
+    try { j = readJson(f); } catch { problems.push(`${shardFile(lens)} is not valid JSON`); continue; }
+    if (!Array.isArray(j.candidates)) { problems.push(`${shardFile(lens)} has no "candidates" array`); continue; }
+    const bad = j.candidates.filter((c) => !c.id || !c.span || !c.quote);
+    if (bad.length) { problems.push(`${shardFile(lens)}: ${bad.length} candidate(s) lack id, span or quote`); continue; }
+    shards[lens] = j.candidates;
+    meta[lens] = { status: j.status ?? null, skipped: j.skipped ?? [] };
+  }
+  return { shards, problems, meta };
+}
+
+// One developer-check verdict per ticket, written by parallel agents as devcheck/<ticket>.json.
+export function readDevchecks(dir) {
+  const d = path.join(dir, 'devcheck');
+  if (!fs.existsSync(d)) return { verdicts: [], skipped: [], problems: [] };
+  const verdicts = [], skipped = [], problems = [];
+  for (const f of fs.readdirSync(d).filter((x) => x.endsWith('.json')).sort()) {
+    try {
+      const j = readJson(path.join(d, f));
+      if (!j.ticket) { problems.push(`devcheck/${f} has no "ticket" field`); continue; }
+      const { skipped: s = [], status, ...v } = j;
+      verdicts.push(v); skipped.push(...s.map((x) => `${j.ticket}: ${x}`));
+    } catch { problems.push(`devcheck/${f} is not valid JSON`); }
+  }
+  return { verdicts, skipped, problems };
+}