@dzhechkov/harness-core 0.3.148 → 0.3.150

package/dist/reqe.js

@@ -0,0 +1,197 @@
+/**
+ * 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.';
+/** 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) {
+    return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'openai' : 'claude';
+}
+/** 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) {
+    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' };
+}
+/** 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) {
+    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) {
+    let raw;
+    try {
+        raw = JSON.parse(String(text ?? ''));
+    }
+    catch {
+        return null;
+    }
+    const d = raw;
+    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,
+    };
+}
+/** 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, artifactsDir) {
+    const reviewFamily = 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,
+    };
+}
+/** 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) {
+    // 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, reportText, reportPath) {
+    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 = 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, malformed) {
+    const lines = [];
+    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;
+}
+//# sourceMappingURL=reqe.js.map

package/dist/reqe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reqe.js","sourceRoot":"","sources":["../src/reqe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAExC,MAAM,CAAC,MAAM,UAAU,GACrB,8FAA8F;IAC9F,mGAAmG;IACnG,gBAAgB,CAAC;AAInB;;;;wCAIwC;AACxC,MAAM,UAAU,WAAW,CAAC,IAA+B;IACzD,OAAO,mBAAmB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAOD;;;mDAGmD;AACnD,MAAM,UAAU,kBAAkB,CAAC,KAIlC;IACC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAChD,IAAI,QAAQ,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACnC,OAAO;YACL,IAAI,EAAE,IAAI;YACV,MAAM,EACJ,uEAAuE,GAAG,QAAQ;gBAClF,2EAA2E;SAC9E,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,6CAA6C,GAAG,KAAK,GAAG,YAAY,GAAG,QAAQ,GAAG,GAAG,EAAE,CAAC;IACpI,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,4GAA4G,EAAE,CAAC;IACrK,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;AACxD,CAAC;AAiBD;kDACkD;AAClD,MAAM,UAAU,aAAa,CAAC,KAO7B;IACC,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC;QACzC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,cAAc,CAAC;QAC3C,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QAC3G,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;KACnC,CAAC;AACJ,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,CAAC,GAAG,GAAwB,CAAC;IACnC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACpE,IAAI,CAAC,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACpE,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO;QACL,MAAM,EAAE,WAAW;QACnB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,OAAO,EAAE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QAC3F,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,SAAS,EAAE,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;QAC5F,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;KACzF,CAAC;AACJ,CAAC;AASD;;oCAEoC;AACpC,MAAM,UAAU,cAAc,CAAC,IAAc,EAAE,YAAoB;IACjE,MAAM,YAAY,GAAgB,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACtF,MAAM,KAAK,GAAG;QACZ,YAAY,GAAG,qCAAqC;QACpD,YAAY,GAAG,kBAAkB;QACjC,YAAY,GAAG,UAAU;KAC1B,CAAC;IACF,MAAM,YAAY,GAAG;QACnB,yBAAyB,GAAG,IAAI,CAAC,IAAI,GAAG,+DAA+D,GAAG,IAAI,CAAC,WAAW,GAAG,4BAA4B,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG;QACrN,kBAAkB,GAAG,YAAY,CAAC,WAAW,EAAE,GAAG,4EAA4E;QAC9H,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,6CAA6C;QAC5E,oJAAoJ;QACpJ,yFAAyF,GAAG,YAAY,GAAG,sBAAsB;QACjI,uCAAuC,GAAG,IAAI,CAAC,IAAI,GAAG,mBAAmB,GAAG,YAAY,GAAG,qBAAqB;KACjH,CAAC;IACF,MAAM,gBAAgB,GAAG,YAAY,KAAK,QAAQ;QAChD,CAAC,CAAC,iKAAiK;QACnK,CAAC,CAAC,IAAI,CAAC;IACT,OAAO;QACL,YAAY;QACZ,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC,GAAG,GAAG;QAC5F,YAAY;QACZ,gBAAgB;KACjB,CAAC;AACJ,CAAC;AASD;;;+FAG+F;AAC/F,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,0FAA0F;IAC1F,8EAA8E;IAC9E,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,qGAAqG,CAAC,CAAC,CAAC;IACxJ,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACjG,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAClC,CAAC;AAED;;;;;6CAK6C;AAC7C,MAAM,UAAU,cAAc,CAAC,IAAc,EAAE,UAAkB,EAAE,UAAkB;IACnF,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,iFAAiF,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC9I,CAAC;IACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,qIAAqI,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAClM,CAAC;IACD,MAAM,YAAY,GAAgB,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACtF,MAAM,QAAQ,GAAG;QACf,EAAE;QACF,KAAK;QACL,EAAE;QACF,gDAAgD;QAChD,EAAE;QACF,4DAA4D,GAAG,IAAI,CAAC,WAAW,GAAG,aAAa;QAC/F,kBAAkB,GAAG,IAAI,CAAC,MAAM,GAAG,oBAAoB,GAAG,YAAY,CAAC,WAAW,EAAE,GAAG,8BAA8B;QACrH,EAAE;QACF,aAAa,GAAG,UAAU,GAAG,GAAG;QAChC,mBAAmB,GAAG,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,iCAAiC,GAAG,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACjH,sFAAsF;QACtF,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACpD,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,KAA0B,EAAE,SAAiB;IAC1E,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,qGAAqG,CAAC,CAAC;IACpH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,2BAA2B,CAAC,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,GAAG,UAAU,GAAG,CAAC,CAAC,WAAW,GAAG,MAAM,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QACrM,CAAC;IACH,CAAC;IACD,IAAI,SAAS,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,SAAS,GAAG,wDAAwD,CAAC,CAAC;IAC3G,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-core",
-  "version": "0.3.148",
+  "version": "0.3.150",
   "description": "Shared harness logic - skill loading, additive apply, and the init/sync/verify/doctor operations.",
   "type": "module",
   "license": "MIT",
@@ -32,11 +32,11 @@
     "@dzhechkov/adapter-openclaude": "^0.1.0",
     "@dzhechkov/adapter-opencode": "^0.2.0",
     "yaml": "^2.0.0",
-    "@dzhechkov/adapter-copilot": "0.1.1",
+    "@dzhechkov/adapter-agents-md": "0.1.1",
     "@dzhechkov/adapter-cursor": "0.1.1",
-    "@dzhechkov/adapter-windsurf": "0.1.1",
     "@dzhechkov/adapter-gemini": "0.1.1",
-    "@dzhechkov/adapter-agents-md": "0.1.1",
+    "@dzhechkov/adapter-copilot": "0.1.1",
+    "@dzhechkov/adapter-windsurf": "0.1.1",
     "@dzhechkov/core": "0.2.14",
     "@dzhechkov/memory": "0.2.9"
   },

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4710903a3f0f81d2163062977f6471f29073d2c516209f875c09cc54e75ea099"
+          "content": "6d047e89ebd5532a54d5200fa86660b3a8f1e96e128a5a4042d718d2cacae2ec"
         }
       ]
     },
@@ -1295,7 +1295,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ecf62c0372ef24516aa12797719b0cedfbfea1cf0f92d573baea8e9d9dea45b8"
+          "content": "1651978c5ce1fc510541d6ae3cc09f9cd74dde1e31d460d01b16f637dd80c8d2"
         }
       ]
     },
@@ -1305,7 +1305,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ef7b4183ebdd16a162e00960b8070207901d6d3b4415c2ff78da0a762e713a78"
+          "content": "a8098db1327beb284a22ac8b2410d030578e55a0648c8c8fbc7934dfa966ef85"
         }
       ]
     },
@@ -1315,7 +1315,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "25595cd5c6d53c4376571a9bf52444778a749fc22f50c64d15c38b248c12ed1f"
+          "content": "46032dd7deeb29b7a71d13d068620bd197a9a4d503e2c74089cbff0b9314859e"
         }
       ]
     },
@@ -1325,7 +1325,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c07373c4a1ad8ec473dcd01852cbffc6b5641e78bbf629dd8b5060dda94eea5e"
+          "content": "ad9870713ae8589d93e031048a9af4cea0371a35b53194870a672d02e66ccaaa"
         }
       ]
     },
@@ -2009,6 +2009,46 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "dist/reqe.d.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "115fa0797ad0e98a452f9987c15b038e22b18486043c8890c65cc32c9dc51af9"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/reqe.d.ts.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "75996953748647f0cbe548c73daa5cb7cd1f8906f2df474926c31b9e5fa223f9"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/reqe.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "229014a8fa37faeb716d7f0deb22758a133ce50479b849b072eb6a285e78db40"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/reqe.js.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "c28182b280cf2c016a2b1d2ef15a3a335ff25993220767ae9fc7c74af76ba022"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "dist/risk-scoring.d.ts",
@@ -2775,7 +2815,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1a64e1ded35c482214c3426808b24bcf7048041d716e375f101e228931c28248"
+          "content": "76997cf27ff9c8901df35b45fbdb1c91f201396f070dab0579289b8aa9ac851c"
         }
       ]
     },
@@ -3095,7 +3135,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "537dc4dc55cb43f11f2f0cee45ea53ec6fe362df470948408c49bb11fe972d9f"
+          "content": "5eb07fb5e21e7be1e78a11243d6f86b9c84461eec22a954102549b5e237b7ab2"
         }
       ]
     },
@@ -3259,6 +3299,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/reqe.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "67988858ff527e5b465aa46b341aa710465e8cb0f72038be30f2419e0ff12cc3"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "src/risk-scoring.ts",
@@ -4109,6 +4159,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/reqe.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "c5bb25b04caa8e9c14111ab838a135f7e2564b9fd1b7624520827bc95600661e"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/routing-outcomes.test.ts",

package/src/index.ts

@@ -155,6 +155,30 @@ export {
   checkpointAppendCmd,
 } from './feature-adr-checkpoints.js';
 export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead } from './feature-adr-checkpoints.js';
+export {
+  DOMAIN_LIFT_EXACT,
+  DOMAIN_LIFT_RELATED,
+  normalizeDomain,
+  domainMatch,
+  applyDomainBoost,
+  countDisplacedByCut,
+  renderDomainBoostNote,
+  renderDomainCutNote,
+} from './recall-domain-boost.js';
+export type { DomainMatch, DomainBoostResult } from './recall-domain-boost.js';
+export {
+  REQE_SCHEMA,
+  REQE_SCOPE,
+  modelFamily,
+  shouldEmitReqeDebt,
+  buildReqeDebt,
+  parseReqeDebt,
+  buildReqeBrief,
+  extractReportGrade,
+  settleReqeDebt,
+  renderReqeList,
+} from './reqe.js';
+export type { ModelFamily, ReqeEmitDecision, ReqeDebt, ReqeBrief, ReqeSettlement } from './reqe.js';
 export {
   detectQueryLang,
   relevanceFloorFor,

package/src/recall-domain-boost.ts

@@ -0,0 +1,172 @@
+/**
+ * Domain-aware recall re-ranking — the pure half of `dz recall --domain <name>`.
+ *
+ * WHY THIS EXISTS. `dz teach --domain <name>` has always recorded a domain, and
+ * `dz recall --all --stats` prints the per-domain histogram — but the RANKING path
+ * (`recallHybrid`: lexical FTS5 + optional vector leg merged by RRF) never looked at
+ * the field. So a store shared by different KINDS of work returns them interleaved:
+ * medical-research lessons dilute a coding recall and vice versa, and the dilution
+ * gets worse as either side grows.
+ *
+ * WHY A BOOST AND NOT A FILTER. Cross-pollination here is real, not theoretical:
+ * "a reviewer's evidence needs the same execute-don't-describe discipline as your
+ * own claims" was learned reviewing code and applies verbatim to medical sources;
+ * the medical report's core insight ("was the source ever opened?") is the same
+ * principle as our claim-check. A hard filter would cut exactly the transfers that
+ * make one store worth more than two. So: matching-domain hits move UP, foreign
+ * ones stay in the list.
+ *
+ * THE PROMISE, NARROWLY: this reorders. It NEVER drops a hit, never invents one,
+ * and never changes how many are returned. If the boost is wrong, the cost is
+ * ordering; it can't hide a lesson from you.
+ */
+
+import type { RecallHit } from './patterns.js';
+
+/** How many places a same-domain lesson may climb. STATED AS POSITIONS, not as a
+ * score multiplier: "moves up at most two places" is a sentence a reader can check
+ * against the output, while "index × 0.55" is an opaque constant whose behaviour
+ * changes with position (it could not lift index 2 past index 1 at all, but did
+ * lift index 3 past index 2 — an accident, not a design). A bounded lift keeps
+ * lexical relevance dominant: a domain tag is a hint about relevance, not evidence
+ * of it, so it breaks near-ties instead of overruling the ranking. */
+export const DOMAIN_LIFT_EXACT = 2;
+
+/** A prefix/suffix relative (`health-research` against `health`) climbs less. */
+export const DOMAIN_LIFT_RELATED = 1;
+
+export type DomainMatch = 'exact' | 'related' | 'none';
+
+/** Normalize a domain tag for comparison: case- and separator-insensitive, so
+ * `Health-Research`, `health_research` and `health research` are one domain. */
+export function normalizeDomain(domain: string | null | undefined): string {
+  return String(domain ?? '')
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/** How a hit's domain relates to the requested one. `related` covers the common
+ * hierarchy shapes (`health` ↔ `health-research`) without a taxonomy: a taxonomy
+ * nobody maintains drifts, and a wrong taxonomy is worse than none. */
+export function domainMatch(hitDomain: string | null | undefined, wanted: string | null | undefined): DomainMatch {
+  const a = normalizeDomain(hitDomain);
+  const b = normalizeDomain(wanted);
+  if (a === '' || b === '') return 'none';
+  if (a === b) return 'exact';
+  if (a.startsWith(`${b}-`) || b.startsWith(`${a}-`)) return 'related';
+  return 'none';
+}
+
+export interface DomainBoostResult {
+  readonly hits: readonly RecallHit[];
+  /** How many hits MATCHED the domain (exactly / relatedly). */
+  readonly exact: number;
+  readonly related: number;
+  /** How many hits actually CHANGED position. Counted separately because the note
+   * used to print the match counts as "lifted" — an exact match already at rank 0,
+   * or a list that is entirely one domain, matches without moving, and calling that
+   * "lifted" tells the reader the ranking changed when it did not. */
+  readonly moved: number;
+  /** True when NOTHING in the result matched: the caller says so out loud rather
+   * than implying the ranking is domain-aware when it had nothing to work with. */
+  readonly noMatches: boolean;
+}
+
+/**
+ * Re-rank hits so same-domain lessons surface first, keeping every hit.
+ *
+ * Effective position = `index - lift`. The original relevance order dominates; the
+ * domain only breaks near-ties, and the lift is BOUNDED so a tail match can never
+ * teleport to the top. Ties keep the incoming order (stable sort), so the function
+ * is deterministic — the same input always yields the same output, which is what
+ * makes it testable at all.
+ */
+export function applyDomainBoost(hits: readonly RecallHit[], wanted: string | null | undefined): DomainBoostResult {
+  const target = normalizeDomain(wanted);
+  if (target === '' || hits.length === 0) {
+    return { hits, exact: 0, related: 0, moved: 0, noMatches: true };
+  }
+  let exact = 0;
+  let related = 0;
+  const scored = hits.map((hit, index) => {
+    const match = domainMatch(hit.pattern.domain, target);
+    if (match === 'exact') exact += 1;
+    else if (match === 'related') related += 1;
+    const lift = match === 'exact' ? DOMAIN_LIFT_EXACT : match === 'related' ? DOMAIN_LIFT_RELATED : 0;
+    return { hit, index, lift, effective: index - lift };
+  });
+  // Tie-break: at equal effective position the LIFTED hit goes first, then the
+  // original order. Without this the foreign hit it landed level with won the tie
+  // by having the lower original index, so a lift of N moved the hit only N-1
+  // places — the code quietly delivered less than the constant promised. A test
+  // asserting the documented bound caught it; the fix is here, not in the test.
+  scored.sort((a, b) => (a.effective - b.effective) || (b.lift - a.lift) || (a.index - b.index));
+  const reordered = scored.map((s) => s.hit);
+  let moved = 0;
+  scored.forEach((s, newIndex) => { if (s.index !== newIndex) moved += 1; });
+  return { hits: reordered, exact, related, moved, noMatches: exact === 0 && related === 0 };
+}
+
+/**
+ * How many hits the CUT hid that an unboosted recall would have shown.
+ *
+ * WHY THIS EXISTS. `applyDomainBoost` never drops a hit — but the CLI still cuts the
+ * list at `--limit`, and a promotion INTO the top N necessarily pushes something out
+ * of it. Cross-model review found the resulting sentence to be a lie by omission: the
+ * note said "foreign-domain lessons kept" while `foreign-B`, visible without
+ * `--domain`, had vanished from the printed output. Both statements were true of
+ * different lists, which is exactly how an honest tool ends up misleading its reader.
+ *
+ * The fix is not to stop promoting — that would be the filter we refused to build. It
+ * is to COUNT what fell past the cut and say so, because the reader can act on that
+ * (raise `--limit`) only if they know it happened.
+ *
+ * Compares by identity: both lists hold the same hit objects.
+ */
+export function countDisplacedByCut(
+  original: readonly RecallHit[],
+  boosted: readonly RecallHit[],
+  limit: number,
+): number {
+  if (!Number.isFinite(limit) || limit <= 0) return 0;
+  const shownAfter = new Set(boosted.slice(0, limit));
+  let displaced = 0;
+  for (const hit of original.slice(0, limit)) {
+    if (!shownAfter.has(hit)) displaced += 1;
+  }
+  return displaced;
+}
+
+/** The line that reports the cut. Empty when nothing was displaced, so the common
+ * case stays quiet. */
+export function renderDomainCutNote(displaced: number, limit: number): string {
+  if (displaced <= 0) return '';
+  const plural = displaced === 1 ? 'lesson' : 'lessons';
+  return `  ${displaced} lower-ranked ${plural} fell past the --limit ${limit} cut to make room — raise --limit to see them (the boost promotes; the cut is what hides)`;
+}
+
+/** One honest line about what the boost did — including the case where it did
+ * nothing, which a silent reorder would hide.
+ *
+ * The two tail phrases below are a WIRE CONTRACT: `learning_bridge.py` in the
+ * `goap-research-ed25519` skill detects whether the installed `dz` supports
+ * `--domain` by looking for them, because an older CLI ignores the flag and exits 0
+ * (so an exit code cannot tell the versions apart). A test pins both strings — if you
+ * reword them, update the bridge in the same change or you switch that loop into
+ * permanent degraded mode without a single test turning red. */
+export function renderDomainBoostNote(result: DomainBoostResult, wanted: string): string {
+  if (result.noMatches) {
+    return `  domain "${wanted}": no lesson in this result carries it — order unchanged, nothing was hidden`;
+  }
+  const parts = [`${result.exact} exact`];
+  if (result.related > 0) parts.push(`${result.related} related`);
+  const effect = result.moved === 0
+    ? 'the order was already correct — nothing moved'
+    : `${result.moved} changed position`;
+  // The counts describe the CANDIDATES the boost ranked, which is a longer list than
+  // the one printed (the caller over-fetches, then cuts at --limit). Saying "3 changed
+  // position" above two printed lines reads as an arithmetic error unless the note
+  // names the list it is talking about — so it does.
+  return `  domain "${wanted}": among ${result.hits.length} candidate(s) — ${parts.join(', ')} match(es), ${effect}; foreign-domain lessons kept (a boost, not a filter)`;
+}