@theronap/cortex-mcp 0.9.145 → 0.9.146

package/lib/capture.mjs

@@ -400,6 +400,16 @@ async function captureWork(stdinRaw) {
   }
   const extracted = transcript ? extractSession(transcript) : null
   if (extracted && /^NOOP\b/i.test(extracted.summary)) { process.stderr.write(`cortex: ${stamp} ${sid} NOT RECORDED — summarizer classified it a no-op session\n`); return }
+  // ADR-0059 §5.3 — review obligation candidates before they leave the machine: drop what nobody owes,
+  // merge a deadline stated twice, reclassify whose it is. Never adds; fails open (obligation_review.mjs).
+  // Only when there are candidates, which most sessions never produce.
+  let obligations = extracted?.obligations ?? []
+  if (obligations.length) {
+    const { reviewObligations, describeReview } = await import('./obligation_review.mjs')
+    const rev = reviewObligations(obligations, transcript)
+    process.stderr.write(`cortex: ${stamp} ${sid} obligations ${describeReview(obligations.length, rev)}\n`)
+    obligations = rev.obligations
+  }
   // `pages` is the edge's PROPOSAL of where this record belongs (ADR-0055). Free-text names, resolved
   // against real pages server-side and dropped when they match nothing — the same untrusted-edge
   // contract people/entities use. Omitted entirely when empty so an older server sees no new field.
@@ -413,7 +423,7 @@ async function captureWork(stdinRaw) {
         // ADR-0059. Obligation candidates the extraction found AND verified verbatim against the
         // transcript it was shown — the server cannot re-check the quote (it never receives the
         // transcript), so these arrive already filtered. Omitted when empty, same as `pages`.
-        ...(extracted.obligations?.length ? { obligations: extracted.obligations } : {}),
+        ...(obligations.length ? { obligations } : {}),
       }
     : { ...common, transcript }
 

package/lib/obligation_review.mjs

