@blockrun/franklin 3.19.0 → 3.20.0

package/dist/skills-bundled/trade-discussion/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: trade-discussion
+description: Record market commentary, hypotheses, or open observations as a structured note — no trade fired, no position sized. Lighter than /trade-strategy. Saves to ~/.blockrun/notes/ for future reference. Use when the user wants to think out loud about the market.
+triggers:
+  - "market commentary"
+  - "trade discussion"
+  - "observation"
+  - "just thinking"
+  - "market thought"
+  - "log a thought"
+argument-hint: <topic>
+cost-receipt: false
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This skill is the lightest of the three trading skills — no trade, no full strategy doc, just a short observation with enough structure to be useful later.
+
+## Workflow
+
+1. **Gather context only if cheap or asked.** Don't burn $0.005 on a chain query for a discussion note unless the user requested data. Default: write the note from what you already know.
+
+2. **Write the note.** Use the `Write` tool to create:
+
+   - Path: `~/.blockrun/notes/<YYYY-MM-DD>-<slug>-discussion.md`
+   - Slug: 3–5-word kebab-case (e.g. `etf-flow-divergence-watch`)
+   - Content template:
+
+```markdown
+# Discussion — <Title>
+
+**Date:** <YYYY-MM-DD>
+**Author:** Franklin (skill: /trade-discussion)
+
+## Observation
+
+<1–3 paragraphs.>
+
+## Symbols mentioned
+
+`<SYMBOL1>` `<SYMBOL2>` (etc.)
+
+## Tags
+
+`<sentiment>` `<watch>` `<thesis-fragment>` (etc.)
+
+## Open questions
+
+- <Question 1 — what would confirm or invalidate this?>
+- <Question 2>
+
+## Possible follow-ups
+
+- `/surf-market` for <specific data>
+- `/surf-social` for <specific KOL or mindshare check>
+- `/trade-strategy` if this matures into a plan
+- `/trade-signal` if a clear entry emerges
+```
+
+3. **Confirm.** Report back: "Note saved to `<path>`. Tagged `<tags>`. No trade fired. If this hardens into a plan, run `/trade-strategy <topic>`."
+
+4. **Do not call `TradingOpenPosition`.** Discussion notes are explicitly trade-free.
+
+## When this skill fits vs the alternatives
+
+- **`/trade-discussion`** — open-ended observation, hypothesis, "what if". Cheapest, least structured.
+- **`/trade-strategy`** — committed plan with entry/exit/sizing. Reach for this when an observation has hardened.
+- **`/trade-signal`** — the actual trade. Fires `TradingOpenPosition`, hits the wallet (paper trading) and the journal.
+
+## The user said
+
+$ARGUMENTS

package/dist/skills-bundled/trade-signal/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: trade-signal
+description: Open a paper-trade position with a structured rationale — direction, price target, stop, time horizon, conviction, evidence, tags, thesis. The journal scores the trade on discipline (verifiability, evidence, specificity, novelty, review), not P&L, and surfaces the trend in TradingPortfolio. Use any time the user wants to open a position with intent, not vibes.
+triggers:
+  - "open a trade"
+  - "buy"
+  - "long"
+  - "short"
+  - "take a position"
+  - "trade signal"
+  - "trade idea"
+argument-hint: <symbol or thesis>
+cost-receipt: false
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This is paper trading — fills are simulated against a live mark — so the value is the discipline, not the dollars. Every trade entered through this skill carries a rationale that the journal scorer evaluates on five dimensions:
+
+| Dimension | Weight | Earned by |
+|---|---|---|
+| verifiability | 30% | direction + priceTarget both set |
+| evidence | 25% | thesis ≥ 200 chars + 3 evidence items + indicator keywords (RSI/MACD/funding/etc.) |
+| specificity | 20% | symbol + ≥ 2 tags |
+| novelty | 15% | not the 4th identical revenge-trade this week |
+| review | 10% | post-trade note left at close |
+
+Total is a 0–5 score, persisted with the trade and averaged across the last 10 entries in the portfolio footer.
+
+## Workflow
+
+1. **Read the request.** The user's argument is below under "The user said". If it's a complete thesis (symbol + direction + reasoning + numbers), proceed to step 3. If anything's vague, ask **one** clarifying question — the cheapest call you have on the wallet is "tell me more before I burn $0.001 on a market quote."
+
+2. **Optional context** — if you don't already have a recent quote, call `TradingMarket({ ticker, assetClass })` (free for crypto, $0.001 for stocks). For thesis support beyond price, the `/surf-market`, `/surf-chain`, or `/surf-social` skills can be invoked, each documenting their own endpoint costs.
+
+3. **Construct the rationale.** Fill as many fields as the request justifies:
+
+   - `direction`: `"long"` for buys (paper trading is long-only today).
+   - `priceTarget`: where you expect to take profit (USD).
+   - `stopLoss`: where you'll exit if wrong (USD).
+   - `timeHorizon`: `"1h"`, `"1d"`, `"1w"`, `"1m"`, `"3m"` — match the trade type.
+   - `conviction`: 1 (low, "small probe") → 5 (high, "size up").
+   - `evidence`: 2–4 items. Indicator readings, news links, on-chain stats, comparable trades.
+   - `tags`: 2+ categories — `"momentum"`, `"mean-reversion"`, `"macro"`, `"event"`, `"sentiment"`, etc.
+   - `thesis`: a paragraph (target 200+ chars) connecting the evidence to the trade. Mention at least one named indicator if you cite one.
+
+4. **Size with discipline.** Default per-position cap is $400, total exposure $900 (see TradingPortfolio for current utilization). Don't size beyond what conviction justifies — a conviction-2 trade at the cap is a discipline red flag.
+
+5. **Fire the trade** by calling `TradingOpenPosition`:
+
+```
+TradingOpenPosition({
+  symbol: "<TICKER>",
+  qty: <quantity>,
+  priceUsd: <fill price>,
+  rationale: {
+    direction: "long",
+    priceTarget: <number>,
+    stopLoss: <number>,
+    timeHorizon: "<period>",
+    conviction: <1-5>,
+    evidence: ["<source 1>", "<source 2>", ...],
+    tags: ["<tag 1>", "<tag 2>"],
+    thesis: "<200+ char paragraph>"
+  }
+})
+```
+
+6. **Surface the score.** The tool result shows the fill. Then call `TradingPortfolio` once and quote the new discipline score back to the user — "Trade booked. Journal score on this entry: 4.2/5. Discipline trend over the last 10 trades: 3.6/5 (evidence flagged below 3 — keep citing indicators)."
+
+7. **Stop.** Don't fan out to multiple trades unless the user explicitly asks for portfolio construction. One disciplined trade beats five vibes-trades.
+
+## Anti-patterns
+
+- Firing `TradingOpenPosition` without a rationale block. The journal still records the trade but it scores ~1/5 on discipline. Don't do this.
+- Inventing evidence. If the user says "feels like a top" and you can't find supporting data, write that into the thesis verbatim and let the score reflect it. The journal is a mirror, not a press release.
+- Trading the same symbol + direction four times in a week. The novelty penalty fires for a reason — that's revenge trading.
+
+## The user said
+
+$ARGUMENTS

package/dist/skills-bundled/trade-strategy/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: trade-strategy
+description: Write a long-form trading strategy document — thesis, entry triggers, exit rules, position sizing, hold horizon, kill criteria. No trade is fired. Saves a structured markdown note to ~/.blockrun/notes/. Use when the user wants to plan an approach before committing capital.
+triggers:
+  - "trading strategy"
+  - "write a strategy"
+  - "strategy doc"
+  - "trade plan"
+  - "planning a trade"
+argument-hint: <topic or thesis>
+cost-receipt: false
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This skill captures *intent* before *action*. The user wants a written strategy, not an executed trade. Result: a markdown file under `~/.blockrun/notes/` that the user (and future Franklin sessions) can reference when the actual trade fires via `/trade-signal`.
+
+## Workflow
+
+1. **Clarify if needed.** If the argument is just a ticker ("BTC") without a direction, ask one clarifying question about what the user is trying to do (long, short, range, event-driven).
+
+2. **Gather supporting context.** Use the `/surf-market`, `/surf-chain`, or `/surf-social` skills to pull data that informs the strategy. Each surfaces its own cost; mention what you spent at the end.
+
+3. **Write the strategy doc.** Use the `Write` tool to create:
+
+   - Path: `~/.blockrun/notes/<YYYY-MM-DD>-<slug>-strategy.md` (replace `~` with the user's actual home dir; ask if you don't know it, or run `Bash("echo $HOME")` once)
+   - Slug: short kebab-case identifier derived from the topic (e.g. `btc-pre-halving-long`)
+   - Content template:
+
+```markdown
+# Strategy — <Title>
+
+**Date:** <YYYY-MM-DD>
+**Author:** Franklin (skill: /trade-strategy)
+**Status:** draft
+
+## Thesis
+
+<2–4 paragraphs: why this trade now. Cite the data sources you pulled.>
+
+## Symbols & direction
+
+- Primary: <SYMBOL> <long|short>
+- Hedges (if any): <SYMBOL> <long|short>
+
+## Entry triggers
+
+- <Specific price levels, indicator readings, or events that must hold>
+- <…>
+
+## Position sizing
+
+- Per-symbol notional cap: $<N> (vs Franklin's $400 default)
+- Conviction tier: <1–5> — justification: <…>
+
+## Exit rules
+
+- Take profit: <price | indicator | event>
+- Stop loss: <price | indicator | event>
+- Time stop: exit by <date / horizon> regardless
+
+## Kill criteria
+
+What invalidates the entire thesis? (Be specific — name a level, a metric, or a market regime change.)
+
+## Evidence
+
+- <source 1>
+- <source 2>
+- <indicator reading>
+
+## Tags
+
+`<momentum>` `<macro>` `<event>` (etc.)
+
+## Linked trades
+
+(Populated as `/trade-signal` invocations reference this doc.)
+```
+
+4. **Confirm the path.** Report back to the user: "Strategy saved to `<path>`. Open it with your editor or pull it into your next `/trade-signal` call as context. Discipline score on the strategy is captured when the first trade fires."
+
+5. **Do not call `TradingOpenPosition`.** This skill is plan-only. The user fires the trade separately via `/trade-signal` when ready.
+
+## Anti-patterns
+
+- Skipping kill criteria. Every strategy has them; "I'll know when to exit" is not a strategy.
+- Position sizing without conviction-justified caps. A conviction-2 strategy that loads the full $400 cap is theater.
+- Writing a strategy doc and immediately firing a trade. The point of separating the two is to force a pause. If the user wants both, run `/trade-strategy` first, then `/trade-signal` referencing the saved file.
+
+## The user said
+
+$ARGUMENTS

package/dist/tools/trading-execute.js

@@ -9,7 +9,38 @@
  * The split mirrors OpenBB's router/engine/view layering and keeps every
  * layer testable in isolation.
  */
+import { scoreEntry } from '../trading/journal-quality.js';
+import { renderDisciplineFooter } from '../trading/journal-display.js';
 import { renderOrderBlocked, renderOrderFilled, renderPortfolio, renderPositionClosed, renderTradeHistory, windowToSince, } from './trading-views.js';
