argus-decision-mcp 1.0.0

package/dist/tools/premises.js

@@ -0,0 +1,209 @@
+import { z } from 'zod';
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday } from '../lib/resolve-today.js';
+import { resolveContract } from '../lib/resolve-contract.js';
+import { guardTransition } from '../lib/state-machine.js';
+import { appendLedger } from '../lib/ledger-append.js';
+import { premiseId, resolvePremiseRef, MAX_ACTIVE_PREMISES, MAX_LOAD_BEARING, } from '../lib/premises.js';
+import { elicit } from '../lib/elicit.js';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir, zId, zDate } from './tool-types.js';
+import { handleToolException } from './errors.js';
+/**
+ * argus_premises — the write surface for a decision's living premises
+ * (plan v5 §2). One tool, three ops, so hosts thread ONE name:
+ *
+ *   add     — record the facts / open questions the decision rests on
+ *   amend   — the user corrects a premise (the edit IS the signal; authorship
+ *             transfers honestly, ai_original preserved)
+ *   resolve — the user closes an open question IN THEIR OWN WORDS
+ *             (elicitation-only: this tool never generates options, examples,
+ *             or leans — a two-pole fork cannot be expressed here)
+ *
+ * Premise text is DATA, never instructions; it is echoed back in full
+ * (data.premises) so the host can always show the user what was recorded.
+ */
+const zPremiseInput = z.strictObject({
+    text: z.string().min(3).max(400).describe('One literal, factual sentence. No metaphor. Good: "base rate stays at 3.5% through 2026". Bad: "the ground this rests on".'),
+    kind: z.enum(['premise', 'open_question']).default('premise').describe('premise = a fact/belief the decision rests on. open_question = something the user explicitly left undecided.'),
+    external: z.boolean().default(false).describe('Can reality verify this later (a rate, a date, supply, a third party)? external + load_bearing arms re-checking.'),
+    load_bearing: z.boolean().default(false).describe(`Would the decision flip if this is wrong? Mark sparingly — max ${MAX_LOAD_BEARING} per decision.`),
+    source: z.enum(['ai', 'user']).describe('Provenance. Never forge: "user" = the user\'s own words; "ai" = model-drafted (requires ai_original).'),
+    ai_original: z.string().max(400).optional().describe('REQUIRED when source="ai": the model\'s original wording, preserved verbatim across later edits.'),
+});
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    id: zId.describe('The decision id from argus_open_decision.'),
+    op: z.enum(['add', 'amend', 'resolve']).describe('add = record premises; amend = correct one (user edit = signal); resolve = close an open question in the user\'s words.'),
+    premises: z.array(zPremiseInput).min(1).max(MAX_ACTIVE_PREMISES).optional().describe('op=add only.'),
+    ref: z.string().max(64).optional().describe('op=amend/resolve: which premise — an ordinal ("P1"), the premise_id, or an unambiguous id prefix. Ordinals are permanent (a retired P2 stays P2).'),
+    action: z.enum(['accept', 'refine', 'replace', 'retire']).optional().describe('op=amend only. accept = confirm as-is; refine/replace = correct the text; retire = remove from active tracking (stays on the record).'),
+    text: z.string().min(3).max(400).optional().describe('op=amend refine/replace: the corrected text — the USER\'s wording, verbatim, never re-summarized.'),
+    note: z.string().max(300).optional().describe('op=amend: optional why (never required).'),
+    external: z.boolean().optional().describe('op=amend: correct the external flag (true lets re-checking arm for a load-bearing premise).'),
+    load_bearing: z.boolean().optional().describe('op=amend: correct the load-bearing flag.'),
+    decision: z.string().min(1).max(400).optional().describe('op=resolve: the user\'s own closing call. MUST be the user\'s words — never an Argus-drafted line.'),
+    today_override: zDate.optional(),
+});
+export const premises = {
+    name: 'argus_premises',
+    description: 'Record and maintain the premises a decision rests on — the facts and open questions behind it. ' +
+        'op=add records them (echoed back in full so the user sees what was written); op=amend lets the user correct one (edits are the signal; provenance is preserved); ' +
+        'op=resolve closes an open question in the user\'s own words. Premises lock once the check-by date arrives. ' +
+        'A load-bearing external premise is re-checked against reality via argus_recheck once the decision is sealed.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Track decision premises', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const id = String(a['id'] ?? '');
+            const today = resolveToday({ override: a['today_override'] });
+            const op = String(a['op']);
+            const now = new Date().toISOString();
+            const current = resolveContract(dir, id, today);
+            const existing = current.entry?.premises ?? [];
+            if (op === 'add')
+                return await opAdd(dir, id, today, now, current.state, existing, a);
+            if (op === 'amend')
+                return await opAmend(dir, id, now, current.state, existing, a);
+            return await opResolve(dir, id, now, current.state, existing, a);
+        }
+        catch (e) {
+            return handleToolException('argus_premises', e);
+        }
+    },
+};
+// ── op=add ─────────────────────────────────────────────────────────────────
+async function opAdd(dir, id, _today, now, state, existing, a) {
+    guardTransition(state, 'premise_add');
+    const inputs = a['premises'];
+    if (!inputs || inputs.length === 0) {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'PREMISES_REQUIRED', message: 'op=add needs a non-empty `premises` array.', recovery: 'Pass 1-5 premises: {text, kind, external, load_bearing, source}.' });
+    }
+    for (const p of inputs) {
+        if (p.source === 'ai' && !(p.ai_original && p.ai_original.trim())) {
+            return toolError({ ok: false, tool: 'argus_premises', error_code: 'PROVENANCE_REQUIRED', message: `source="ai" requires ai_original (the model's original wording): "${p.text.slice(0, 60)}"`, recovery: 'Set ai_original to the exact model-drafted sentence, or source="user" if the user wrote it.' });
+        }
+    }
+    // Dedup against the ledger by stable id — re-adding is idempotent, not an error.
+    const known = new Set(existing.map((p) => p.premise_id));
+    const fresh = inputs.filter((p) => !known.has(premiseId(id, p.kind, p.text)));
+    const skippedDup = inputs.length - fresh.length;
+    const activeCount = existing.filter((p) => p.status === 'active').length;
+    if (activeCount + fresh.length > MAX_ACTIVE_PREMISES) {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'PREMISE_CAP', message: `A decision holds at most ${MAX_ACTIVE_PREMISES} active premises (${activeCount} already active).`, recovery: 'Retire one first (op=amend action=retire), or fold minor premises into the load-bearing ones — a decision is 5 premises, not a wiki.' });
+    }
+    const lbExisting = existing.filter((p) => p.status === 'active' && p.load_bearing).length;
+    const lbNew = fresh.filter((p) => p.load_bearing).length;
+    if (lbExisting + lbNew > MAX_LOAD_BEARING) {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'PREMISE_CAP', message: `At most ${MAX_LOAD_BEARING} load-bearing premises (${lbExisting} already marked).`, recovery: 'Load-bearing means the decision flips if it is wrong — if three qualify, the sharpest one is hiding among them.' });
+    }
+    let nextOrdinal = existing.reduce((m, p) => Math.max(m, p.ordinal), 0) + 1;
+    const events = fresh.map((p) => ({
+        id, event: 'premise_add',
+        premise_id: premiseId(id, p.kind, p.text),
+        ordinal: nextOrdinal++,
+        kind: p.kind, text: p.text,
+        external: p.external, load_bearing: p.load_bearing,
+        source: p.source,
+        ...(p.ai_original ? { ai_original: p.ai_original } : {}),
+    }));
+    if (events.length > 0)
+        await appendLedger(dir, events, now);
+    // Full echo — the silent-premise defense: the host always has the material to
+    // show the user exactly what was recorded (plan v5 §2).
+    const echo = events.map((e) => ({
+        ref: `P${e.ordinal}`, premise_id: e.premise_id, kind: e.kind, text: e.text,
+        external: e.external, load_bearing: e.load_bearing, source: e.source,
+        monitored: e.kind === 'premise' && e.external === true && e.load_bearing === true,
+    }));
+    const monitoredCount = echo.filter((p) => p.monitored).length;
+    return envelope({
+        ok: true, tool: 'argus_premises',
+        surface: events.length === 0
+            ? 'All of those premises are already recorded (nothing new written).'
+            : `${events.length} premise(s) recorded (${echo[0].ref}${echo.length > 1 ? `–${echo[echo.length - 1].ref}` : ''}). Fix anything wrong with op=amend — your correction is part of the record.${monitoredCount > 0 ? ` ${monitoredCount} will be re-checked against reality once the decision is sealed.` : ''}`,
+        next_actions: ['argus_seal', 'argus_recall', 'leave_as_is'],
+        data: { id, premises: echo, skipped_duplicates: skippedDup, ledger_events_written: events.map(() => 'premise_add') },
+    });
+}
+// ── op=amend ───────────────────────────────────────────────────────────────
+async function opAmend(dir, id, now, state, existing, a) {
+    guardTransition(state, 'premise_amend');
+    const ref = a['ref'];
+    const action = a['action'];
+    if (typeof ref !== 'string' || !action) {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'AMEND_NEEDS_REF', message: 'op=amend needs `ref` (e.g. "P1") and `action`.', recovery: 'List premises via argus_recall view="premises", then amend by ordinal.' });
+    }
+    const premise = resolvePremiseRef(existing, ref);
+    if (premise.status !== 'active' && action !== 'accept') {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'PREMISE_RETIRED', message: `P${premise.ordinal} is ${premise.status} — it stays on the record but is no longer edited.`, recovery: 'Add a fresh premise instead (op=add); the old one keeps its history.' });
+    }
+    const text = a['text'];
+    if ((action === 'refine' || action === 'replace') && !(text && text.trim())) {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'AMEND_NEEDS_TEXT', message: `action=${action} needs the corrected text.`, recovery: "Pass `text` with the user's wording, verbatim — never re-summarize it." });
+    }
+    const loadBearing = a['load_bearing'];
+    if (loadBearing === true && !premise.load_bearing) {
+        const lbActive = existing.filter((p) => p.status === 'active' && p.load_bearing).length;
+        if (lbActive >= MAX_LOAD_BEARING) {
+            return toolError({ ok: false, tool: 'argus_premises', error_code: 'PREMISE_CAP', message: `At most ${MAX_LOAD_BEARING} load-bearing premises.`, recovery: 'Unmark another one first (op=amend load_bearing=false).' });
+        }
+    }
+    const ev = {
+        id, event: 'premise_amend', premise_id: premise.premise_id, action,
+        ...(action === 'refine' || action === 'replace' ? { from: premise.text, to: text } : {}),
+        ...(typeof a['note'] === 'string' ? { note: a['note'] } : {}),
+        ...(typeof a['external'] === 'boolean' ? { external: a['external'] } : {}),
+        ...(typeof loadBearing === 'boolean' ? { load_bearing: loadBearing } : {}),
+    };
+    await appendLedger(dir, [ev], now);
+    const nowExternal = typeof ev.external === 'boolean' ? ev.external : premise.external;
+    const nowLb = typeof ev.load_bearing === 'boolean' ? ev.load_bearing : premise.load_bearing;
+    const armed = action !== 'retire' && premise.kind === 'premise' && nowExternal && nowLb;
+    const surface = action === 'retire' ? `P${premise.ordinal} retired — it stays on the record with its history.` :
+        action === 'accept' ? `P${premise.ordinal} confirmed as-is.` :
+            `P${premise.ordinal} updated in your words.${premise.source === 'ai' ? ' The AI\'s original stays on the record for provenance.' : ''}${armed ? '' : ''}`;
+    return envelope({
+        ok: true, tool: 'argus_premises',
+        surface,
+        next_actions: ['argus_recall', 'leave_as_is'],
+        data: {
+            id, ref: `P${premise.ordinal}`, premise_id: premise.premise_id, action,
+            ...(text ? { text } : {}), monitored_after: armed,
+        },
+    });
+}
+// ── op=resolve (elicitation-only — no options, no examples, no leans) ──────
+async function opResolve(dir, id, now, state, existing, a) {
+    guardTransition(state, 'premise_resolve');
+    const ref = a['ref'];
+    if (typeof ref !== 'string') {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'RESOLVE_NEEDS_REF', message: 'op=resolve needs `ref`.', recovery: 'List open questions via argus_recall view="premises", then resolve by ordinal.' });
+    }
+    const premise = resolvePremiseRef(existing, ref);
+    if (premise.kind !== 'open_question') {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'NOT_AN_OPEN_QUESTION', message: `P${premise.ordinal} is a premise, not an open question.`, recovery: 'Premises are re-checked against reality (argus_recheck), not resolved. Only an open_question takes the user\'s closing call.' });
+    }
+    if (premise.status !== 'active') {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'PREMISE_RETIRED', message: `P${premise.ordinal} is already ${premise.status}.`, recovery: 'Read it via argus_recall view="premises".' });
+    }
+    let decision = typeof a['decision'] === 'string' ? a['decision'].trim() : '';
+    if (!decision) {
+        // MCP-native elicitation: ask the USER directly. The question replays their
+        // own open question verbatim and takes free text — no options, no leans.
+        const got = await elicit(`Your open question on this decision: "${premise.text}". What is your call now, in your own words? (You can also leave it open.)`, { type: 'object', properties: { decision: { type: 'string', maxLength: 400, description: 'Your call, your words.' } }, required: ['decision'] });
+        decision = typeof got?.['decision'] === 'string' ? got['decision'].trim() : '';
+    }
+    if (!decision) {
+        return toolError({ ok: false, tool: 'argus_premises', error_code: 'RESOLVE_NEEDS_DECISION', message: 'An open question closes only in the user\'s own words.', recovery: 'Ask the user for their call and pass it as `decision` — never draft it for them. "Still undecided" is a valid answer: then leave it open (no call needed).' });
+    }
+    await appendLedger(dir, [{ id, event: 'premise_resolve', premise_id: premise.premise_id, decision }], now);
+    return envelope({
+        ok: true, tool: 'argus_premises',
+        surface: `Open question P${premise.ordinal} closed in your words: "${decision}".`,
+        next_actions: ['argus_recall', 'leave_as_is'],
+        data: { id, ref: `P${premise.ordinal}`, premise_id: premise.premise_id, decision, decision_owner: 'user' },
+    });
+}

package/dist/tools/recall.js

@@ -0,0 +1,157 @@
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday } from '../lib/resolve-today.js';
+import { replayLedger } from '../lib/ledger-replay.js';
+import { readReceipt } from '../lib/receipt.js';
+import { renderReceipt, renderWake } from '../lib/render-receipt.js';
+import { surfaceLocale } from '../lib/surfaces.js';
+import { isMonitored, isDueForRecheck, receiptPremisesInfo } from '../lib/premises.js';
+import { z } from 'zod';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir, zId, zDate } from './tool-types.js';
+import { handleToolException } from './errors.js';
+/** check_by ascending; rows without a date sink to the end. */
+const byCheckBy = (a, b) => (a.check_by || '9999-99-99') < (b.check_by || '9999-99-99') ? -1 : 1;
+/** wake_text (P1-E7 = 12 §3.5) — rendered only when a wake exists (at least
+ *  one sealed or settled contract); candidates/dismissed never fill the frame. */
+function wakeText(ledger, today, dir) {
+    const rows = [...ledger.contracts.values()];
+    if (!rows.some((c) => c.status === 'sealed' || c.status === 'settled'))
+        return undefined;
+    return renderWake(rows, ledger.stats, today, surfaceLocale(dir), ledger.oldest_ts?.slice(0, 10));
+}
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    view: z.enum(['bearing', 'contracts', 'receipt', 'track_record', 'premises']),
+    id: zId.describe('Required when view = "receipt" or "premises".').optional(),
+    today_override: zDate.optional(),
+});
+export const recall = {
+    name: 'argus_recall',
+    description: "Read your own decision history: a single receipt, the open contracts, or your track record. Read-only. Track record reports sample-size-scaled frequency only — never a tier, score, or verdict about who you are.",
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Recall your history', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const today = resolveToday({ override: a['today_override'] });
+            const view = String(a['view']);
+            if (view === 'receipt') {
+                const id = a['id'];
+                if (typeof id !== 'string' || !id) {
+                    return toolError({ ok: false, tool: 'argus_recall', error_code: 'RECEIPT_NEEDS_ID', message: 'view "receipt" requires an id.', recovery: 'Pass the decision id.' });
+                }
+                const r = readReceipt(dir, id);
+                if (!r) {
+                    return toolError({ ok: false, tool: 'argus_recall', error_code: 'RECEIPT_NOT_FOUND', message: `No receipt for "${id}".`, recovery: 'Check the id, or seal the decision first.' });
+                }
+                // The premise set is canonical — the receipt renders its summary from the fold (plan v5 §3.3).
+                const pInfo = receiptPremisesInfo(replayLedger(dir, today).contracts.get(id));
+                return envelope({
+                    ok: true, tool: 'argus_recall', surface: 'Receipt recalled.',
+                    next_actions: ['stop'], data: { receipt: r, receipt_text: renderReceipt(r, pInfo) },
+                });
+            }
+            const ledger = replayLedger(dir, today);
+            if (view === 'premises') {
+                const id = a['id'];
+                if (typeof id !== 'string' || !id) {
+                    return toolError({ ok: false, tool: 'argus_recall', error_code: 'PREMISES_NEEDS_ID', message: 'view "premises" requires an id.', recovery: 'Pass the decision id.' });
+                }
+                const entry = ledger.contracts.get(id);
+                const list = entry?.premises ?? [];
+                if (list.length === 0) {
+                    return envelope({
+                        ok: true, tool: 'argus_recall',
+                        surface: 'No premises tracked on this decision. Record the facts it rests on with argus_premises (op=add).',
+                        next_actions: ['leave_as_is'],
+                        data: { id, premises: [], today },
+                    });
+                }
+                const rows = list.map((p) => {
+                    const last = p.last_recheck?.ts ? p.last_recheck.ts.slice(0, 10) : null;
+                    const daysStale = last ? Math.round((Date.parse(today) - Date.parse(last)) / 86400000) : null;
+                    return {
+                        ref: `P${p.ordinal}`, premise_id: p.premise_id, kind: p.kind, text: p.text,
+                        status: p.status, external: p.external, load_bearing: p.load_bearing,
+                        monitored: isMonitored(p),
+                        // provenance — the declared reader of ai_original (plan v5 §6.4)
+                        source: p.source,
+                        ...(p.ai_original && p.ai_original !== p.text ? { ai_original: p.ai_original, edited_by_user: true } : {}),
+                        edits: p.amend_history.length,
+                        // staleness, honestly (plan v5 §5-3): never pretend liveness
+                        last_checked: last,
+                        staleness: last === null ? 'never re-checked' : `${daysStale}d since last re-check`,
+                        ...(p.last_recheck ? { last_finding: p.last_recheck.finding, last_source: p.last_recheck.source, last_drifted: p.last_recheck.drifted } : {}),
+                        due_for_recheck: isDueForRecheck(p, today),
+                        ...(p.resolved_decision ? { resolved_decision: p.resolved_decision } : {}),
+                    };
+                });
+                const monitored = rows.filter((r) => r.monitored).length;
+                const due = rows.filter((r) => r.due_for_recheck).length;
+                return envelope({
+                    ok: true, tool: 'argus_recall',
+                    surface: `${rows.length} premise(s) on this decision — ${monitored} monitored, ${due} due for a reality re-check${due > 0 ? ' (argus_recheck)' : ''}.`,
+                    next_actions: due > 0 ? ['argus_check_in', 'leave_as_is'] : ['leave_as_is'],
+                    data: { id, premises: rows, today },
+                });
+            }
+            if (view === 'bearing') {
+                // JSON side sorted too (P1-E7 / 12 §3.6): check_by ascending, so a
+                // past-due contract can never hide between far-future ones.
+                const open = [...ledger.contracts.values()]
+                    .filter((c) => c.status === 'sealed')
+                    .map((c) => ({ id: c.id, predicate: c.predicate, check_by: c.check_by }))
+                    .sort(byCheckBy);
+                const surface = ledger.ids.size === 0
+                    ? 'Argus does not answer. It records a prediction + a check-by date, and meets reality on that date. Open your first decision with argus_open_decision.'
+                    : `${open.length} open bearing(s).`;
+                const wake = wakeText(ledger, today, dir);
+                return envelope({ ok: true, tool: 'argus_recall', surface, next_actions: open.length ? ['argus_check_in'] : ['argus_open_decision'], data: { open, today, ...(wake ? { wake_text: wake } : {}) } });
+            }
+            if (view === 'contracts') {
+                const all = [...ledger.contracts.values()]
+                    .map((c) => ({ id: c.id, status: c.status, predicate: c.predicate, check_by: c.check_by, outcome: c.outcome, dismiss_reason: c.dismiss_reason }))
+                    .sort(byCheckBy);
+                // 60-row cap (12 §3.6) — the JSON stays a summary, not a wall.
+                const shown = all.slice(0, 60);
+                const wake = wakeText(ledger, today, dir);
+                return envelope({
+                    ok: true, tool: 'argus_recall', surface: `${all.length} decision(s) on record.`, next_actions: ['stop'],
+                    data: { contracts: shown, ...(all.length > shown.length ? { truncated: all.length - shown.length } : {}), today, ...(wake ? { wake_text: wake } : {}) },
+                });
+            }
+            // track_record — frequency only, sample-size caveated. No tier, no score (spine rule 2).
+            const s = ledger.stats;
+            const n = s.total_settled;
+            const freq = n === 0
+                ? 'No settled decisions yet — nothing to summarize.'
+                : `Of ${n} settled: ${s.held} held, ${s.avoided} avoided, ${s.partial} partial.`;
+            // Premise-level attribution (plan v5 P2) — where accumulation compounds:
+            // COUNTS of settles where the user themselves named a broken premise.
+            // A frequency statement, never a diagnosis of the person.
+            const settled = [...ledger.contracts.values()].filter((c) => c.status === 'settled');
+            const missedOrPartial = settled.filter((c) => c.outcome === 'avoided' || c.outcome === 'partial');
+            const withBroken = missedOrPartial.filter((c) => c.broken_premise_id);
+            const premiseAttribution = withBroken.length > 0
+                ? `Of ${missedOrPartial.length} settle(s) that did not hold, you attributed ${withBroken.length} to a named broken premise.`
+                : undefined;
+            return envelope({
+                ok: true, tool: 'argus_recall',
+                surface: premiseAttribution ? `${freq} ${premiseAttribution}` : freq,
+                next_actions: ['stop'],
+                data: {
+                    judgment_tier: null, judgment_score: null, // drift-guard asserts these stay null
+                    frequency_statement: freq,
+                    ...(premiseAttribution ? { premise_attribution: premiseAttribution, premise_attribution_counts: { not_held: missedOrPartial.length, with_named_broken_premise: withBroken.length } } : {}),
+                    sample_size: n,
+                    sample_size_caveat: n < 10 ? 'Sample is small — read this as history, not a pattern about you.' : undefined,
+                    stats: s,
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_recall', e);
+        }
+    },
+};

package/dist/tools/recheck.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { resolveToolArgusDir } from '../lib/argus-dir.js';
+import { resolveToday } from '../lib/resolve-today.js';
+import { replayLedger } from '../lib/ledger-replay.js';
+import { deriveState, guardTransition } from '../lib/state-machine.js';
+import { appendLedger } from '../lib/ledger-append.js';
+import { resolvePremiseRef, matchingMonitoredPremises, normalizePremiseText } from '../lib/premises.js';
+import { numericDrift } from '../lib/numeric-drift.js';
+import { envelope, toolError } from '../lib/envelope.js';
+import { ENVELOPE_OUTPUT_SCHEMA, zArgusDir, zId, zDate } from './tool-types.js';
+import { handleToolException } from './errors.js';
+/**
+ * argus_recheck — re-check one premise against reality (plan v5 §2, §7.1).
+ *
+ * The HOST does the research (web search, a document, the user's report); this
+ * tool does the mechanical part only:
+ *   - numeric premises: compares EXPLICIT numbers (never parses prose — the
+ *     first-number-in-string bug class reads "2026년 기준금리 3.5%" as 2026)
+ *   - text premises: records the host's provenance-armed factual assertion
+ *     (`changed`) — a paraphrase is not a changed fact, so string comparison
+ *     over-fires and is not used
+ *   - provenance is REQUIRED on every recheck: a half-remembered value must
+ *     never enter the reality record unlabeled
+ *
+ * When the fact drifted, the surface returns the handle — never a directive.
+ */
+const inputSchema = z.strictObject({
+    argus_dir: zArgusDir,
+    id: zId.describe('The decision id.'),
+    ref: z.string().max(64).describe('Which premise — ordinal ("P1"), premise_id, or unambiguous prefix.'),
+    finding: z.string().min(3).max(400).describe('The CURRENT state of the fact, one literal comparable sentence. e.g. "base rate 3.75% after a 25bp hike".'),
+    numeric_value: z.number().optional().describe('The fact\'s current number, named EXPLICITLY (e.g. 3.75). Never extracted from prose by regex. When present, drift is decided mechanically (>=10% move or sign flip).'),
+    changed: z.boolean().optional().describe('Text premises only: has the FACT materially changed vs the recorded baseline? A research finding about external reality (provenance required) — never a judgment of the user.'),
+    source: z.enum(['url', 'user_stated', 'host_reported']).describe('Where the finding comes from. host_reported = the model\'s own research without a citation — recorded honestly as such.'),
+    source_detail: z.string().max(300).optional().describe('URL or short citation when source="url".'),
+    apply_to_matching: z.boolean().default(false).describe('Also record this re-check on OTHER decisions whose monitored premise has the same normalized text (same fact, same evidence — an explicit mechanical fan-out, plan v5 P1).'),
+    today_override: zDate.optional(),
+});
+export const recheck = {
+    name: 'argus_recheck',
+    description: 'Re-check one premise of a decision against reality. The host researches the fact and passes the finding (with provenance); ' +
+        'the tool records it and decides drift mechanically — explicit numbers compare numerically, text premises take the host\'s asserted `changed`. ' +
+        'First re-check records the baseline and never alerts. If the fact drifted, the response says so and returns the handle — whether to revisit the decision stays the user\'s call.',
+    inputSchema,
+    outputSchema: ENVELOPE_OUTPUT_SCHEMA,
+    annotations: { title: 'Re-check a premise against reality', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    handler: async (a) => {
+        try {
+            const dir = resolveToolArgusDir(a['argus_dir']);
+            const id = String(a['id'] ?? '');
+            const today = resolveToday({ override: a['today_override'] });
+            const now = new Date().toISOString();
+            const state = replayLedger(dir, today);
+            const entry = state.contracts.get(id);
+            guardTransition(deriveState(entry, today), 'premise_recheck');
+            const premise = resolvePremiseRef(entry?.premises ?? [], String(a['ref']));
+            if (premise.kind !== 'premise') {
+                return toolError({ ok: false, tool: 'argus_recheck', error_code: 'NOT_RECHECKABLE', message: `P${premise.ordinal} is an open question — it is resolved by you, not re-checked against reality.`, recovery: 'Use argus_premises op="resolve" with your own call.' });
+            }
+            if (premise.status !== 'active') {
+                return toolError({ ok: false, tool: 'argus_recheck', error_code: 'PREMISE_RETIRED', message: `P${premise.ordinal} is ${premise.status}.`, recovery: 'Only active premises are re-checked. See argus_recall view="premises".' });
+            }
+            const finding = String(a['finding']);
+            const source = String(a['source']);
+            const sourceDetail = a['source_detail'];
+            const numericValue = a['numeric_value'];
+            const changed = a['changed'];
+            // ── drift decision (mechanical or host-asserted; plan v5 §7.1) ──
+            const prior = premise.last_recheck;
+            const baselineOnly = !prior;
+            let drifted = false;
+            let reason = 'baseline recorded';
+            let integrityNote;
+            if (!baselineOnly) {
+                const prevNum = prior.numeric_value;
+                if (typeof numericValue === 'number' && typeof prevNum === 'number') {
+                    const d = numericDrift(prevNum, numericValue);
+                    drifted = d.drifted;
+                    reason = d.reason;
+                    if (typeof changed === 'boolean' && changed !== drifted) {
+                        integrityNote = `numeric comparison (${reason}) disagrees with the asserted changed=${changed} — the numbers win; both are on the record.`;
+                    }
+                }
+                else if (typeof changed === 'boolean') {
+                    drifted = changed;
+                    reason = changed ? 'the host asserts the fact changed (see source)' : 'the host asserts the fact is unchanged';
+                    if (changed && normalizePremiseText(finding) === normalizePremiseText(prior.finding)) {
+                        integrityNote = 'asserted changed=true but the finding text is identical to the recorded baseline — recorded as asserted, flagged here.';
+                    }
+                }
+                else {
+                    return toolError({
+                        ok: false, tool: 'argus_recheck', error_code: 'RECHECK_NEEDS_ASSERTION',
+                        message: 'A prior baseline exists but neither a comparable numeric_value nor a `changed` assertion was given.',
+                        recovery: `Pass numeric_value (explicit number) for a numeric fact, or changed=true/false as your research finding vs the baseline: "${prior.finding}".`,
+                    });
+                }
+            }
+            const mkEvent = (targetId, targetPremiseId) => ({
+                id: targetId, event: 'premise_recheck', premise_id: targetPremiseId,
+                finding,
+                ...(typeof numericValue === 'number' ? { numeric_value: numericValue } : {}),
+                drifted, baseline_only: baselineOnly, source,
+                ...(sourceDetail ? { source_detail: sourceDetail } : {}),
+            });
+            const events = [mkEvent(id, premise.premise_id)];
+            // ── explicit cross-decision fan-out (same fact, same evidence) ──
+            const appliedTo = [];
+            if (a['apply_to_matching'] === true) {
+                for (const m of matchingMonitoredPremises(state, id, premise.text)) {
+                    try {
+                        guardTransition(deriveState(m.entry, today), 'premise_recheck');
+                    }
+                    catch {
+                        continue;
+                    } // closed decisions are skipped, never forced
+                    events.push(mkEvent(m.entry.id, m.premise.premise_id));
+                    appliedTo.push({ decision_id: m.entry.id, ref: `P${m.premise.ordinal}` });
+                }
+            }
+            await appendLedger(dir, events, now);
+            const surface = baselineOnly
+                ? `Baseline recorded for P${premise.ordinal}: "${finding}" (${source}). Re-check suggested again in 7 days.`
+                : drifted
+                    ? `The fact under P${premise.ordinal} changed: "${prior.finding}" → "${finding}" (${source}). Whether to revisit this decision is your call.`
+                    : `P${premise.ordinal} unchanged (${source}).`;
+            return envelope({
+                ok: true, tool: 'argus_recheck',
+                surface,
+                // NEXT_ACTIONS is a closed enum (v4 §0.5-2: not extended) — tool
+                // discovery rides the surface text and descriptions instead.
+                next_actions: drifted ? ['argus_recall', 'leave_as_is'] : ['leave_as_is', 'stop'],
+                data: {
+                    id, ref: `P${premise.ordinal}`, premise_id: premise.premise_id,
+                    finding, drifted, baseline_only: baselineOnly, reason,
+                    source, ...(sourceDetail ? { source_detail: sourceDetail } : {}),
+                    ...(integrityNote ? { integrity_note: integrityNote } : {}),
+                    ...(appliedTo.length ? { applied_to_matching: appliedTo } : {}),
+                    ledger_events_written: events.map(() => 'premise_recheck'),
+                },
+            });
+        }
+        catch (e) {
+            return handleToolException('argus_recheck', e);
+        }
+    },
+};