@dzhechkov/harness-core 0.3.148 → 0.3.150

package/src/reqe.ts

@@ -0,0 +1,243 @@
+/**
+ * re-QE debt — the pure half of `dz reqe` (backlog 6b40e667, goal honest-quality).
+ *
+ * The cross-model-QE guard ("the model that writes code must not self-review") is an ADR-named
+ * safety property of the feature-adr pipeline. The usage-adaptive override consciously SUSPENDS it
+ * (FR-2.9): at >= threshold usage every remaining stage — including Step-8 QE — switches to Codex,
+ * so coder and reviewer become the SAME family. The rule doc said "run an independent re-QE after
+ * limits reset" — a human instruction on the weakest detection layer. This module turns it into a
+ * DEBT with a lifecycle:
+ *
+ *   emit   — the workflow records features/<slug>/.fa-state/reqe-due.json when Step-8 actually ran
+ *            same-family under the override (not on every switch — a switch before Step 8 that
+ *            still got cross-family QE creates no debt);
+ *   list   — `dz reqe` scans the debts; `dz usage` surfaces the count so the moment limits free up
+ *            is the moment the debt is visible;
+ *   brief  — `dz reqe --slug <s>` prints a ready cross-family review brief (the OTHER family than
+ *            the coder);
+ *   settle — `dz reqe --slug <s> --done --report <file>` clears the debt FAIL-CLOSED: only against
+ *            an existing, non-trivial report that names a grade; the settlement is appended to
+ *            08_qe_report.md so the artifact trail closes.
+ *
+ * HONEST SCOPE: nothing here re-runs QE automatically (no background spend — the human decides);
+ * the same-family CLAUDE belt fallback (codex unavailable) is out of scope by design — it is
+ * already logged loudly at run time and is not a limit-pressure artifact; runs from before this
+ * feature carry no marker and are UNDETERMINABLE, not debt-free.
+ */
+
+export const REQE_SCHEMA = 'reqe-due-1';
+
+export const REQE_SCOPE =
+  'scope: debt is emitted only when Step-8 QE actually ran on the coder’s own family under the ' +
+  'usage override; settling requires a graded cross-family report (fail-closed); nothing re-runs QE ' +
+  'automatically.';
+
+export type ModelFamily = 'claude' | 'openai';
+
+/** Family classification shared with the workflow's acFamOf (codex/gpt/openai markers ⇒ openai).
+ * DELIBERATELY binary over the workflow's own CONTROLLED vocabulary (coderUsed ∈ claude | codex |
+ * codex-fallback; qeReviewerUsed ∈ claude | codex) — this is never fed arbitrary model ids, so the
+ * claude default is the correct reading of "not a codex marker", not a fail-open (Codex QE #11,
+ * accepted with this documentation). */
+export function modelFamily(spec: string | null | undefined): ModelFamily {
+  return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'openai' : 'claude';
+}
+
+export interface ReqeEmitDecision {
+  emit: boolean;
+  reason: string;
+}
+
+/** Emit iff the QE stage label carries the workflow's ' (usage-switched)' marker AND the reviewer
+ * family equals the coder family. Marker-only (cross-family survived the switch) or same-family
+ * WITHOUT the marker (the codex-unavailable Claude belt — degraded loudly at run time, not a
+ * limit-pressure artifact) both create NO debt. */
+export function shouldEmitReqeDebt(input: {
+  coderUsed: string | null | undefined;
+  qeReviewerUsed: string | null | undefined;
+  qeModelLabel: string | null | undefined;
+}): ReqeEmitDecision {
+  const switched = /\(usage-switched\)/.test(String(input.qeModelLabel ?? ''));
+  const coderFam = modelFamily(input.coderUsed);
+  const qeFam = modelFamily(input.qeReviewerUsed);
+  if (switched && coderFam === qeFam) {
+    return {
+      emit: true,
+      reason:
+        'usage-switched self-review: Step-8 QE ran on the coder’s own family (' + coderFam +
+        ') under the limit override — the cross-model guard was suspended (FR-2.9)',
+    };
+  }
+  if (switched) return { emit: false, reason: 'usage-switched but QE stayed cross-family (' + qeFam + ' vs coder ' + coderFam + ')' };
+  if (coderFam === qeFam) return { emit: false, reason: 'same-family without the usage override (belt degrade — logged loudly at run time; out of re-QE-debt scope)' };
+  return { emit: false, reason: 'cross-family QE ran' };
+}
+
+export interface ReqeDebt {
+  schema: typeof REQE_SCHEMA;
+  slug: string;
+  coderFamily: ModelFamily;
+  qeFamily: ModelFamily;
+  qeGrade: string | null;
+  reason: string;
+  emittedAt: string | null;
+  /** The emitting run's identity (the workflow's qe inputHash). Lets a LATER run on the same slug
+   * emit a fresh debt even though an older settlement exists, while the SAME run's resume never
+   * re-opens a debt its settlement already covered (Codex QE round-2 #2). Optional: debts from
+   * before this field settle normally. */
+  runStamp?: string | null;
+}
+
+/** Build the debt record (the workflow serializes this; emittedAt is stamped by the writer agent's
+ * shell `date`, so the sandbox needs no Date). */
+export function buildReqeDebt(input: {
+  slug: string;
+  coderUsed: string | null | undefined;
+  qeReviewerUsed: string | null | undefined;
+  qeGrade: string | null | undefined;
+  reason: string;
+  emittedAt?: string | null;
+}): ReqeDebt {
+  return {
+    schema: REQE_SCHEMA,
+    slug: input.slug,
+    coderFamily: modelFamily(input.coderUsed),
+    qeFamily: modelFamily(input.qeReviewerUsed),
+    qeGrade: input.qeGrade == null || String(input.qeGrade).trim() === '' ? null : String(input.qeGrade).trim(),
+    reason: input.reason,
+    emittedAt: input.emittedAt ?? null,
+  };
+}
+
+/** Parse + validate a debt file's text. null = not a valid debt (the caller reports it as
+ * malformed — a corrupt debt file is NAMED, never silently dropped). */
+export function parseReqeDebt(text: string): ReqeDebt | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(String(text ?? ''));
+  } catch {
+    return null;
+  }
+  const d = raw as Partial<ReqeDebt>;
+  if (!d || typeof d !== 'object') return null;
+  if (d.schema !== REQE_SCHEMA) return null;
+  if (typeof d.slug !== 'string' || d.slug.trim() === '') return null;
+  if (d.coderFamily !== 'claude' && d.coderFamily !== 'openai') return null;
+  if (d.qeFamily !== 'claude' && d.qeFamily !== 'openai') return null;
+  if (typeof d.reason !== 'string' || d.reason.trim() === '') return null;
+  return {
+    schema: REQE_SCHEMA,
+    slug: d.slug,
+    coderFamily: d.coderFamily,
+    qeFamily: d.qeFamily,
+    qeGrade: typeof d.qeGrade === 'string' && d.qeGrade.trim() !== '' ? d.qeGrade.trim() : null,
+    reason: d.reason,
+    emittedAt: typeof d.emittedAt === 'string' && d.emittedAt.trim() !== '' ? d.emittedAt : null,
+    runStamp: typeof d.runStamp === 'string' && d.runStamp.trim() !== '' ? d.runStamp : null,
+  };
+}
+
+export interface ReqeBrief {
+  reviewFamily: ModelFamily;
+  header: string;
+  instructions: readonly string[];
+  codexCmdTemplate: string | null;
+}
+
+/** The ready-to-run cross-family review brief. Review family = the OTHER family than the CODER
+ * (reviewing with the other-than-reviewer family would let a codex-coded, codex-reviewed run be
+ * "re-reviewed" by codex again). */
+export function buildReqeBrief(debt: ReqeDebt, artifactsDir: string): ReqeBrief {
+  const reviewFamily: ModelFamily = debt.coderFamily === 'openai' ? 'claude' : 'openai';
+  const files = [
+    artifactsDir + '/07_code_changes/change_manifest.md',
+    artifactsDir + '/08_qe_report.md',
+    artifactsDir + '/03_adr/',
+  ];
+  const instructions = [
+    'Independent re-QE for "' + debt.slug + '": the recorded Step-8 review ran on the coder’s own family (' + debt.coderFamily + ') under the usage override' + (debt.qeGrade ? ' and graded ' + debt.qeGrade : '') + '.',
+    'Review with the ' + reviewFamily.toUpperCase() + ' family (the OTHER family than the coder — the suspended guard, restored).',
+    'Read: ' + files.join(' , ') + ' plus every file the change manifest lists.',
+    'Adversarially verify: correctness, edge cases, the ADR-named load-bearing property HAS a test, and whether the same-family review missed anything.',
+    'Output: GRADE A-F + numbered findings with file:line and severity; write the report to ' + artifactsDir + '/08b_reqe_report.md.',
+    'Then settle the debt: dz reqe --slug ' + debt.slug + ' --done --report ' + artifactsDir + '/08b_reqe_report.md',
+  ];
+  const codexCmdTemplate = reviewFamily === 'openai'
+    ? 'codex exec -m <probed-id> -c model_reasoning_effort="high" --sandbox read-only "<the brief above>" < /dev/null   # probe the id first: ids are account-specific'
+    : null;
+  return {
+    reviewFamily,
+    header: 're-QE brief for ' + debt.slug + ' (' + (debt.emittedAt ?? 'emitted: unknown') + ')',
+    instructions,
+    codexCmdTemplate,
+  };
+}
+
+export interface ReqeSettlement {
+  ok: boolean;
+  error: string | null;
+  grade: string | null;
+  epilogue: string | null;
+}
+
+/** Extract the verdict grade from a report, or null. LINE-ANCHORED and range-proof (Codex QE #7):
+ * the boilerplate phrase `GRADE A-F` must not read as grade A, so a letter followed by a dash and
+ * another grade letter is rejected; and the grade must head its line (a quoted "do not assign
+ * GRADE A" mid-paragraph is not a verdict). Conflicting distinct grades ⇒ null (ambiguous). */
+export function extractReportGrade(text: string): string | null {
+  // the lookahead rejects RANGES in punctuation form (A-F, A/F) AND word form (A through F,
+  // A to F) — Codex QE round-2 #6: 'GRADE A through F' must not read as grade A
+  const matches = [...String(text ?? '').matchAll(/^\s*(?:\*{0,2}#{0,4}\s*)?GRADE\s*[:=—–-]?\s*([A-F])\b(?!\s*(?:[-–—/]|through|to|thru)\s*[A-F]\b)/gim)];
+  const distinct = new Set(matches.map((m) => (m[1] ?? '').toUpperCase()).filter((g) => g !== ''));
+  if (distinct.size !== 1) return null;
+  return [...distinct][0] ?? null;
+}
+
+/** FAIL-CLOSED settlement validation: the report must be non-trivial (>= 200 chars of substance)
+ * and must NAME exactly one line-anchored grade. A settlement that cannot cite its evidence is
+ * refused — clearing a debt against an empty file would re-open the exact hole this feature closes.
+ * HONEST LIMIT (documented, not hidden): the validator proves the settlement is PROCEDURALLY sound
+ * (a distinct, graded report exists); it cannot prove which model authored the text — attribution
+ * stays with the human running the brief. */
+export function settleReqeDebt(debt: ReqeDebt, reportText: string, reportPath: string): ReqeSettlement {
+  const text = String(reportText ?? '');
+  if (text.trim().length < 200) {
+    return { ok: false, error: 'report too small to be a review (< 200 chars of substance) — refusing to settle', grade: null, epilogue: null };
+  }
+  const grade = extractReportGrade(text);
+  if (grade === null) {
+    return { ok: false, error: 'report names no unambiguous line-anchored GRADE (A-F) — text without exactly one verdict grade is not a verdict; refusing to settle', grade: null, epilogue: null };
+  }
+  const reviewFamily: ModelFamily = debt.coderFamily === 'openai' ? 'claude' : 'openai';
+  const epilogue = [
+    '',
+    '---',
+    '',
+    '## re-QE settlement (cross-model debt cleared)',
+    '',
+    'The original Step-8 review ran on the coder’s own family (' + debt.coderFamily + ') under the',
+    'usage override (' + debt.reason + '). An independent ' + reviewFamily.toUpperCase() + '-family re-QE was performed:',
+    '',
+    '- report: `' + reportPath + '`',
+    '- re-QE grade: **' + grade + '**' + (debt.qeGrade ? ' (same-family grade on record: ' + debt.qeGrade + ')' : ''),
+    '- settled via `dz reqe --done` (fail-closed: an existing graded report is required).',
+    '',
+  ].join('\n');
+  return { ok: true, error: null, grade, epilogue };
+}
+
+/** Render the debt list for `dz reqe` / the `dz usage` surfacing line. */
+export function renderReqeList(debts: readonly ReqeDebt[], malformed: number): string[] {
+  const lines: string[] = [];
+  if (debts.length === 0 && malformed === 0) {
+    lines.push('dz reqe: no re-QE debts — every recorded run kept cross-model QE (or none used the usage override).');
+  } else {
+    lines.push('dz reqe — ' + debts.length + ' unsettled re-QE debt(s):');
+    for (const d of debts) {
+      lines.push('  ' + d.slug + '  coder=' + d.coderFamily + ' qe=' + d.qeFamily + (d.qeGrade ? ' grade=' + d.qeGrade : '') + (d.emittedAt ? '  ' + d.emittedAt : '') + '  → dz reqe --slug ' + d.slug);
+    }
+  }
+  if (malformed > 0) lines.push('  ' + malformed + ' malformed debt file(s) skipped (named, never silent).');
+  lines.push(REQE_SCOPE);
+  return lines;
+}