+/**
+ * Pull a `rationale` object out of the LLM's input safely. Skips fields
+ * that don't match the expected shape so a half-filled rationale is still
+ * captured (the scorer rewards completeness, doesn't require it).
+ */
+function extractRationale(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const out = {};
+    if (r.direction === 'long' || r.direction === 'short' || r.direction === 'neutral')
+        out.direction = r.direction;
+    if (typeof r.priceTarget === 'number' && r.priceTarget > 0)
+        out.priceTarget = r.priceTarget;
+    if (typeof r.stopLoss === 'number' && r.stopLoss > 0)
+        out.stopLoss = r.stopLoss;
+    if (typeof r.timeHorizon === 'string' && r.timeHorizon.trim())
+        out.timeHorizon = r.timeHorizon.trim();
+    if (typeof r.conviction === 'number' && r.conviction >= 1 && r.conviction <= 5) {
+        out.conviction = Math.round(r.conviction);
+    }
+    if (Array.isArray(r.evidence))
+        out.evidence = r.evidence.filter((x) => typeof x === 'string');
+    if (Array.isArray(r.tags))
+        out.tags = r.tags.filter((x) => typeof x === 'string');
+    if (typeof r.thesis === 'string' && r.thesis.trim())
+        out.thesis = r.thesis.trim();
+    return Object.keys(out).length ? out : undefined;
+}
 function enginePortfolio(engine) {
     return engine.deps.portfolio;
 }