@@ -0,0 +1,184 @@
+// ADR-0059 §5.3 — A SECOND READ OF THE PROPOSALS, BEFORE THEY LEAVE THE MACHINE.
+//
+// Asked for by Theron Peterson 2026-09-10: "why don't we have an agent review the proposed stuff before
+// it adds anything?" The first three real proposals made the case. One was right. One had the wrong date
+// (fixed in code since, due_phrase.ts). One was not his at all — "before the semester's over, we will
+// golf", a speaker's plan quoted out of a lecture, dismissed as "Never was for me". And the same lecture
+// yielded the same deliverable twice, once as announced ("Saturday") and once as later moved ("by
+// Tuesday the 22nd"). Those are JUDGMENT errors: whose is it, is it real, which statement is final. The
+// verbatim gate cannot see them (every quote was real) and date code cannot either.
+//
+// WHAT THE REVIEWER MAY DO — and the one thing it may not:
+//   keep        leave it as proposed
+//   drop        nobody is being asked to do anything (a plan, a hope, an anecdote, course content)
+//   reclassify  obligated_party → other | none (Model B stores those as context, §4.2)
+//   merge       the same item as candidate k, where k is the final statement of it
+//   ✗ ADD or REWORD — never. It returns decisions about candidates by index; it cannot introduce one,
+//     or change a subject, quote or date. A reviewer that could add would be a second extractor with
+//     none of the first one's gates.
+//
+// 🔴 IT FAILS OPEN. If the review cannot run — no `claude`, an expired credential, a timeout, output
+// that is not the expected JSON — the candidates go on UNREVIEWED, exactly as they did before this file
+// existed, and the log says so. The reviewer improves what the person sees; it must never be the reason
+// a real deadline is lost. For the same reason the prompt says: when unsure, keep. A wrong keep costs the
+// person one dismissal; a wrong drop is gone.
+//
+// It runs OUTSIDE the summarizer lock (the callers invoke it after extractSession returns): holding the
+// lock through a second model call would let it outlive the lock's staleness window, and another session
+// would reclaim a lock that is still in use. It only runs when there ARE candidates, which most records
+// do not produce, so it costs nothing on an ordinary session.
+
+import { spawnSync } from 'node:child_process'
+import { edgeSafeEnv, classifyEdgeFailure } from './edge_extract.mjs'
+
+export const REVIEW_MODEL_DEFAULT = 'claude-sonnet-5'
+export const REVIEW_TIMEOUT_MS = 180_000
+const CONTEXT_BEFORE = 1500
+const CONTEXT_AFTER = 1000
+const HEADER_CHARS = 600
+const PARTIES = new Set(['self', 'other', 'none'])
+
+/** PURE. Where `evidence` starts in `text`, allowing any whitespace between its words; -1 if absent. */
+export function locate(text, evidence) {
+  if (typeof text !== 'string' || typeof evidence !== 'string') return -1
+  const words = evidence.trim().split(/\s+/).slice(0, 14).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+  if (!words.length || !words[0]) return -1
+  const m = new RegExp(words.join('\\s+'), 'i').exec(text)
+  return m ? m.index : -1
+}
+
+/** PURE. The prompt: the record's opening, each candidate with the text around its quote, the rules. */
+export function buildReviewPrompt(cands, text) {
+  const t = typeof text === 'string' ? text : ''
+  const blocks = cands.map((c, i) => {
+    const at = locate(t, c.evidence)
+    const context = at >= 0
+      ? t.slice(Math.max(0, at - CONTEXT_BEFORE), at + (c.evidence?.length ?? 0) + CONTEXT_AFTER)
+      : c.evidence
+    const when = c.due_phrase ? `"${c.due_phrase}"` : c.due_at ? `(model read it as ${c.due_at})` : 'no time stated'
+    return `[${i}] subject: "${c.subject}" | obligated_party: ${c.obligated_party} | when: ${when}\n` +
+      `quote: "${c.evidence}"\ncontext: «${context.replace(/\s+/g, ' ').trim()}»`
+  })
+  return [
+    'You are the second reader of obligations that an extractor proposed from one record — a lecture, a ' +
+      'meeting or a work session. The person the record belongs to will see what you keep. You may only ' +
+      'KEEP, DROP, MERGE or RECLASSIFY a candidate. You may never add one, and never change its wording, ' +
+      'its quote or its date.',
+    '',
+    `The record begins:\n«${t.slice(0, HEADER_CHARS).replace(/\s+/g, ' ').trim()}»`,
+    '',
+    'Candidates, each with the text around its quote:',
+    '',
+    blocks.join('\n\n'),
+    '',
+    'Decide each candidate:',
+    '- DROP it if nobody is actually being asked to do anything: a plan, a hope, an anecdote, a ' +
+      "hypothetical, a speaker's own intention, course content, or history.",
+    '- RECLASSIFY it to "other" if someone other than the person this record belongs to must do it, or to ' +
+      '"none" if nobody must. In a lecture or meeting that person is an attendee, and a "you" said to the ' +
+      'room includes them.',
+    '- MERGE it into candidate k if it is the SAME item as k and k is the later or final statement of it — ' +
+      'for example a deadline that was announced and then changed.',
+    '- Otherwise KEEP it.',
+    'When unsure, KEEP: the person reviews what you keep, and a wrong drop is lost for good.',
+    '',
+    'Return ONLY minified JSON, one decision per candidate: ' +
+      '{"decisions":[{"i":0,"verdict":"keep|drop|merge|reclassify","into":null,"party":null,"why":"at most 12 words"}]}',
+  ].join('\n')
+}
+
+/** PURE. The decisions array out of the model's reply, or null. */
+export function parseReview(out) {
+  if (typeof out !== 'string') return null
+  const a = out.indexOf('{')
+  const b = out.lastIndexOf('}')
+  if (a < 0 || b <= a) return null
+  try {
+    const j = JSON.parse(out.slice(a, b + 1))
+    return Array.isArray(j?.decisions) ? j.decisions : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * PURE. Apply decisions to candidates. Anything malformed is IGNORED, which means KEPT: an index out of
+ * range, a merge into itself, into a dropped candidate, or into one that is itself merged away (no chains,
+ * so two candidates merging into each other both survive rather than both vanishing).
+ */
+export function applyReview(cands, decisions) {
+  const byI = new Map()
+  for (const d of Array.isArray(decisions) ? decisions : []) {
+    if (d && Number.isInteger(d.i) && d.i >= 0 && d.i < cands.length && !byI.has(d.i)) byI.set(d.i, d)
+  }
+  const verdict = (i) => byI.get(i)?.verdict
+  const dropped = new Set([...byI.keys()].filter((i) => verdict(i) === 'drop'))
+  const merged = []
+  for (const [i, d] of byI) {
+    const k = d.into
+    if (d.verdict === 'merge' && Number.isInteger(k) && k !== i && k >= 0 && k < cands.length && !dropped.has(k) && verdict(k) !== 'merge') {
+      merged.push([i, k])
+    }
+  }
+  const mergedAway = new Set(merged.map(([i]) => i))
+  const reclassified = []
+  const kept = []
+  cands.forEach((c, i) => {
+    if (dropped.has(i) || mergedAway.has(i)) return
+    const d = byI.get(i)
+    if (d?.verdict === 'reclassify' && PARTIES.has(d.party) && d.party !== c.obligated_party) {
+      reclassified.push([i, d.party])
+      kept.push({ ...c, obligated_party: d.party })
+    } else {
+      kept.push(c)
+    }
+  })
+  return { kept, changes: { dropped: [...dropped], merged, reclassified } }
+}
+
+function runClaude(prompt, model) {
+  return spawnSync('claude', ['--print', '--model', model], {
+    input: prompt,
+    // CORTEX_SUMMARIZING: the reviewer's own `claude` session must not re-enter the capture hooks.
+    env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }),
+    encoding: 'utf8',
+    timeout: REVIEW_TIMEOUT_MS,
+    maxBuffer: 1024 * 1024,
+  })
+}
+
+/**
+ * Review candidates against the text they came from. Never throws, never adds; on any failure returns
+ * the candidates unchanged with `reviewed: false` and the reason.
+ *
+ * opts: { run(prompt, model) → spawnSync-shaped result, env }
+ */
+export function reviewObligations(cands, text, opts = {}) {
+  const env = opts.env ?? process.env
+  if (!Array.isArray(cands) || cands.length === 0) return { obligations: Array.isArray(cands) ? cands : [], reviewed: false, reason: 'nothing to review' }
+  if (env.CORTEX_REVIEW_DISABLED || env.CORTEX_SUMMARIZE_DISABLED) return { obligations: cands, reviewed: false, reason: 'disabled' }
+  const model = env.CORTEX_REVIEW_MODEL || REVIEW_MODEL_DEFAULT
+  let r
+  try {
+    r = (opts.run ?? runClaude)(buildReviewPrompt(cands, text), model)
+  } catch (e) {
+    return { obligations: cands, reviewed: false, reason: `threw: ${e instanceof Error ? e.message : String(e)}` }
+  }
+  const why = classifyEdgeFailure(r)
+  if (why) return { obligations: cands, reviewed: false, reason: why.reason }
+  const decisions = parseReview(r.stdout)
+  if (!decisions) return { obligations: cands, reviewed: false, reason: 'unparseable' }
+  const { kept, changes } = applyReview(cands, decisions)
+  return { obligations: kept, reviewed: true, changes, model }
+}
+
+/** PURE. One log line for a review outcome. */
+export function describeReview(before, rev) {
+  if (!rev.reviewed) return `review skipped [${rev.reason}] — ${before} candidate(s) go on unreviewed`
+  const c = rev.changes
+  const parts = []
+  if (c.dropped.length) parts.push(`dropped ${c.dropped.join(',')}`)
+  if (c.merged.length) parts.push(`merged ${c.merged.map(([i, k]) => `${i}→${k}`).join(',')}`)
+  if (c.reclassified.length) parts.push(`reclassified ${c.reclassified.map(([i, p]) => `${i}→${p}`).join(',')}`)
+  return `review (${rev.model}): kept ${rev.obligations.length} of ${before}${parts.length ? ` — ${parts.join('; ')}` : ''}`
+}

