@theronap/cortex-mcp 0.9.145 → 0.9.147

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/edge_extract.mjs

@@ -167,15 +167,26 @@ const PAGES_FRAGMENT =
 // ⚠ `evidence` IS VERIFIED HERE, NOT SERVER-SIDE (ADR-0059 §4.1). The cloud receives only the derived
 // digest and never the transcript, so there is nothing server-side to compare a quote against. The
 // check is `verbatimIn()` below, run against the SAME slice the model was shown.
+//
+// ⚠ "THE 15TH" IS A STATED DAY (2026-09-11). The old wording — "otherwise null — do NOT invent or infer
+// a date … that was not said" — left a model free to read a day with no month as "not said", and one
+// run of the STRAT 421 lecture did exactly that: no due_at AND no due_phrase for "on the 15th" and
+// "by Tuesday the 22nd", while a repeat of the same run filled both. The phrase is what the server
+// resolves, so it is now REQUIRED whenever the evidence says when. The server also reads the verbatim
+// quote itself when a candidate arrives with neither (resolveDueFromQuote in web/lib/engine/due_phrase.ts),
+// so this wording lowers how often that net is needed rather than being the only thing holding the date.
 const OBLIGATIONS_FRAGMENT =
   '"obligations" (array of things someone must DO by a date, stated in this session. Each an object ' +
   'with "subject" (what must be done, one short phrase), ' +
-  '"due_at" (a DATE, YYYY-MM-DD, when only a day is stated; a date-time, YYYY-MM-DDTHH:MM, ONLY when a ' +
-  'time of day is actually said; otherwise null — do NOT invent or infer a date or a time that was not ' +
-  'said. A day with no time is kept as a bare date and treated as all-day), ' +
+  '"due_at" (a DATE, YYYY-MM-DD, when only a day is stated — and a day said without its month or ' +
+  'year, like "the 15th", IS a stated day: complete it from the record\'s own date; a date-time, ' +
+  'YYYY-MM-DDTHH:MM, ONLY when a ' +
+  'time of day is actually said; null only when no day is stated at all — never invent a day or a ' +
+  'time the evidence does not state. A day with no time is kept as a bare date and treated as all-day), ' +
   '"due_phrase" (the exact words that say WHEN it is due — "on the 15th", "by Tuesday the 22nd", ' +
-  '"Saturday", "by 5 pm tomorrow" — copied VERBATIM from the evidence sentence; null if the evidence ' +
-  'names no time. The date itself is worked out from these words, so copy them, do not rephrase), ' +
+  '"Saturday", "by 5 pm tomorrow" — copied VERBATIM from the evidence sentence. REQUIRED whenever the ' +
+  'evidence says when, even when it leaves out the month or year; null ONLY if the evidence names no ' +
+  'time at all. The date itself is worked out from these words, so copy them, do not rephrase), ' +
   '"evidence" (the sentence from the session that says so, copied EXACTLY and VERBATIM — it is ' +
   'checked against the transcript and the whole item is discarded if it does not match), ' +
   '"obligated_party" (exactly one of: "self" if the person whose session this is must do it; ' +
@@ -285,7 +296,9 @@ export function verbatimIn(needle, haystack) {
  * `obligated_party` outside the preset is malformed and goes — the server's CHECK constraint would
  * reject it anyway, and failing here means the record still lands with its other keys intact.
  */
-const normWs = (x) => x.toLowerCase().replace(/[’']/g, '').replace(/\s+/g, ' ').trim()
+// Punctuation is spacing here too: "Tuesday, the 22nd" is the same words as "Tuesday the 22nd", and a
+// phrase dropped over a comma leaves the server with only due_at — the gap a phrase exists to close.
+const normWs = (x) => x.toLowerCase().replace(/[’']/g, '').replace(/[,.;:!?"“”()]/g, ' ').replace(/\s+/g, ' ').trim()
 
 export function keepVerifiableObligations(items, shown) {
   if (!Array.isArray(items)) return []

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
@@ -52,6 +53,31 @@ export function classifyPost(status) {
   return 'retry'
 }
 
+/**
+ * PURE. The log line for a recorded post: what the server did with the candidates, and what DATE
+ * information each one carried.
+ *
+ * 🔴 WHY (2026-09-11). A re-run of a lecture logged "recorded 2 of 3 as proposals" while two of the three
+ * had landed with no due date — one having lost the date an earlier read stored. Nothing on this machine
+ * said so; it took a query against the table, and what the model had sent was unrecoverable. So the line
+ * now carries the server's counts and, per candidate, its SHAPE — phrase, date, both, or neither. Never the
+ * subject or the quote: capture.log is created with default permissions, unlike the 0600 parked files,
+ * and a candidate's words are the person's content.
+ */
+export function describeRecorded(body, sent) {
+  const b = body ?? {}
+  const counts = [`${b.proposed ?? '?'} new`]
+  // An older server answers without these; say nothing rather than "undefined refreshed".
+  if (b.refreshed !== undefined) counts.push(`${b.refreshed} refreshed`)
+  if (b.replaced !== undefined) counts.push(`${b.replaced} replaced`)
+  const shape = (o) => (o?.due_phrase ? (o.due_at ? 'phrase+date' : 'phrase') : o?.due_at ? 'date' : 'NO date')
+  const list = Array.isArray(sent) ? sent : []
+  let line = `recorded ${list.length} on record ${b.recordId ?? '?'}: ${counts.join(', ')} — sent ${list.map((o, i) => `#${i} ${shape(o)}`).join(', ')}`
+  if (b.fromQuote) line += `; ${b.fromQuote} dated from the quote`
+  if (b.undated) line += `; ⚠ ${b.undated} left WITHOUT a date`
+  return line
+}
+
 /** PURE. The next retry delay: 5 min, doubling, capped at 6 h. */
 export function backoffMs(attempts) {
   return Math.min(FIRST_RETRY_MS * 2 ** Math.max(0, attempts - 1), MAX_RETRY_MS)
@@ -103,14 +129,22 @@ 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 ?? '?'}`)
+    log(describeRecorded(res.body, obligations))
     return { outcome: 'recorded', proposed: res.body?.proposed ?? null }
   }
   if (res.action === 'drop') {
@@ -161,7 +195,8 @@ export async function flushParkedObligations(deps) {
       try { unlinkSync(file) } catch { /* raced with another flush; the write is idempotent */ }
       flushed += 1
       log(res.action === 'recorded'
-        ? `recorded ${res.body?.proposed ?? '?'} parked obligations for ${id} on attempt ${(entry.attempts ?? 0) + 1}`
+        ? `recorded ${res.body?.proposed ?? '?'} parked obligations for ${id} on attempt ${(entry.attempts ?? 0) + 1}` +
+          (res.body?.undated ? ` — ⚠ ${res.body.undated} left WITHOUT a date` : '')
         : `DROPPED parked obligations for ${id} — the server answered ${res.status} ${res.body?.error ?? ''}`.trim())
       continue
     }
@@ -224,6 +259,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.147",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {