phaedo-mcp 0.3.7 → 0.3.14

package/learned.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// Phaedo — "here's what I learned about you: keep it or remove it."
+//
+// Everything Phaedo inferred from how the subject works (evidence_basis `observed` — not what
+// they said in the interview, not their rules) as one plain sentence each, from the shared
+// phrasebook (vendor/trait-phrases.js). Remove one and it stops shaping answers and decisions on
+// this computer: the forget list is applied every time the profile loads (fingerprint-source.js),
+// so a trait the sessions keep showing stays forgotten. Keep one and it isn't asked about again.
+//
+//   npm run learned                 # what Phaedo learned, numbered; new ones marked
+//   npm run learned -- --remove 3,5
+//   npm run learned -- --keep 1,2   # or --keep all
+//   npm run learned -- --forgotten  # what you removed
+//   npm run learned -- --restore 2  # (number from --forgotten)
+//
+// The list file holds a field name and a digest of the value per item — never the text.
+// PURE functions above the CLI; `now` and the state are passed in.
+
+import { createHash } from 'crypto';
+import { join } from 'path';
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
+import './vendor/trait-phrases.js';               // UMD → globalThis.PhaedoTraitPhrases
+import { isMainModule } from './lib/is-main.js';
+
+const T = globalThis.PhaedoTraitPhrases;
+export const STATE_FILE = 'learned.json';
+export const SHOW_CHARS = 160;
+
+const canon = (field, value) => {
+  try { return T.canonical(field, value); } catch { return value; }
+};
+
+/** A stable key for a (field, value): the field in the clear, the value only as a digest. */
+export function itemKey(field, value) {
+  const v = JSON.stringify(canon(field, value) ?? null);
+  return `${field}#${createHash('sha256').update(v).digest('hex').slice(0, 12)}`;
+}
+
+function sentence(field, value) {
+  let s;
+  try { s = T.phrase(field, value); } catch { s = ''; }
+  return String(s || `${String(field).replace(/_/g, ' ')}: ${JSON.stringify(value)}`).trim();
+}
+
+/** Shorten a long list sentence for the screen: "Terms I use: a, b, c … (+40 more)." */
+export function shorten(text, max = SHOW_CHARS) {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const at = cut.lastIndexOf(', ');
+  const shown = at > max / 2 ? cut.slice(0, at) : cut.trimEnd();
+  const more = (text.slice(shown.length).match(/, /g) || []).length;
+  return `${shown}${more ? ` … (+${more} more)` : ' …'}`;
+}
+
+/**
+ * What Phaedo learned, merged by choice: [{ key, keys, field, layer, text, times, contradicts }].
+ * Values that are the same choice (0.8 and 0.85 on a scale) are one item; `keys` holds every
+ * value's key, so removing the item forgets all of them. `times` sums the observations.
+ * `contradicts` lists the other items for the same field that are a different choice — never
+ * for list traits (bullets and headings can both be true). Ordered by layer, then most-seen. PURE.
+ */
+export function learnedItems(vd) {
+  const layers = vd?.phaedo_fingerprint?.layers || {};
+  const items = [];
+  for (const [layer, l] of Object.entries(layers)) {
+    for (const s of Array.isArray(l?.signals) ? l.signals : []) {
+      if (!s || s.evidence_basis !== 'observed' || !s.field) continue;
+      const k = itemKey(s.field, s.value);
+      const times = Number(s.observation_count) || 1;
+      const same = items.find((it) => it.field === s.field && (it.keys.includes(k) || (!Array.isArray(s.value) && sameChoice(s.field, it.value, s.value))));
+      if (same) {
+        if (!same.keys.includes(k)) same.keys.push(k);
+        if (times > same.best) { same.best = times; same.value = s.value; same.text = sentence(s.field, s.value); }
+        same.times += times;
+        continue;
+      }
+      items.push({ key: k, keys: [k], field: s.field, layer, value: s.value, text: sentence(s.field, s.value), times, best: times });
+    }
+  }
+  for (const it of items) {
+    it.contradicts = Array.isArray(it.value) ? [] : items.filter((o) => o !== it && o.field === it.field && !Array.isArray(o.value)).map((o) => o.key);
+  }
+  const order = Object.keys(layers);
+  items.sort((a, b) => order.indexOf(a.layer) - order.indexOf(b.layer) || b.times - a.times || a.text.localeCompare(b.text));
+  return items.map(({ value, best, ...rest }) => rest);
+}
+
+function sameChoice(field, a, b) {
+  try { return T.sameChoice(field, a, b); } catch { return JSON.stringify(a) === JSON.stringify(b); }
+}
+
+/** The state: { forgotten: { key: at }, kept: { key: at } }. Never throws. */
+export function readLearnedState(stateDir) {
+  try {
+    const j = JSON.parse(readFileSync(join(stateDir, STATE_FILE), 'utf8'));
+    return { forgotten: obj(j.forgotten), kept: obj(j.kept) };
+  } catch { return { forgotten: {}, kept: {} }; }
+}
+const obj = (x) => (x && typeof x === 'object' && !Array.isArray(x) ? x : {});
+
+export function writeLearnedState(stateDir, state) {
+  mkdirSync(stateDir, { recursive: true });
+  const path = join(stateDir, STATE_FILE);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ forgotten: state.forgotten, kept: state.kept }, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/**
+ * The profile with every forgotten trait taken out of its layers, in place (the loaders'
+ * provenance marker lives on the object, so it is kept). Signals the subject said themselves
+ * are never touched by a forget — only `observed` ones are listed, so only those can match.
+ */
+export function applyForgotten(vd, state) {
+  const forgotten = state?.forgotten || {};
+  const layers = vd?.phaedo_fingerprint?.layers;
+  if (!layers || !Object.keys(forgotten).length) return vd;
+  const next = {};
+  for (const [id, l] of Object.entries(layers)) {
+    if (!l || !Array.isArray(l.signals)) { next[id] = l; continue; }
+    const signals = l.signals.filter((s) => !(s && s.evidence_basis === 'observed' && forgotten[itemKey(s.field, s.value)]));
+    next[id] = signals.length === l.signals.length ? l : { ...l, signals };
+  }
+  vd.phaedo_fingerprint = { ...vd.phaedo_fingerprint, layers: next };
+  return vd;
+}
+
+/** Items not yet kept or removed. */
+const any = (map, it) => it.keys.some((k) => map[k]);
+export const isForgotten = (it, state) => any(state.forgotten, it);
+export const isKept = (it, state) => any(state.kept, it);
+export const unreviewed = (items, state) => items.filter((i) => !isKept(i, state) && !isForgotten(i, state));
+
+/** The screen. PURE. */
+export function formatList(items, state) {
+  if (!items.length) return 'Phaedo hasn\'t learned anything from how you work yet.';
+  const num = new Map(items.map((it, i) => [it.key, i + 1]));
+  const reviewedBefore = Object.keys(state.kept).length + Object.keys(state.forgotten).length > 0;
+  const lines = [`Here's what Phaedo learned from how you work (${items.length}). Remove anything that isn't right.`, ''];
+  for (const [i, it] of items.entries()) {
+    const fresh = reviewedBefore && !isKept(it, state) ? ' (new)' : '';
+    const clash = it.contradicts.filter((k) => num.has(k)).map((k) => `#${num.get(k)}`);
+    lines.push(`${String(i + 1).padStart(3)}. ${shorten(it.text)}${fresh}`);
+    if (clash.length) lines.push(`      ⚠ disagrees with ${clash.join(', ')}; keep the one that's right`);
+  }
+  lines.push('', 'Remove: npm run learned -- --remove 3,5    Keep: --keep 1,2 (or --keep all)');
+  return lines.join('\n');
+}
+
+/** "3,5" / "all" → indexes into `items`; unknown numbers reported. PURE. */
+export function pick(arg, items) {
+  if (String(arg).trim().toLowerCase() === 'all') return { picked: items.slice(), bad: [] };
+  const picked = [], bad = [];
+  for (const p of String(arg || '').split(/[\s,]+/).filter(Boolean)) {
+    const n = Number(p);
+    if (Number.isInteger(n) && n >= 1 && n <= items.length) picked.push(items[n - 1]); else bad.push(p);
+  }
+  return { picked, bad };
+}
+
+/** Record a decision. PURE: returns the new state. */
+export function decide(state, items, action, now = new Date().toISOString()) {
+  const s = { forgotten: { ...state.forgotten }, kept: { ...state.kept } };
+  for (const it of items) for (const k of it.keys || [it.key]) {
+    if (action === 'remove') { s.forgotten[k] = now; delete s.kept[k]; }
+    if (action === 'keep') { s.kept[k] = now; delete s.forgotten[k]; }
+    if (action === 'restore') { delete s.forgotten[k]; s.kept[k] = now; }
+  }
+  return s;
+}
+
+/** One line for /phaedo:status, or null when nothing is waiting. */
+export function reviewLine(items, state) {
+  const n = unreviewed(items, state).length;
+  if (!n) return null;
+  return `Phaedo learned ${n} thing${n === 1 ? '' : 's'} about how you work that you haven't looked at yet — /phaedo:learned (or npm run learned) to keep or remove ${n === 1 ? 'it' : 'them'}.`;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+async function main(argv) {
+  const opt = (f) => { const i = argv.indexOf(f); return i >= 0 ? (argv[i + 1] ?? '') : null; };
+  const { dirname } = await import('path');
+  const { fileURLToPath } = await import('url');
+  const { loadFingerprintPreferCache } = await import('./fingerprint-source.js');
+  const { defaultStateDir } = await import('./cache.js');
+  const MCP_DIR = dirname(fileURLToPath(import.meta.url));
+  const stateDir = defaultStateDir();
+  let vd;
+  try { vd = await loadFingerprintPreferCache(MCP_DIR, { unfiltered: true }); } catch {
+    process.stdout.write('Phaedo has no profile on this computer yet, so there is nothing to review.\n');
+    return 0;
+  }
+  const all = learnedItems(vd);
+  let state = readLearnedState(stateDir);
+  const showing = all.filter((i) => !isForgotten(i, state));
+  const gone = all.filter((i) => isForgotten(i, state));
+  const say = (s) => process.stdout.write(s + '\n');
+  const report = (bad) => { if (bad.length) say(`Not on the list: ${bad.join(', ')}.`); };
+
+  for (const [flag, action, from] of [['--remove', 'remove', showing], ['--keep', 'keep', showing], ['--restore', 'restore', gone]]) {
+    const arg = opt(flag);
+    if (arg === null) continue;
+    const { picked, bad } = pick(arg, from);
+    report(bad);
+    if (!picked.length) return bad.length ? 1 : 0;
+    state = decide(state, picked, action);
+    writeLearnedState(stateDir, state);
+    const verb = { remove: 'Removed', keep: 'Kept', restore: 'Brought back' }[action];
+    for (const it of picked) say(`${verb}: ${shorten(it.text, 100)}`);
+    if (action === 'remove') say('Phaedo stops using these on this computer from the next session. To remove them from your phone\'s profile too, use the Phaedo app.');
+    return 0;
+  }
+  if (argv.includes('--forgotten')) {
+    if (!gone.length) { say('You haven\'t removed anything.'); return 0; }
+    say('What you removed:');
+    gone.forEach((it, i) => say(`${String(i + 1).padStart(3)}. ${shorten(it.text)}`));
+    say('\nBring one back: npm run learned -- --restore 2');
+    return 0;
+  }
+  say(formatList(showing, state));
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2)).then((c) => process.exit(c), (e) => { process.stderr.write(`✗ ${e.message}\n`); process.exit(1); });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.7",
+  "version": "0.3.14",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
@@ -50,6 +50,12 @@
     "receipts.js",
     "receipts-sync.js",
     "agreement.js",
+    "weekly.js",
+    "precedent.js",
+    "rules-files.js",
+    "learned.js",
+    "history-import.js",
+    "agent-hooks.js",
     "calibration.js",
     "health.js",
     "phone-source.js",
@@ -88,14 +94,16 @@
     "setup": "node install.mjs",
     "setup:pair": "node install.mjs --pair",
     "setup:code-hook": "node install.mjs --code-hook",
+    "setup:agent-hooks": "node install.mjs --agent-hooks",
     "setup:capture-model": "node install.mjs --capture-model",
     "unsetup": "node install.mjs --uninstall",
     "pair": "node pair.js",
     "pull": "node pull.js",
-    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs && node test-plugin.mjs",
+    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-weekly.mjs && node test-precedent.mjs && node test-rules-files.mjs && node test-agent-hook.mjs && node test-learned.mjs && node test-history-import.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs && node test-plugin.mjs",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
     "ship-readout": "node ship-readout.js",
+    "precedent": "node precedent.js",
     "calibration": "node calibration.js",
     "health": "node health.js",
     "validate": "node ../spec/validate-fingerprint.mjs sample-fingerprint.json",
@@ -113,7 +121,11 @@
     "smoke:calibration": "node test-calibration.mjs",
     "smoke:binding": "node test-action-binding.mjs",
     "smoke:autonomy": "node test-autonomy-promotion.mjs",
-    "smoke:ap2": "node test-ap2.mjs"
+    "smoke:ap2": "node test-ap2.mjs",
+    "week": "node weekly.js",
+    "rules": "node rules-files.js",
+    "learned": "node learned.js",
+    "import": "node history-import.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/precedent.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Phaedo — situational precedent, Phase 2 (proposal 0009, design doc §9 / G8 B4).
+//
+// A §10 consultation answers dispositionally ("this subject favors caution"). An agent can act
+// on a precedent: "you have faced this shape 6 times; approved 5, edited 1." This module is the
+// derived view that would say so — over the §10.6 receipt store, never a stored artifact.
+//
+// PURE: (receipts, opts) -> report. No I/O, `now` injected — the agreement.js discipline.
+// NOT WIRED into consult: 0009 is a draft, and its rail 4 says precedent informs and never
+// authorizes. Dev-only readout: `npm run precedent`.
+//
+// The SHAPE is the situation key — banded features only, a closed vocabulary per field, so
+// nothing a receipt holds on-device (summary, exact amount, counterparty, ids, previews) can
+// leave through it (0009 rail 1):
+//
+//   domain       canonical §10.2 term when there is one, else the normalized free-text domain
+//   kind         merge | deploy | push to main | publish | message | payment | … | other
+//   reversible   true | false | null
+//   magnitude    low | medium | high | null            (as the agent described it)
+//   amount_band  none | low | medium | high            (against the subject's own edges, G8 B1)
+//   size         normal | large | null                 (the diff, when GitHub was read)
+//   touched      ordinary | sensitive | null           (the paths, when GitHub was read)
+//   binding      shell | connected_app | agent_tool | none   (what would carry the action out)
+//
+// Rails enforced here (0009 "Rails proposed for normative status"):
+//   1. banded features only — shapeOf() reads nothing else into the key;
+//   2. minimum support — below MIN_SUPPORT observations the answer is null, never a guess;
+//   3. subject-authored outcomes only — a burst of marks (BATCH_MIN within BATCH_WINDOW_MS)
+//      is bookkeeping, not consent, and is excluded (the §10.7 batch gate, per receipt);
+//   5. pre-flight receipts (via phaedo_check_authorization) are counted apart, never mixed in.
+// Rails 4 and 6 are about use, not computation: nothing here produces a signal.
+
+import { actionKind } from './ship-readout.js';
+import { canonicalDomain, normalizeDomain } from './lib/domain.js';
+import { DECISIVE } from './agreement.js';
+import { BATCH_WINDOW_MS } from './autonomy-promotion.js';
+import { isMainModule } from './lib/is-main.js';
+
+export const SHAPE_REVISION = '2026-10-27.v0';
+export const SHAPE_FIELDS = Object.freeze(['domain', 'kind', 'reversible', 'magnitude', 'amount_band', 'size', 'touched', 'binding']);
+export const DEFAULT_WINDOW_DAYS = 180;
+export const MIN_SUPPORT = 5;
+export const BATCH_MIN = 3;                 // this many marks inside BATCH_WINDOW_MS = a burst
+export const PREFLIGHT_VIA = 'phaedo_check_authorization';
+
+const DAY = 24 * 60 * 60 * 1000;
+const OUTCOMES = new Set(['approved', 'rejected', 'modified']);
+const MAGNITUDES = new Set(['low', 'medium', 'high']);
+
+const driver = (r, cue) => (Array.isArray(r?.drivers) ? r.drivers.find((d) => d && d.cue === cue) : null)?.value ?? null;
+
+function domainOf(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return '(none)';
+  return canonicalDomain(raw) || normalizeDomain(raw) || '(none)';
+}
+
+function amountBandOf(r) {
+  const a = r?.request?.action_descriptor?.amount;
+  if (typeof a !== 'number' || !Number.isFinite(a) || a <= 0) return 'none';
+  // consult-core only writes amountBand when the amount raised the stakes; a positive
+  // amount without one sat below the subject's low edge.
+  const b = driver(r, 'amountBand');
+  return b === 'medium' || b === 'high' ? b : 'low';
+}
+
+function bindingOf(r) {
+  const t = r?.request?.action_binding?.tool_name;
+  if (typeof t !== 'string' || !t) return 'none';
+  if (t === 'Bash') return 'shell';
+  if (t.startsWith('mcp__')) return 'connected_app';
+  return 'agent_tool';
+}
+
+/** The situation a receipt was about, as banded features. Never throws. */
+export function shapeOf(r) {
+  const ad = r?.request?.action_descriptor || {};
+  const stakes = driver(r, 'diffStakes');        // normal | large | sensitive | large+sensitive | unknown
+  const read = typeof stakes === 'string' && stakes !== 'unknown';
+  return {
+    domain: domainOf(ad.domain),
+    kind: actionKind(ad.summary),
+    reversible: typeof ad.reversible === 'boolean' ? ad.reversible : null,
+    magnitude: MAGNITUDES.has(ad.magnitude) ? ad.magnitude : null,
+    amount_band: amountBandOf(r),
+    size: read ? (stakes.includes('large') ? 'large' : 'normal') : null,
+    touched: read ? (stakes.includes('sensitive') ? 'sensitive' : 'ordinary') : null,
+    binding: bindingOf(r),
+  };
+}
+
+/** A stable string for a shape over `fields` (a coarser key = fewer fields). */
+export function shapeKey(shape, fields = SHAPE_FIELDS) {
+  return fields.map((f) => `${f}=${shape?.[f] ?? 'null'}`).join('|');
+}
+
+/** Only the requested fields of a shape — what may cross the boundary. */
+export function projectShape(shape, fields = SHAPE_FIELDS) {
+  return Object.fromEntries(fields.map((f) => [f, shape?.[f] ?? null]));
+}
+
+/**
+ * Receipt ids whose outcome was marked in a burst: BATCH_MIN or more marks inside one
+ * windowMs span. Receipts without a mark time are never batch (absence of evidence).
+ */
+export function batchMarkedIds(receipts, { windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN } = {}) {
+  const marked = (Array.isArray(receipts) ? receipts : [])
+    .map((r) => ({ id: r?.receipt_id, t: Date.parse(r?.user_action_at) }))
+    .filter((x) => x.id && Number.isFinite(x.t))
+    .sort((a, b) => a.t - b.t);
+  const out = new Set();
+  let i = 0;
+  for (let j = 0; j < marked.length; j++) {
+    while (marked[j].t - marked[i].t > windowMs) i++;
+    if (j - i + 1 >= batchMin) for (let k = i; k <= j; k++) out.add(marked[k].id);
+  }
+  return out;
+}
+
+function agrees(signal, action) {
+  if (action === 'approved') return signal === 'proceed' || signal === 'proceed_with_note';
+  if (action === 'rejected') return signal === 'decline';
+  return false;   // modified: not accepted as-judged (agreement.js v0, conservative)
+}
+
+// The receipts that may count as evidence at all: in the window, subject-marked, not in a burst.
+function evidence(receipts, { now, windowDays, windowMs, batchMin }) {
+  const since = now - windowDays * DAY;
+  const list = Array.isArray(receipts) ? receipts : [];
+  const batch = batchMarkedIds(list, { windowMs, batchMin });
+  const out = { usable: [], excluded_batch: 0 };
+  for (const r of list) {
+    const t = Date.parse(r?.created_at);
+    if (!Number.isFinite(t) || t < since || t > now) continue;
+    if (!OUTCOMES.has(r?.user_action)) continue;
+    if (batch.has(r.receipt_id)) { out.excluded_batch++; continue; }
+    out.usable.push({ r, t });
+  }
+  return out;
+}
+
+function tally(items, now) {
+  const user_actions = { approved: 0, rejected: 0, modified: 0 };
+  let scored = 0, agreed = 0, lastDivergence = null;
+  for (const { r, t } of items) {
+    user_actions[r.user_action]++;
+    const signal = r?.response?.signal;
+    if (!DECISIVE.includes(signal)) continue;
+    scored++;
+    if (agrees(signal, r.user_action)) agreed++;
+    else if (lastDivergence === null || t > lastDivergence) lastDivergence = t;
+  }
+  return {
+    observed: items.length,
+    user_actions,
+    oracle_agreement: scored ? Math.round((agreed / scored) * 100) / 100 : null,
+    most_recent_divergence_days_ago: lastDivergence === null ? null : Math.floor((now - lastDivergence) / DAY),
+  };
+}
+
+/**
+ * The precedent for one situation, or null below minimum support (rail 2 — never a guess).
+ * `shape` may be a receipt's shapeOf() or any object with the SHAPE_FIELDS; `fields` picks
+ * how coarse the match is. The result carries banded features and counts only (rail 1).
+ */
+export function precedentFor(receipts, shape, {
+  now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS, minSupport = MIN_SUPPORT,
+  fields = SHAPE_FIELDS, windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN,
+} = {}) {
+  const want = shapeKey(shape, fields);
+  const { usable } = evidence(receipts, { now, windowDays, windowMs, batchMin });
+  const match = usable.filter(({ r }) => shapeKey(shapeOf(r), fields) === want);
+  const main = match.filter(({ r }) => r.via !== PREFLIGHT_VIA);
+  if (main.length < minSupport) return null;
+  const pre = match.filter(({ r }) => r.via === PREFLIGHT_VIA);
+  const { observed, user_actions, oracle_agreement, most_recent_divergence_days_ago } = tally(main, now);
+  return {
+    shape: projectShape(shape, fields),
+    shape_revision: SHAPE_REVISION,
+    observed,
+    user_actions,
+    oracle_agreement,
+    window_days: windowDays,
+    most_recent_divergence_days_ago,
+    preflight: { observed: pre.length, user_actions: tally(pre, now).user_actions },
+  };
+}
+
+/**
+ * The divergence episodes — the only thing 0009's principle says is worth keeping: receipts
+ * where a decisive prediction did not match what the subject did. Banded, newest first.
+ */
+export function divergenceEpisodes(receipts, {
+  now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS, fields = SHAPE_FIELDS,
+  windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN,
+} = {}) {
+  const { usable } = evidence(receipts, { now, windowDays, windowMs, batchMin });
+  return usable
+    .filter(({ r }) => DECISIVE.includes(r?.response?.signal) && !agrees(r.response.signal, r.user_action))
+    .sort((a, b) => b.t - a.t)
+    .map(({ r, t }) => ({
+      shape: projectShape(shapeOf(r), fields),
+      predicted: r.response.signal,
+      user_action: r.user_action,
+      days_ago: Math.floor((now - t) / DAY),
+      preflight: r.via === PREFLIGHT_VIA,
+    }));
+}
+
+/**
+ * Every shape seen in the window with its support — the readout's table, and the data for
+ * choosing N, the window and the coarseness of the key (0009 "Open").
+ */
+export function precedentTable(receipts, {
+  now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS, minSupport = MIN_SUPPORT,
+  fields = SHAPE_FIELDS, windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN,
+} = {}) {
+  const { usable, excluded_batch } = evidence(receipts, { now, windowDays, windowMs, batchMin });
+  const groups = new Map();
+  for (const item of usable) {
+    if (item.r.via === PREFLIGHT_VIA) continue;
+    const s = shapeOf(item.r);
+    const k = shapeKey(s, fields);
+    if (!groups.has(k)) groups.set(k, { shape: projectShape(s, fields), items: [] });
+    groups.get(k).items.push(item);
+  }
+  const shapes = [...groups.values()]
+    .map(({ shape, items }) => ({ shape, ...tally(items, now), supported: items.length >= minSupport }))
+    .sort((a, b) => b.observed - a.observed);
+  return {
+    window_days: windowDays,
+    min_support: minSupport,
+    fields: [...fields],
+    usable: usable.length,
+    excluded_batch,
+    shapes,
+  };
+}
+
+const show = (shape) => Object.entries(shape).filter(([, v]) => v !== null && v !== 'none' && v !== '(none)').map(([k, v]) => `${k}=${v}`).join(' ');
+
+export function formatTable(t) {
+  const lines = [
+    `Precedent — last ${t.window_days} days, ${t.usable} marked decision(s) usable` +
+      (t.excluded_batch ? `, ${t.excluded_batch} left out as marked in a burst` : '') + '.',
+    `Key: ${t.fields.join(' × ')}. A shape needs ${t.min_support} to answer.`,
+  ];
+  if (!t.shapes.length) lines.push('  No marked decisions yet — nothing to show.');
+  for (const s of t.shapes) {
+    const a = s.user_actions;
+    const agree = s.oracle_agreement === null ? 'no decisive calls' : `matched ${Math.round(s.oracle_agreement * 100)}%`;
+    const div = s.most_recent_divergence_days_ago === null ? '' : `, last miss ${s.most_recent_divergence_days_ago}d ago`;
+    lines.push(`  ${s.supported ? '✓' : '·'} ${s.observed}× ${show(s.shape)} — yes ${a.approved}, no ${a.rejected}, edited ${a.modified}; ${agree}${div}`);
+  }
+  return lines.join('\n');
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const num = (flag, d) => { const i = args.indexOf(flag); const n = i >= 0 ? Number(args[i + 1]) : NaN; return Number.isFinite(n) && n > 0 ? n : d; };
+  const fi = args.indexOf('--fields');
+  const fields = fi >= 0 ? String(args[fi + 1] || '').split(',').filter((f) => SHAPE_FIELDS.includes(f)) : SHAPE_FIELDS;
+  const { readReceipts } = await import('./receipts.js');
+  const { defaultStateDir } = await import('./cache.js');
+  const receipts = await readReceipts(defaultStateDir()).catch(() => []);
+  const t = precedentTable(receipts, { windowDays: num('--days', DEFAULT_WINDOW_DAYS), minSupport: num('--min', MIN_SUPPORT), fields: fields.length ? fields : SHAPE_FIELDS });
+  process.stdout.write(formatTable(t) + '\n');
+}

package/pull.js

@@ -8,9 +8,18 @@
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { loadFingerprint, sourceOf, summarizeStarter } from './fingerprint-source.js';
+import { readReceipts } from './receipts.js';
+import { defaultStateDir } from './cache.js';
+import { weeklyHandled, formatWeekly } from './weekly.js';
+import { learnedItems, readLearnedState, reviewLine } from './learned.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 
+// Every outcome ends with what Phaedo did for the subject this week — the reason to have it.
+const week = async () => `  ${formatWeekly(weeklyHandled(await readReceipts(defaultStateDir()).catch(() => [])))}\n`;
+// …and, when there is any, what Phaedo learned that the subject hasn't looked at yet.
+const review = (vd) => { const line = reviewLine(learnedItems(vd), readLearnedState(defaultStateDir())); return line ? `  ${line}\n` : ''; };
+
 loadFingerprint(BASE_DIR)
   .then(async (vd) => {
     const fp = (vd && vd.phaedo_fingerprint) || {};
@@ -28,12 +37,14 @@ loadFingerprint(BASE_DIR)
         `  ${learned} thing(s) learned across ${areas} area(s)${sessions ? ` from ${sessions} session(s)` : ''} — ${stage}\n` +
         `  Pair the Phaedo phone app (npm run pair) to replace it with your full profile.\n`
       );
+      process.stdout.write(await week() + review(vd));
       process.exit(0);
     }
     if (src.live) {
       process.stdout.write(
         `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`
       );
+      process.stdout.write(await week() + review(vd));
       process.exit(0);
     }
     const hours = src.ageMs != null ? Math.round(src.ageMs / 3600000) : null;
@@ -43,9 +54,11 @@ loadFingerprint(BASE_DIR)
       `  Anything you changed since then — including a revoked authorization — is NOT reflected.\n` +
       `  Open Phaedo on your phone and approve the card, then run this again.\n`
     );
+    process.stdout.write(await week() + review(vd));
     process.exit(2);                       // distinct from 1 (hard failure) — stale, not broken
   })
-  .catch((err) => {
+  .catch(async (err) => {
     process.stderr.write(`✗ Couldn't read your profile: ${err.message}\n`);
+    process.stdout.write(await week());
     process.exit(1);
   });

package/receipts-sync.js

@@ -29,6 +29,7 @@
 import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
 import { readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
 import { agreementDigest } from './agreement.js';
+import { weeklyHandled, formatWeekly } from './weekly.js';
 
 const { Kdf, Envelope } = Phaedo;
 const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
@@ -95,7 +96,11 @@ export async function buildReceiptsDeposit(pairKeyB64u, receipts, { cap = DIGEST
     pairKey.fill(0);
   }
   try {
-    const inner = { kind: 'receipts_digest', data: { receipts: head, agreement, generated_at: generatedAt } };
+    // The visible win: what Phaedo handled without interrupting the subject this week. Counts
+    // plus the sentence the MCP already shows in /phaedo:status, so both surfaces say the same.
+    const w = weeklyHandled(list, { now: Number.isFinite(agreementAt) ? agreementAt : Date.now() });
+    const week = { ...w, summary: formatWeekly(w) };
+    const inner = { kind: 'receipts_digest', data: { receipts: head, agreement, week, generated_at: generatedAt } };
     const plaintext = new TextEncoder().encode(JSON.stringify(inner));
     const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'receipts_digest', created_at: now() });
     plaintext.fill(0);