package/lib/obligations_worker.mjs

@@ -25,6 +25,7 @@ import { mkdirSync, openSync, readdirSync, readFileSync, writeFileSync, renameSy
 import { homedir } from 'node:os'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { reviewObligations, describeReview } from './obligation_review.mjs'
 
 export const MAX_PARK_DAYS = 30
 export const FIRST_RETRY_MS = 5 * 60_000
@@ -103,11 +104,19 @@ export async function processJob(job, deps) {
     log(`extraction FAILED [${why?.reason ?? 'unknown'}] — this record was NOT checked for obligations`)
     return { outcome: 'extract-failed', reason: why?.reason ?? null }
   }
-  const obligations = Array.isArray(result.obligations) ? result.obligations : []
+  let obligations = Array.isArray(result.obligations) ? result.obligations : []
   if (obligations.length === 0) {
     log('no obligations found')
     return { outcome: 'none' }
   }
+  // ADR-0059 §5.3 — the second read (obligation_review.mjs), before anything leaves the machine. It may
+  // drop, merge or reclassify, never add; it fails open. Optional here so a caller without it is unchanged.
+  const review = deps.review ?? ((o) => ({ obligations: o, reviewed: false, reason: 'no reviewer' }))
+  const before = obligations.length
+  const rev = review(obligations, job.text)
+  log(describeReview(before, rev))
+  obligations = rev.obligations
+  if (obligations.length === 0) return { outcome: 'none', reviewed: true }
   const res = await post(job.target, obligations)
   if (res.action === 'recorded') {
     log(`recorded ${res.body?.proposed ?? '?'} of ${obligations.length} as proposals on record ${res.body?.recordId ?? '?'}`)
@@ -224,6 +233,7 @@ async function realDeps(target) {
   return {
     extract: extractSession,
     lastSkip: lastEdgeSkip,
+    review: (obligations, text) => reviewObligations(obligations, text),
     post: (t, obligations) => postCandidates({ base, token, target: t, obligations, fetchImpl: fetchCortex }),
     park: (entry) => writeParked(parkDir(), entry),
     log: logger(target),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.145",
+  "version": "0.9.146",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {