@rvry/mcp 0.12.1 → 0.13.0

package/dist/local-writer.d.ts

@@ -1,30 +1,116 @@
 /**
- * Local session writer -- writes a minimal markdown summary to .rvry/sessions/
- * when a session completes.
+ * Local session writer -- writes a client-owned markdown harvest to
+ * .rvry/<op>/<timestamp>-<slug>/harvest.md when a session completes.
+ *
+ * Optionally emits per-round files (round-N-<mode>.md) when the slash-command
+ * shim passes `rounds[]` (triggered by `--record` flag on the user side).
  *
  * PROTOCOL SURFACE: This file produces user-facing output. It must NEVER contain
- * constraint IDs, detection scores, mode names, gate verdicts, or any engine internals.
- * Only question + harvest data.
+ * constraint IDs, detection scores, mode names used as gate verdicts, or any
+ * engine internals. Only question + client-supplied harvest + recorded bodies.
  */
-interface LocalSessionData {
+export type ChallengeVerdict = 'GO' | 'CONDITIONAL_GO' | 'NO_GO';
+export type ChallengeBias = 'anchoring' | 'framing' | 'authority' | 'sunk_cost' | 'availability' | 'confirmation' | 'none';
+export type ChallengeBlastRadius = 'contained' | 'cascading';
+export type ChallengeAssumptionConfidence = 'high' | 'medium' | 'low';
+export interface ChallengeAssumption {
+    assumption: string;
+    confidence: ChallengeAssumptionConfidence;
+    ifWrong: string;
+    bias: ChallengeBias;
+    biasEvidence: string;
+}
+export interface ChallengeFailureMode {
+    component: string;
+    howItFails: string;
+    blastRadius: ChallengeBlastRadius;
+    detection: string;
+}
+export interface ChallengeCounterArgument {
+    argument: string;
+    rebuttal: string;
+}
+export type ProblemSolveAdversarialVerdict = 'PASSED' | 'CAVEATS' | 'NEEDS_REVISION';
+export type ProblemSolveBias = 'anchoring' | 'framing' | 'authority' | 'sunk_cost' | 'availability' | 'confirmation';
+export interface ProblemSolveBiasOperating {
+    bias: ProblemSolveBias;
+    evidence: string;
+    sourceReflex?: string;
+    correction?: string;
+}
+export interface ProblemSolveFrameReversal {
+    originalFraming?: string;
+    invertedFraming?: string;
+    wouldReachSameConclusion?: boolean;
+}
+export interface ProblemSolveBiasAudit {
+    biasesOperating?: ProblemSolveBiasOperating[];
+    decisionStable?: boolean;
+    frameReversal?: ProblemSolveFrameReversal;
+}
+export interface ClientHarvest {
+    title?: string | null;
+    summary?: string;
+    keyFindings?: string[];
+    shimmer?: string;
+    openQuestions?: string[];
+    followUps?: Array<{
+        question: string;
+        rationale: string;
+    }>;
+    verdict?: ChallengeVerdict;
+    confidence?: number;
+    mitigations?: string[];
+    assumptions?: ChallengeAssumption[];
+    edgeCases?: string[];
+    failureModes?: ChallengeFailureMode[];
+    counterArguments?: ChallengeCounterArgument[];
+    biasAudit?: ProblemSolveBiasAudit;
+    adversarialVerdict?: ProblemSolveAdversarialVerdict;
+    reversalConditions?: string[];
+}
+export interface ClientRound {
+    round: number;
+    mode: string;
+    body: string;
+}
+export interface LocalSessionData {
     sessionId: string;
     operationType: string;
     question: string;
     rounds: number;
-    harvest: {
-        summary: string;
-        keyFindings: string[];
-        openQuestions: string[];
-        followUps: Array<{
-            question: string;
-            rationale: string;
-        }>;
-    };
+    /** Engine-side harvest (telemetry). Kept for potential future use; not written. */
+    harvest?: unknown;
+    /** Client-authored harvest (the synthesis Claude produced). Preferred source. */
+    clientHarvest?: ClientHarvest | null;
+    /** Per-round bodies for `--record` mode. */
+    clientRounds?: ClientRound[] | null;
+    /** Override "now" for deterministic tests. */
+    now?: Date;
+    /** Override base directory (default: process.cwd()). */
+    baseDir?: string;
 }
 /**
- * Write a minimal markdown summary of a completed session to .rvry/sessions/.
+ * Build the main harvest.md content. If `clientHarvest` is missing, emits the
+ * graceful-degradation fallback (question + upgrade notice).
+ *
+ * Per-op rendering (FR-16):
+ * - Challenge: verdict line below H1; Required Mitigations (when CONDITIONAL_GO);
+ *   Assumptions table; Edge Cases bullets; Failure Modes table; Counter-Arguments.
+ * - Problem-solve: Adversarial Verdict line below H1; Bias Audit; Reversal Conditions.
+ * - Other ops: render unchanged.
+ *
+ * All op-specific sections are conditional on the corresponding field being
+ * present and non-empty. Absent field = absent section, never an empty section.
+ */
+export declare function buildMarkdown(data: LocalSessionData, now: Date): string;
+/**
+ * Build a per-round markdown file body.
+ */
+export declare function buildRoundMarkdown(round: ClientRound, now: Date): string;
+/**
+ * Write session folder: harvest.md (always) + optional per-round files.
  *
  * Disabled via RVRY_LOCAL_SESSIONS=0. Fails silently on any error.
  */
 export declare function writeLocalSession(data: LocalSessionData): Promise<void>;
-export {};

package/dist/local-writer.js

@@ -1,16 +1,32 @@
 /**
- * Local session writer -- writes a minimal markdown summary to .rvry/sessions/
- * when a session completes.
+ * Local session writer -- writes a client-owned markdown harvest to
+ * .rvry/<op>/<timestamp>-<slug>/harvest.md when a session completes.
+ *
+ * Optionally emits per-round files (round-N-<mode>.md) when the slash-command
+ * shim passes `rounds[]` (triggered by `--record` flag on the user side).
  *
  * PROTOCOL SURFACE: This file produces user-facing output. It must NEVER contain
- * constraint IDs, detection scores, mode names, gate verdicts, or any engine internals.
- * Only question + harvest data.
+ * constraint IDs, detection scores, mode names used as gate verdicts, or any
+ * engine internals. Only question + client-supplied harvest + recorded bodies.
  */
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+/** Op label for H1 headings. */
+const OP_LABELS = {
+    deepthink: 'RVRY Deepthink',
+    problem_solve: 'RVRY Problem-Solve',
+    think: 'RVRY Think',
+    challenge: 'RVRY Challenge',
+    meta: 'RVRY Meta',
+};
+function opLabel(operationType) {
+    return OP_LABELS[operationType] ?? `RVRY ${operationType}`;
+}
+function opFolder(operationType) {
+    return operationType.replace(/_/g, '-');
+}
 /**
- * Slugify a question string for use in filenames.
- * Lowercases, replaces non-alphanumeric runs with hyphens, trims, and caps at maxLen chars.
+ * Slugify text for filenames/folders.
  */
 function slugify(text, maxLen = 50) {
     return text
@@ -20,9 +36,7 @@ function slugify(text, maxLen = 50) {
         .slice(0, maxLen)
         .replace(/-+$/, '');
 }
-/**
- * Format a Date as YYYYMMDD-HHMM for filenames.
- */
+/** YYYYMMDD-HHMM for folder names. */
 function formatTimestamp(date) {
     const y = date.getFullYear().toString();
     const mo = (date.getMonth() + 1).toString().padStart(2, '0');
@@ -31,9 +45,7 @@ function formatTimestamp(date) {
     const mi = date.getMinutes().toString().padStart(2, '0');
     return `${y}${mo}${d}-${h}${mi}`;
 }
-/**
- * Format a Date as YYYY-MM-DD HH:MM for YAML frontmatter.
- */
+/** YYYY-MM-DD HH:MM for italic date line. */
 function formatDate(date) {
     const y = date.getFullYear().toString();
     const mo = (date.getMonth() + 1).toString().padStart(2, '0');
@@ -43,72 +55,355 @@ function formatDate(date) {
     return `${y}-${mo}-${d} ${h}:${mi}`;
 }
 /**
- * Build the markdown content for a completed session.
+ * Title-case the first 4 words of a question as an H1 fallback.
+ */
+function fallbackTitleFromQuestion(question) {
+    const words = question
+        .trim()
+        .split(/\s+/)
+        .slice(0, 4)
+        .map((w) => w.replace(/[^\p{L}\p{N}'-]/gu, ''))
+        .filter((w) => w.length > 0);
+    if (words.length === 0)
+        return 'Session';
+    return words
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+        .join(' ');
+}
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function isNonEmptyArray(v) {
+    return Array.isArray(v) && v.length > 0;
+}
+/**
+ * Build the main harvest.md content. If `clientHarvest` is missing, emits the
+ * graceful-degradation fallback (question + upgrade notice).
+ *
+ * Per-op rendering (FR-16):
+ * - Challenge: verdict line below H1; Required Mitigations (when CONDITIONAL_GO);
+ *   Assumptions table; Edge Cases bullets; Failure Modes table; Counter-Arguments.
+ * - Problem-solve: Adversarial Verdict line below H1; Bias Audit; Reversal Conditions.
+ * - Other ops: render unchanged.
+ *
+ * All op-specific sections are conditional on the corresponding field being
+ * present and non-empty. Absent field = absent section, never an empty section.
  */
-function buildMarkdown(data, now) {
+export function buildMarkdown(data, now) {
+    const label = opLabel(data.operationType);
     const lines = [];
-    // YAML frontmatter
-    lines.push('---');
-    lines.push(`session: ${data.sessionId}`);
-    lines.push(`operation: ${data.operationType}`);
-    lines.push(`date: ${formatDate(now)}`);
-    lines.push(`rounds: ${data.rounds}`);
-    lines.push('---');
-    lines.push('');
-    // Question
-    lines.push(`# ${data.question}`);
-    lines.push('');
-    // Summary
-    lines.push('## Summary');
-    lines.push(data.harvest.summary);
-    lines.push('');
-    // Key Findings
-    if (data.harvest.keyFindings.length > 0) {
-        lines.push('## Key Findings');
-        for (const finding of data.harvest.keyFindings) {
-            lines.push(`- ${finding}`);
-        }
+    const harvest = data.clientHarvest;
+    if (!harvest) {
+        // Fallback: no client synthesis provided.
+        const title = fallbackTitleFromQuestion(data.question);
+        lines.push(`# ${label} — ${title}`);
+        lines.push('');
+        lines.push(`*${formatDate(now)}*`);
+        lines.push('');
+        lines.push('### Prompt');
+        lines.push('');
+        lines.push(data.question);
         lines.push('');
+        lines.push('## Summary');
+        lines.push('');
+        lines.push('*(Synthesis not provided — upgrade your slash commands by re-running `rvry-mcp setup`.)*');
+        lines.push('');
+        return lines.join('\n');
+    }
+    const title = isNonEmptyString(harvest.title)
+        ? harvest.title.trim()
+        : fallbackTitleFromQuestion(data.question);
+    lines.push(`# ${label} — ${title}`);
+    // Op-specific verdict line directly below H1.
+    if (data.operationType === 'challenge') {
+        const verdictLine = renderChallengeVerdictLine(harvest);
+        if (verdictLine)
+            lines.push(verdictLine);
+    }
+    else if (data.operationType === 'problem_solve') {
+        const verdictLine = renderProblemSolveVerdictLine(harvest);
+        if (verdictLine)
+            lines.push(verdictLine);
+    }
+    lines.push(`*${formatDate(now)}*`);
+    lines.push('');
+    lines.push('### Prompt');
+    lines.push('');
+    lines.push(data.question);
+    lines.push('');
+    if (isNonEmptyString(harvest.shimmer)) {
+        lines.push('## Shimmer');
+        lines.push('');
+        lines.push(harvest.shimmer.trim());
+        lines.push('');
+    }
+    if (isNonEmptyString(harvest.summary)) {
+        lines.push('## Summary');
+        lines.push('');
+        lines.push(harvest.summary.trim());
+        lines.push('');
+    }
+    // Challenge-specific structured sections (in declared rendering order).
+    if (data.operationType === 'challenge') {
+        appendChallengeMitigations(lines, harvest);
+        appendChallengeAssumptions(lines, harvest);
+        appendChallengeEdgeCases(lines, harvest);
+        appendChallengeFailureModes(lines, harvest);
+        appendChallengeCounterArguments(lines, harvest);
+    }
+    // Problem-solve-specific structured sections.
+    if (data.operationType === 'problem_solve') {
+        appendProblemSolveBiasAudit(lines, harvest);
+        appendProblemSolveReversalConditions(lines, harvest);
+    }
+    if (isNonEmptyArray(harvest.keyFindings)) {
+        const findings = harvest.keyFindings.filter(isNonEmptyString);
+        if (findings.length > 0) {
+            lines.push('## Key Findings');
+            lines.push('');
+            for (const f of findings)
+                lines.push(`- ${f.trim()}`);
+            lines.push('');
+        }
+    }
+    if (isNonEmptyArray(harvest.openQuestions)) {
+        const qs = harvest.openQuestions.filter(isNonEmptyString);
+        if (qs.length > 0) {
+            lines.push('## Open Questions');
+            lines.push('');
+            for (const q of qs)
+                lines.push(`- ${q.trim()}`);
+            lines.push('');
+        }
+    }
+    if (isNonEmptyArray(harvest.followUps)) {
+        const fus = harvest.followUps.filter((f) => f && isNonEmptyString(f.question));
+        if (fus.length > 0) {
+            lines.push('## Follow-ups');
+            lines.push('');
+            for (const f of fus) {
+                if (isNonEmptyString(f.rationale)) {
+                    lines.push(`- ${f.question.trim()} — ${f.rationale.trim()}`);
+                }
+                else {
+                    lines.push(`- ${f.question.trim()}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+// ─────────────────────────────────────────────────────────────────────
+// Challenge renderers
+// ─────────────────────────────────────────────────────────────────────
+const CHALLENGE_VERDICT_LABELS = {
+    GO: 'GO',
+    CONDITIONAL_GO: 'CONDITIONAL_GO',
+    NO_GO: 'NO_GO',
+};
+function renderChallengeVerdictLine(harvest) {
+    const verdict = harvest.verdict;
+    if (!verdict || !CHALLENGE_VERDICT_LABELS[verdict])
+        return null;
+    const confidenceText = typeof harvest.confidence === 'number'
+        ? ` (confidence: ${harvest.confidence.toFixed(1)})`
+        : '';
+    return `**Verdict: ${CHALLENGE_VERDICT_LABELS[verdict]}${confidenceText}**`;
+}
+function appendChallengeMitigations(lines, harvest) {
+    // Conditional: only render when verdict is CONDITIONAL_GO and mitigations are non-empty.
+    if (harvest.verdict !== 'CONDITIONAL_GO')
+        return;
+    const mitigations = (harvest.mitigations ?? []).filter(isNonEmptyString);
+    if (mitigations.length === 0)
+        return;
+    lines.push('## Required Mitigations');
+    lines.push('');
+    for (const m of mitigations)
+        lines.push(`- ${m.trim()}`);
+    lines.push('');
+}
+function appendChallengeAssumptions(lines, harvest) {
+    const assumptions = (harvest.assumptions ?? []).filter((a) => a && isNonEmptyString(a.assumption));
+    if (assumptions.length === 0)
+        return;
+    lines.push('## Assumptions');
+    lines.push('');
+    lines.push('| Assumption | Confidence | If Wrong | Bias | Bias Evidence |');
+    lines.push('| --- | --- | --- | --- | --- |');
+    for (const a of assumptions) {
+        lines.push(`| ${escapeTableCell(a.assumption)} | ${escapeTableCell(a.confidence ?? '')} | ${escapeTableCell(a.ifWrong ?? '')} | ${escapeTableCell(a.bias ?? '')} | ${escapeTableCell(a.biasEvidence ?? '')} |`);
+    }
+    lines.push('');
+}
+function appendChallengeEdgeCases(lines, harvest) {
+    const cases = (harvest.edgeCases ?? []).filter(isNonEmptyString);
+    if (cases.length === 0)
+        return;
+    lines.push('## Edge Cases');
+    lines.push('');
+    for (const c of cases)
+        lines.push(`- ${c.trim()}`);
+    lines.push('');
+}
+function appendChallengeFailureModes(lines, harvest) {
+    const modes = (harvest.failureModes ?? []).filter((m) => m && isNonEmptyString(m.component));
+    if (modes.length === 0)
+        return;
+    lines.push('## Failure Modes');
+    lines.push('');
+    lines.push('| Component | How It Fails | Blast Radius | Detection |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const m of modes) {
+        lines.push(`| ${escapeTableCell(m.component)} | ${escapeTableCell(m.howItFails ?? '')} | ${escapeTableCell(m.blastRadius ?? '')} | ${escapeTableCell(m.detection ?? '')} |`);
     }
-    // Open Questions
-    if (data.harvest.openQuestions.length > 0) {
-        lines.push('## Open Questions');
-        for (const q of data.harvest.openQuestions) {
-            lines.push(`- ${q}`);
+    lines.push('');
+}
+function appendChallengeCounterArguments(lines, harvest) {
+    const args = (harvest.counterArguments ?? []).filter((c) => c && isNonEmptyString(c.argument));
+    if (args.length === 0)
+        return;
+    lines.push('## Counter-Arguments');
+    lines.push('');
+    for (const c of args) {
+        lines.push(`- **For:** ${c.argument.trim()}`);
+        if (isNonEmptyString(c.rebuttal)) {
+            lines.push(`  **Against:** ${c.rebuttal.trim()}`);
+        }
+    }
+    lines.push('');
+}
+// ─────────────────────────────────────────────────────────────────────
+// Problem-solve renderers
+// ─────────────────────────────────────────────────────────────────────
+const PROBLEM_SOLVE_VERDICT_LABELS = {
+    PASSED: 'PASSED',
+    CAVEATS: 'CAVEATS',
+    NEEDS_REVISION: 'NEEDS_REVISION',
+};
+function renderProblemSolveVerdictLine(harvest) {
+    const verdict = harvest.adversarialVerdict;
+    if (!verdict || !PROBLEM_SOLVE_VERDICT_LABELS[verdict])
+        return null;
+    return `**Adversarial Verdict: ${PROBLEM_SOLVE_VERDICT_LABELS[verdict]}**`;
+}
+function appendProblemSolveBiasAudit(lines, harvest) {
+    const audit = harvest.biasAudit;
+    if (!audit)
+        return;
+    const operating = (audit.biasesOperating ?? []).filter((b) => b && isNonEmptyString(b.bias) && isNonEmptyString(b.evidence));
+    const hasReversal = audit.frameReversal && (isNonEmptyString(audit.frameReversal.originalFraming) ||
+        isNonEmptyString(audit.frameReversal.invertedFraming) ||
+        typeof audit.frameReversal.wouldReachSameConclusion === 'boolean');
+    const hasStability = typeof audit.decisionStable === 'boolean';
+    if (operating.length === 0 && !hasReversal && !hasStability)
+        return;
+    lines.push('## Bias Audit');
+    lines.push('');
+    if (operating.length > 0) {
+        for (const b of operating) {
+            lines.push(`- **${b.bias.trim()}**: ${b.evidence.trim()}`);
+            if (isNonEmptyString(b.sourceReflex)) {
+                lines.push(`  - Source reflex: ${b.sourceReflex.trim()}`);
+            }
+            if (isNonEmptyString(b.correction)) {
+                lines.push(`  - Correction: ${b.correction.trim()}`);
+            }
         }
         lines.push('');
     }
-    // Follow-ups
-    if (data.harvest.followUps.length > 0) {
-        lines.push('## Follow-ups');
-        for (const f of data.harvest.followUps) {
-            lines.push(`- ${f.question} — ${f.rationale}`);
+    if (hasStability) {
+        lines.push(`Decision stable under bias check: ${audit.decisionStable ? 'yes' : 'no'}`);
+        lines.push('');
+    }
+    if (hasReversal && audit.frameReversal) {
+        lines.push('### Frame Reversal');
+        lines.push('');
+        if (isNonEmptyString(audit.frameReversal.originalFraming)) {
+            lines.push(`- Original: ${audit.frameReversal.originalFraming.trim()}`);
+        }
+        if (isNonEmptyString(audit.frameReversal.invertedFraming)) {
+            lines.push(`- Inverted: ${audit.frameReversal.invertedFraming.trim()}`);
+        }
+        if (typeof audit.frameReversal.wouldReachSameConclusion === 'boolean') {
+            lines.push(`- Same conclusion under reversal: ${audit.frameReversal.wouldReachSameConclusion ? 'yes' : 'no'}`);
         }
         lines.push('');
     }
+}
+function appendProblemSolveReversalConditions(lines, harvest) {
+    const conds = (harvest.reversalConditions ?? []).filter(isNonEmptyString);
+    if (conds.length === 0)
+        return;
+    lines.push('## Reversal Conditions');
+    lines.push('');
+    for (const c of conds)
+        lines.push(`- ${c.trim()}`);
+    lines.push('');
+}
+/**
+ * Escape pipe and newline characters in markdown table cells.
+ * Keeps cell content on a single line and prevents pipe characters from
+ * breaking column alignment.
+ */
+function escapeTableCell(value) {
+    return value
+        .replace(/\r?\n/g, ' ')
+        .replace(/\|/g, '\\|')
+        .trim();
+}
+/**
+ * Build a per-round markdown file body.
+ */
+export function buildRoundMarkdown(round, now) {
+    const modeLabel = round.mode
+        ? round.mode.charAt(0).toUpperCase() + round.mode.slice(1)
+        : 'Round';
+    const lines = [];
+    lines.push(`# Round ${round.round} — ${modeLabel}`);
+    lines.push('');
+    lines.push(`*${formatDate(now)}*`);
+    lines.push('');
+    lines.push(round.body ?? '');
+    lines.push('');
     return lines.join('\n');
 }
+function roundFilename(round) {
+    const modeSafe = (round.mode || 'round')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'round';
+    return `round-${round.round}-${modeSafe}.md`;
+}
 /**
- * Write a minimal markdown summary of a completed session to .rvry/sessions/.
+ * Write session folder: harvest.md (always) + optional per-round files.
  *
  * Disabled via RVRY_LOCAL_SESSIONS=0. Fails silently on any error.
  */
 export async function writeLocalSession(data) {
-    // Check opt-out
     if (process.env.RVRY_LOCAL_SESSIONS === '0')
         return;
     try {
-        const now = new Date();
+        const now = data.now ?? new Date();
         const timestamp = formatTimestamp(now);
-        const slug = slugify(data.question);
-        const filename = `${timestamp}-${data.operationType}-${slug}.md`;
-        const sessionsDir = join(process.cwd(), '.rvry', 'sessions');
-        mkdirSync(sessionsDir, { recursive: true });
-        const filePath = join(sessionsDir, filename);
-        const content = buildMarkdown(data, now);
-        writeFileSync(filePath, content, 'utf-8');
+        const slug = slugify(data.question) || 'session';
+        const folderName = `${timestamp}-${slug}`;
+        const baseDir = data.baseDir ?? process.cwd();
+        const sessionDir = join(baseDir, '.rvry', opFolder(data.operationType), folderName);
+        mkdirSync(sessionDir, { recursive: true });
+        const harvestPath = join(sessionDir, 'harvest.md');
+        writeFileSync(harvestPath, buildMarkdown(data, now), 'utf-8');
+        if (isNonEmptyArray(data.clientRounds)) {
+            for (const r of data.clientRounds) {
+                if (!r || typeof r.round !== 'number' || typeof r.mode !== 'string')
+                    continue;
+                const fp = join(sessionDir, roundFilename(r));
+                writeFileSync(fp, buildRoundMarkdown(r, now), 'utf-8');
+            }
+        }
     }
     catch {
-        // Fail silently -- this is a convenience feature, not critical path
+        // Fail silently -- convenience feature, not critical path.
     }
 }