@@ -44,7 +75,15 @@ export function createTradingCapabilities(deps) {
         concurrent: true,
         async execute(_input, _ctx) {
             const snap = await buildPortfolioSnapshot(engine);
-            return { output: renderPortfolio(snap, riskConfig) };
+            const base = renderPortfolio(snap, riskConfig);
+            if (!tradeLog)
+                return { output: base };
+            // Journal discipline footer — last 10 scored entries from the log.
+            // If no entries carry qualityScore yet (pre-v3.20 history or no rationale
+            // ever recorded), renderDisciplineFooter returns null and we skip silently.
+            const recent = tradeLog.recent(10);
+            const footer = renderDisciplineFooter(recent);
+            return { output: footer ? `${base}\n${footer}` : base };
         },
     };
     const tradingOpenPosition = {
@@ -53,7 +92,10 @@ export function createTradingCapabilities(deps) {
             description: 'Open (buy into) a position. Pre-trade risk checks enforce per-position and total ' +
                 'exposure caps; a blocked order returns a normal text result with the reason — the ' +
                 'agent should read it and try again with a smaller qty if appropriate. This is paper ' +
-                'trading: fills are simulated against the provided price.',
+                'trading: fills are simulated against the provided price. ' +
+                'Optionally pass a `rationale` object documenting why — direction, price target, stop, ' +
+                'time horizon, conviction, evidence, tags, thesis. The journal scores entries on ' +
+                'rationale completeness (not P&L) and surfaces the discipline trend in TradingPortfolio.',
             input_schema: {
                 type: 'object',
                 required: ['symbol', 'qty', 'priceUsd'],
@@ -61,6 +103,21 @@ export function createTradingCapabilities(deps) {
                     symbol: { type: 'string', description: 'Ticker (e.g., "BTC", "ETH")' },
                     qty: { type: 'number', description: 'Quantity in base units (e.g., 0.01 for 0.01 BTC)' },
                     priceUsd: { type: 'number', description: 'Price at which to execute, in USD' },
+                    rationale: {
+                        type: 'object',
+                        description: 'Optional — why you are opening this position. Captured in the trade journal and scored on discipline (verifiability, evidence, specificity, novelty, review).',
+                        properties: {
+                            direction: { type: 'string', enum: ['long', 'short', 'neutral'], description: 'Trade direction. For paper-trade longs use "long".' },
+                            priceTarget: { type: 'number', description: 'Expected exit price (USD).' },
+                            stopLoss: { type: 'number', description: 'Forced exit floor (USD).' },
+                            timeHorizon: { type: 'string', description: 'How long you expect to hold: "1h", "1d", "1w", "1m", "3m", etc.' },
+                            conviction: { type: 'number', description: 'How sure are you, 1 (low) to 5 (high).' },
+                            evidence: { type: 'array', items: { type: 'string' }, description: 'Sources, links, or indicator names supporting the thesis.' },
+                            tags: { type: 'array', items: { type: 'string' }, description: 'Categorization: "momentum", "macro", "mean-reversion", etc.' },
+                            thesis: { type: 'string', description: 'Free-text reasoning (≥200 chars scores best).' },
+                        },
+                        additionalProperties: false,
+                    },
                 },
                 additionalProperties: false,
             },
@@ -84,7 +141,8 @@ export function createTradingCapabilities(deps) {
                 return { output: `No-op: ${outcome.reason}` };
             }
             if (tradeLog) {
-                tradeLog.append({
+                const rationale = extractRationale(input.rationale);
+                const draftEntry = {
                     timestamp: Date.now(),
                     symbol,
                     side: 'buy',
@@ -92,7 +150,11 @@ export function createTradingCapabilities(deps) {
                     priceUsd: outcome.fill.priceUsd,
                     feeUsd: outcome.fill.feeUsd,
                     realizedPnlUsd: 0,
-                });
+                    rationale,
+                };
+                const history = tradeLog.all();
+                draftEntry.qualityScore = scoreEntry(draftEntry, history);
+                tradeLog.append(draftEntry);
             }
             if (onStateChange)
                 await onStateChange();
@@ -110,7 +172,9 @@ export function createTradingCapabilities(deps) {
             name: 'TradingClosePosition',
             description: 'Close (sell) an open position, realizing P&L against the average entry price. ' +
                 "Omit qty to flatten the position entirely; pass qty to partially reduce. Uses the " +
-                "exchange's current mark — no manual price required.",
+                "exchange's current mark — no manual price required. " +
+                'Optionally pass a `review` note documenting whether the trade hit its plan; that ' +
+                'boosts the journal discipline score for this entry.',
             input_schema: {
                 type: 'object',
                 required: ['symbol'],
@@ -120,6 +184,10 @@ export function createTradingCapabilities(deps) {
                         type: 'number',
                         description: 'Optional — partial size. Omit to close the full position.',
                     },
+                    review: {
+                        type: 'string',
+                        description: 'Optional post-trade note: did the trade hit its target / stop / hypothesis? Boosts the journal "review" score component.',
+                    },
                 },
                 additionalProperties: false,
             },
@@ -145,7 +213,8 @@ export function createTradingCapabilities(deps) {
             }
             const tradeRealized = portfolio.realizedPnlUsd - priorRealized;
             if (tradeLog) {
-                tradeLog.append({
+                const review = typeof input.review === 'string' && input.review.trim() ? input.review.trim() : undefined;
+                const draftEntry = {
                     timestamp: Date.now(),
                     symbol,
                     side: 'sell',
@@ -153,7 +222,10 @@ export function createTradingCapabilities(deps) {
                     priceUsd: outcome.fill.priceUsd,
                     feeUsd: outcome.fill.feeUsd,
                     realizedPnlUsd: tradeRealized,
-                });
+                    review,
+                };
+                draftEntry.qualityScore = scoreEntry(draftEntry, tradeLog.all());
+                tradeLog.append(draftEntry);
             }
             if (onStateChange)
                 await onStateChange();

package/dist/trading/journal-display.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Markdown footer for `TradingPortfolio` — the discipline mirror.
+ *
+ * Shows the last-N trades' average quality score and flags any component
+ * that scored below 3.0 (the threshold AI-Trader uses too). The footer
+ * is the only place the discipline metric surfaces today; future
+ * releases can drop it into the panel Audit tab too.
+ *
+ * Pure formatting; takes AggregateScore from journal-quality.ts.
+ */
+import type { TradeLogEntry } from './trade-log.js';
+/**
+ * Build the discipline footer markdown for an existing portfolio output.
+ * Returns `null` when there's nothing to show (no scored entries yet).
+ */
+export declare function renderDisciplineFooter(entries: TradeLogEntry[]): string | null;

package/dist/trading/journal-display.js

@@ -0,0 +1,53 @@
+/**
+ * Markdown footer for `TradingPortfolio` — the discipline mirror.
+ *
+ * Shows the last-N trades' average quality score and flags any component
+ * that scored below 3.0 (the threshold AI-Trader uses too). The footer
+ * is the only place the discipline metric surfaces today; future
+ * releases can drop it into the panel Audit tab too.
+ *
+ * Pure formatting; takes AggregateScore from journal-quality.ts.
+ */
+import { aggregateScores } from './journal-quality.js';
+const COMPONENT_WARN_THRESHOLD = 3.0; // out of 5
+function fmt(n) {
+    return (Math.round(n * 100) / 100).toFixed(2);
+}
+function flagFor(component) {
+    switch (component) {
+        case 'averageVerifiability': return 'most trades missing direction or price target';
+        case 'averageEvidence': return 'most trades missing thesis or sources';
+        case 'averageSpecificity': return 'few tags — trades feel generic';
+        case 'averageNovelty': return 'repeating same symbol/direction';
+        case 'averageReview': return 'no post-trade notes';
+    }
+}
+/**
+ * Build the discipline footer markdown for an existing portfolio output.
+ * Returns `null` when there's nothing to show (no scored entries yet).
+ */
+export function renderDisciplineFooter(entries) {
+    const agg = aggregateScores(entries);
+    if (!agg)
+        return null;
+    const lines = [];
+    lines.push('');
+    lines.push('### Journal discipline');
+    lines.push(`Last ${agg.count} scored trade${agg.count === 1 ? '' : 's'}: ` +
+        `**${fmt(agg.averageTotal)} / 5**`);
+    lines.push('');
+    // Each component scaled to 0–5 for display (internal is 0–1).
+    const components = [
+        { key: 'averageVerifiability', label: 'verifiability', value: agg.averageVerifiability * 5 },
+        { key: 'averageEvidence', label: 'evidence', value: agg.averageEvidence * 5 },
+        { key: 'averageSpecificity', label: 'specificity', value: agg.averageSpecificity * 5 },
+        { key: 'averageNovelty', label: 'novelty', value: agg.averageNovelty * 5 },
+        { key: 'averageReview', label: 'review', value: agg.averageReview * 5 },
+    ];
+    for (const c of components) {
+        const flagged = c.value < COMPONENT_WARN_THRESHOLD;
+        const flagText = flagged ? `  ←  ${flagFor(c.key)}` : '';
+        lines.push(`- ${c.label.padEnd(14)} ${fmt(c.value).padStart(5)}${flagText}`);
+    }
+    return lines.join('\n');
+}

package/dist/trading/journal-quality.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Journal quality scorer — non-outcome trade discipline metric.
+ *
+ * Scores each journal entry on how well it was *justified*, not whether
+ * it made money. The five components are weighted to reward the same
+ * habits a discretionary trader's playbook teaches:
+ *
+ *   verifiability (30%)  did the entry name a direction and a price target?
+ *   evidence       (25%)  did it cite sources / thesis / indicators?
+ *   specificity    (20%)  symbol, tags — not vague vibes?
+ *   novelty        (15%)  not the 4th identical revenge-trade this week?
+ *   review         (10%)  did the user write a post-trade note?
+ *
+ * The total is on a 0–5 scale, presented in the portfolio footer so the
+ * agent and the user can see the discipline curve over time.
+ *
+ * Pure function — no I/O, no clock, deterministic given inputs. Used at
+ * append time (TradeLog) and at render time (TradingPortfolio).
+ */
+import type { TradeLogEntry, QualityScore } from './trade-log.js';
+/**
+ * Score one journal entry against the prior history (used for novelty).
+ * `history` should contain entries chronologically before `entry`.
+ */
+export declare function scoreEntry(entry: TradeLogEntry, history?: TradeLogEntry[]): QualityScore;
+export interface AggregateScore {
+    count: number;
+    averageTotal: number;
+    averageVerifiability: number;
+    averageEvidence: number;
+    averageSpecificity: number;
+    averageNovelty: number;
+    averageReview: number;
+}
+/**
+ * Average the qualityScore fields across a set of entries — used by the
+ * portfolio footer to show "your last 10 trades scored 3.2 / 5 on average".
+ *
+ * Entries without a persisted qualityScore are skipped (back-compat with
+ * pre-v3.20 trades). Returns null when there's nothing scored to average.
+ */
+export declare function aggregateScores(entries: TradeLogEntry[]): AggregateScore | null;

package/dist/trading/journal-quality.js

@@ -0,0 +1,109 @@
+/**
+ * Journal quality scorer — non-outcome trade discipline metric.
+ *
+ * Scores each journal entry on how well it was *justified*, not whether
+ * it made money. The five components are weighted to reward the same
+ * habits a discretionary trader's playbook teaches:
+ *
+ *   verifiability (30%)  did the entry name a direction and a price target?
+ *   evidence       (25%)  did it cite sources / thesis / indicators?
+ *   specificity    (20%)  symbol, tags — not vague vibes?
+ *   novelty        (15%)  not the 4th identical revenge-trade this week?
+ *   review         (10%)  did the user write a post-trade note?
+ *
+ * The total is on a 0–5 scale, presented in the portfolio footer so the
+ * agent and the user can see the discipline curve over time.
+ *
+ * Pure function — no I/O, no clock, deterministic given inputs. Used at
+ * append time (TradeLog) and at render time (TradingPortfolio).
+ */
+const NOVELTY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const NOVELTY_PENALTY = 0.2; // per duplicate within window
+const EVIDENCE_KEYWORD_REGEX = /\b(rsi|macd|bollinger|sma|ema|volatility|funding|liquidation|etf|on[-\s]?chain|catalyst|earnings|tvl|because|since|due to|supports?|resistance|breakout|breakdown|divergence|oversold|overbought)\b/i;
+function clamp01(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    if (n >= 1)
+        return 1;
+    return n;
+}
+function hasIndicatorKeyword(text) {
+    if (!text)
+        return 0;
+    return EVIDENCE_KEYWORD_REGEX.test(text) ? 1 : 0;
+}
+/**
+ * Score one journal entry against the prior history (used for novelty).
+ * `history` should contain entries chronologically before `entry`.
+ */
+export function scoreEntry(entry, history = []) {
+    const r = entry.rationale;
+    // ─ verifiability: direction + priceTarget each contribute half ─
+    const verifiability = (r?.direction ? 0.5 : 0) +
+        (typeof r?.priceTarget === 'number' && r.priceTarget > 0 ? 0.5 : 0);
+    // ─ evidence: array length, thesis length, indicator keyword presence ─
+    const evidenceArrLen = Array.isArray(r?.evidence) ? r.evidence.length : 0;
+    const thesisLen = (r?.thesis ?? '').trim().length;
+    const evidence = clamp01(0.4 * Math.min(1, evidenceArrLen / 3) +
+        0.4 * Math.min(1, thesisLen / 200) +
+        0.2 * hasIndicatorKeyword(r?.thesis));
+    // ─ specificity: symbol present + tags present ─
+    const tagCount = Array.isArray(r?.tags) ? r.tags.length : 0;
+    const specificity = (entry.symbol ? 0.5 : 0) +
+        Math.min(1, tagCount / 2) * 0.5;
+    // ─ novelty: penalize same symbol + direction within 7d ─
+    const sinceCutoff = entry.timestamp - NOVELTY_WINDOW_MS;
+    const recentSameCount = history.filter((e) => e.timestamp >= sinceCutoff &&
+        e.timestamp < entry.timestamp &&
+        e.symbol === entry.symbol &&
+        (e.rationale?.direction ?? null) === (r?.direction ?? null)).length;
+    const novelty = clamp01(1 - NOVELTY_PENALTY * recentSameCount);
+    // ─ review: did the user (or the agent in a follow-up turn) annotate? ─
+    const review = entry.review && entry.review.trim().length > 0 ? 1 : 0;
+    const total = 5 * (verifiability * 0.30 +
+        evidence * 0.25 +
+        specificity * 0.20 +
+        novelty * 0.15 +
+        review * 0.10);
+    return {
+        total: Math.round(total * 100) / 100, // 2 decimal places
+        verifiability,
+        evidence,
+        specificity,
+        novelty,
+        review,
+    };
+}
+/**
+ * Average the qualityScore fields across a set of entries — used by the
+ * portfolio footer to show "your last 10 trades scored 3.2 / 5 on average".
+ *
+ * Entries without a persisted qualityScore are skipped (back-compat with
+ * pre-v3.20 trades). Returns null when there's nothing scored to average.
+ */
+export function aggregateScores(entries) {
+    const scored = entries.filter((e) => e.qualityScore != null);
+    if (scored.length === 0)
+        return null;
+    const sum = scored.reduce((acc, e) => {
+        const q = e.qualityScore;
+        return {
+            total: acc.total + q.total,
+            v: acc.v + q.verifiability,
+            e: acc.e + q.evidence,
+            s: acc.s + q.specificity,
+            n: acc.n + q.novelty,
+            r: acc.r + q.review,
+        };
+    }, { total: 0, v: 0, e: 0, s: 0, n: 0, r: 0 });
+    const n = scored.length;
+    return {
+        count: n,
+        averageTotal: sum.total / n,
+        averageVerifiability: sum.v / n,
+        averageEvidence: sum.e / n,
+        averageSpecificity: sum.s / n,
+        averageNovelty: sum.n / n,
+        averageReview: sum.r / n,
+    };
+}

package/dist/trading/trade-log.d.ts

@@ -16,6 +16,37 @@
  * prior crash never bricks the log.
  */
 import type { Side } from './portfolio.js';
+/**
+ * Trade rationale — the "why" behind a fill, captured at trade time so
+ * the journal can score for discipline (not P&L). Inspired by the AI-Trader
+ * signal-quality model: verifiability + evidence + specificity drive better
+ * decisions than rewarding outcomes (which incentivizes curve-fitting).
+ *
+ * All fields are optional; the scorer rewards completeness without forcing it.
+ */
+export interface TradeRationale {
+    direction?: 'long' | 'short' | 'neutral';
+    priceTarget?: number;
+    stopLoss?: number;
+    timeHorizon?: string;
+    conviction?: 1 | 2 | 3 | 4 | 5;
+    evidence?: string[];
+    tags?: string[];
+    thesis?: string;
+}
+/**
+ * Persisted quality breakdown — five components on 0–1 scales plus a 0–5
+ * total. Written next to each entry at append time so portfolio reads
+ * never need to re-score.
+ */
+export interface QualityScore {
+    total: number;
+    verifiability: number;
+    evidence: number;
+    specificity: number;
+    novelty: number;
+    review: number;
+}
 export interface TradeLogEntry {
     timestamp: number;
     symbol: string;
@@ -25,6 +56,12 @@ export interface TradeLogEntry {
     feeUsd: number;
     /** Realized P&L from this specific fill — 0 for opens, ± for closes. */
     realizedPnlUsd: number;
+    /** Journal-v2 fields (optional, back-compat: older entries lack these). */
+    rationale?: TradeRationale;
+    /** User's post-trade note. Boosts the `review` component of the score. */
+    review?: string;
+    /** Computed at append time so portfolio reads don't re-score on every render. */
+    qualityScore?: QualityScore;
 }
 export declare class TradeLog {
     private filePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {