phewsh 0.15.28 → 0.15.30

package/bin/phewsh.js

@@ -66,6 +66,8 @@ const COMMANDS = {
   mcp:     () => require('../commands/mcp')(),
   receipts: () => require('../commands/receipts')(),
   outcomes: () => require('../commands/outcomes')(),
+  truth:   () => require('../commands/truth'),
+  brief:   () => require('../commands/brief'),
   bypass:  () => require('../commands/bypass')(),
   setup:   () => require('../commands/setup')(),
   update:  () => require('../commands/update')(),
@@ -99,6 +101,8 @@ function showHelp() {
   console.log(`    ${cyan('intent')}     ${g('Create, view, evolve .intent/ artifacts')}`);
   console.log(`    ${cyan('gate')}       ${g('Set constraints (budget, time, skill, urgency)')}`);
   console.log(`    ${cyan('context')}    ${g('Export .intent/ for any AI tool')}`);
+  console.log(`    ${cyan('truth')}      ${g('Read-only audit: versions, Git, intent, projections, conflicts')}`);
+  console.log(`    ${cyan('brief')}      ${g('Provider-ready briefing built from verified project truth')}`);
   console.log(`    ${cyan('ai')}         ${g('One-shot prompt with .intent/ context')}
     ${cyan('browse')}     ${g('Read any URL — AI summary in your terminal')}`);
   console.log('');

package/commands/brief.js

@@ -0,0 +1,13 @@
+const { generateBrief } = require('../lib/brief');
+
+async function main() {
+  const { content } = await generateBrief();
+  console.log(`\n${content}\n`);
+}
+
+module.exports = { main };
+
+main().catch(err => {
+  console.error(`\nBrief unavailable: ${err.message}\n`);
+  process.exitCode = 1;
+});

package/commands/outcomes.js

@@ -10,6 +10,8 @@ const {
   OUTCOMES, recordDecision, labelOutcome,
   pendingDecisions, recentDecisions, outcomeStats, bypassStats,
 } = require('../lib/outcomes');
+const learning = require('../lib/learning');
+const continuity = require('../lib/continuity');
 
 const { b, teal, peach, sage, slate, cream, ember, green } = ui;
 
@@ -42,76 +44,108 @@ function showBypasses() {
   }
 }
 
+// Plain-language explanation of the contract — shown every time, because the
+// #1 complaint was "I have no idea what this is for or how to use it."
+function explainDeal() {
+  console.log(`  ${b(cream('Outcomes'))} ${slate('— phewsh\'s memory of what actually worked')}`);
+  ui.divider('line');
+  console.log(`  ${sage('Every call you route, phewsh logs. Tell it what you')} ${green('kept')} ${sage('vs')} ${ember('threw out')}${sage(',')}`);
+  console.log(`  ${sage('and it learns which tool to trust for which job — and warns you before')}`);
+  console.log(`  ${sage('you repeat something that flopped.')} ${slate('That labeled record is the one thing')}`);
+  console.log(`  ${slate('your chat history doesn\'t have. Two taps now = smarter routing later.')}`);
+}
+
+// The payoff, in their own data — so labeling feels like it buys something.
+function showPayoff(stats) {
+  const lines = [];
+  try {
+    const best = learning.bestRoute(stats, { minSample: 2 });
+    if (best && best.keptRate >= 0.5) {
+      const label = continuity.labelFor(best.route) || best.route;
+      lines.push(`${green('●')} ${sage(label + ' keeps best for you — ')}${cream(Math.round(best.keptRate * 100) + '%')} ${sage(`(${best.kept}/${best.total}). phewsh leans there when it routes.`)}`);
+    }
+  } catch { /* best-effort */ }
+  const regrets = stats.reverted + stats.failed;
+  if (regrets > 0) {
+    lines.push(`${ember('●')} ${sage((regrets === 1 ? '1 call you marked a miss is' : regrets + ' calls you marked misses are') + ' remembered — ')}${cream('/recall')} ${sage('warns you before a repeat.')}`);
+  }
+  if (lines.length === 0) return;
+  console.log('');
+  console.log(`  ${b(cream('What it already knows'))} ${slate('← this is the payoff')}`);
+  for (const l of lines) console.log(`    ${l}`);
+  if (stats.judged < 4) console.log(`    ${slate('judge a few more and clearer patterns surface here.')}`);
+}
+
 function showStats() {
   const stats = outcomeStats();
-  const labeled = stats.total - stats.pending;
 
   console.log('');
-  console.log(`  ${b(cream('Outcomes'))} ${slate('— what your decisions became')}`);
-  ui.divider('line');
+  explainDeal();
 
   if (stats.total === 0) {
-    console.log(`  ${sage('Nothing recorded yet.')}`);
-    console.log(`  ${slate('Work through a phewsh session — every routed action records a decision.')}`);
-    console.log(`  ${slate('Label them 1-4 as you learn what held up.')}`);
+    console.log('');
+    console.log(`  ${sage('Nothing logged yet — start routing work and it fills in.')}`);
+    console.log(`  ${slate('In a session: just type, or use /use <tool>. Then tap 1-4 to judge it.')}`);
     showBypasses();
     console.log('');
     return;
   }
 
-  console.log(`  ${cream(String(stats.total))} ${sage('decisions')} ${slate('·')} ${cream(String(labeled))} ${sage('labeled')} ${slate('·')} ${cream(String(stats.pending))} ${sage('pending')}`);
-  if (labeled > 0) {
-    console.log(`  ${green(stats.kept + ' kept')} ${slate('·')} ${ember(stats.reverted + ' reverted')} ${slate('·')} ${peach(stats.superseded + ' superseded')} ${slate('·')} ${ember(stats.failed + ' failed')}`);
+  // The state of the record, in plain numbers that don't lie.
+  console.log('');
+  console.log(`  ${b(cream('Your record'))}`);
+  console.log(`    ${cream(String(stats.total))} ${sage('routed')} ${slate('·')} ${cream(String(stats.judged))} ${sage('you\'ve judged')} ${slate('·')} ${cream(String(stats.pending))} ${sage('not yet judged')}`);
+  if (stats.judged > 0) {
+    const bits = [green(`✓ ${stats.kept} kept`)];
+    if (stats.reverted) bits.push(ember(`↩ ${stats.reverted} reverted`));
+    if (stats.superseded) bits.push(peach(`⟳ ${stats.superseded} redone`));
+    if (stats.failed) bits.push(ember(`✗ ${stats.failed} flopped`));
+    console.log(`    ${bits.join(slate(' · '))}`);
   }
-
-  const routes = Object.entries(stats.byRoute);
-  if (routes.length > 0) {
-    console.log('');
-    console.log(`  ${b(cream('By route'))}`);
-    for (const [route, r] of routes.sort((a, b) => b[1].total - a[1].total)) {
-      const rate = r.total > 0 ? Math.round((r.kept / r.total) * 100) : 0;
-      console.log(`    ${cream(route.padEnd(14))} ${sage(`${r.total} labeled`)} ${slate('·')} ${green(`${rate}% kept`)}`);
-    }
+  if (stats.autoFailed > 0) {
+    console.log(`    ${slate(`(${stats.autoFailed} didn't complete — route errors phewsh logged for you, not your call)`)}`);
   }
 
-  const modes = Object.entries(stats.byMode);
-  if (modes.length > 0) {
-    console.log('');
-    console.log(`  ${b(cream('By mode'))}`);
-    for (const [mode, m] of modes.sort((a, b) => b[1].total - a[1].total)) {
-      const rate = m.total > 0 ? Math.round((m.kept / m.total) * 100) : 0;
-      console.log(`    ${cream(mode.padEnd(14))} ${sage(`${m.total} labeled`)} ${slate('·')} ${green(`${rate}% kept`)}`);
-    }
-  }
+  showPayoff(stats);
 
-  const recent = recentDecisions(8);
-  if (recent.length > 0) {
+  // The ask — focused on recent, real calls, with a dead-simple next step.
+  const pending = pendingDecisions({ substantive: true }).slice(-6).reverse();
+  if (pending.length > 0) {
     console.log('');
-    console.log(`  ${b(cream('Recent'))}`);
-    for (const d of recent) {
-      console.log(`    ${slate(d.id.padEnd(10))} ${outcomeBadge(d)} ${slate(fmtAgo(d.ts).padStart(3))} ${sage(d.summary.slice(0, 56))}`);
-    }
+    console.log(`  ${b(cream('Give a verdict'))} ${slate('— your recent calls (skip the trivial ones)')}`);
+    pending.forEach((d, i) => {
+      let s = (d.summary || '').replace(/\s+/g, ' ');
+      if (s.length > 44) s = s.slice(0, 43).trimEnd() + '…';
+      const via = (continuity.labelFor(d.route) || d.route).padEnd(12);
+      console.log(`    ${teal(String(i + 1))} ${cream(s.padEnd(45))} ${slate(via)} ${slate(fmtAgo(d.ts))}`);
+    });
+    console.log('');
+    console.log(`  ${teal('→')} ${sage('Walk through them:')} ${cream('phewsh outcomes label')} ${slate('· 20 seconds, Enter skips')}`);
+    console.log(`    ${slate('or in a session, just tap')} ${cream('1-4')} ${slate('right after any answer.')}`);
   }
 
   showBypasses();
-
-  if (stats.pending > 0) {
-    console.log('');
-    console.log(`  ${sage('Label pending decisions:')} ${cream('phewsh outcomes label')}`);
-  }
   console.log('');
 }
 
 function labelInteractive() {
-  const pending = pendingDecisions();
+  // Newest first, and capped — you judge best while the work is fresh, and a
+  // 76-item slog through last week's test prompts is exactly the chore that
+  // made this feel pointless. The recent calls carry the signal.
+  const CAP = 12;
+  const all = pendingDecisions({ substantive: true }).reverse(); // newest first
+  const pending = all.slice(0, CAP);
   if (pending.length === 0) {
-    console.log(`\n  ${teal('●')} ${sage('No pending decisions — everything is labeled.')}\n`);
+    console.log(`\n  ${teal('●')} ${sage('Nothing substantive to judge — your real calls are all labeled.')}\n`);
     return;
   }
 
   console.log('');
-  console.log(`  ${b(cream(`${pending.length} pending decision${pending.length !== 1 ? 's' : ''}`))}`);
-  console.log(`  ${slate('1 kept · 2 reverted · 3 superseded · 4 failed · enter = skip · q = quit')}`);
+  const more = all.length > CAP ? slate(` (most recent ${CAP}; ${all.length - CAP} older left alone)`) : '';
+  console.log(`  ${b(cream(`Judging your recent call${pending.length !== 1 ? 's' : ''}`))}${more}`);
+  console.log(`  ${slate('For each: what happened to it?')}`);
+  console.log(`  ${green('1')} ${sage('kept it')}   ${ember('2')} ${sage('undid it')}   ${peach('3')} ${sage('redid it differently')}   ${ember('4')} ${sage('it flopped')}`);
+  console.log(`  ${slate('Enter = skip (judge later) · q = stop. This is what teaches phewsh.')}`);
   ui.divider('line');
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -136,8 +170,21 @@ function labelInteractive() {
       }
       const idx = parseInt(a, 10);
       if (idx >= 1 && idx <= 4) {
-        labelOutcome(d.id, OUTCOMES[idx - 1]);
-        console.log(`  ${teal('●')} ${OUTCOME_COLOR[OUTCOMES[idx - 1]](OUTCOMES[idx - 1])}`);
+        const outcome = OUTCOMES[idx - 1];
+        // A miss is only useful if phewsh learns WHY — that one line is what
+        // /recall surfaces before you repeat it. Match the inline flow.
+        if (outcome === 'reverted' || outcome === 'failed') {
+          console.log(`  ${teal('●')} ${OUTCOME_COLOR[outcome](outcome)}`);
+          rl.question(`  ${slate('why? (one line — Enter to skip)')} ${teal('>')} `, (why) => {
+            labelOutcome(d.id, outcome, why.trim() || null);
+            if (why.trim()) console.log(`  ${slate('noted — /recall will remember why.')}`);
+            i++;
+            next();
+          });
+          return;
+        }
+        labelOutcome(d.id, outcome);
+        console.log(`  ${teal('●')} ${OUTCOME_COLOR[outcome](outcome)}`);
       }
       i++;
       next();

package/commands/session.js

@@ -17,7 +17,7 @@ const intentDir = () => path.join(process.cwd(), '.intent');
 const { select, refreshSession: refreshSess } = require('../lib/supabase');
 const { readPPS } = require('../lib/pps');
 const { push, pull, ensureValidToken } = require('./sync');
-const { HARNESSES, listHarnesses, runViaHarness, cancelActive } = require('../lib/harnesses');
+const { HARNESSES, interactiveLaunchArgs, listHarnesses, runViaHarness, cancelActive } = require('../lib/harnesses');
 const { recordDecision, labelOutcome, pendingDecisions, recentDecisions, outcomeStats, OUTCOMES } = require('../lib/outcomes');
 const { suggest, suggestAll } = require('../lib/suggest');
 const continuity = require('../lib/continuity');
@@ -28,6 +28,18 @@ const { closest } = require('../lib/closest');
 const cmdHistory = require('../lib/history');
 const { recordSessionEvent } = require('../lib/receipts-data');
 const configFile = require('../lib/config-file');
+const { loadIntentContext } = require('../lib/intent-context');
+const { auditTruth, formatTruth, quickVerifiedState } = require('../lib/truth');
+const { generateBrief, persistBrief } = require('../lib/brief');
+const {
+  applyReconciliation,
+  captureSnapshot,
+  createPostflight,
+  formatObservedReport,
+  observeCurrent,
+  reconciliationProposal,
+} = require('../lib/lifecycle');
+const { formatSourceContract } = require('../lib/source-contract');
 const { createFailureTracker, createLineDispatcher } = require('../lib/session-input');
 const {
   echoedRows,
@@ -173,19 +185,12 @@ function loadConfig() {
 }
 
 function saveConfig(config) {
-  configFile.saveConfig(CONFIG_PATH, config);
-}
-
-function loadIntentContext() {
-  const files = ['vision.md', 'plan.md', 'next.md'];
-  const loaded = [];
-  for (const file of files) {
-    const p = path.join(intentDir(), file);
-    if (fs.existsSync(p)) {
-      loaded.push({ file, content: fs.readFileSync(p, 'utf-8') });
-    }
+  try {
+    configFile.saveConfig(CONFIG_PATH, config);
+    return true;
+  } catch {
+    return false;
   }
-  return loaded;
 }
 
 function buildSystemPrompt(intentFiles) {
@@ -195,8 +200,8 @@ function buildSystemPrompt(intentFiles) {
     return base + `\n\nNo .intent/ artifacts found in the current directory. The user hasn't set up project context yet — help them think through what they're building if they ask.`;
   }
 
-  const sections = intentFiles.map(({ file, content }) =>
-    `## ${file}\n\n${content.trim()}`
+  const sections = intentFiles.map(({ file, promptContent, content }) =>
+    `## ${file}\n\n${(promptContent || content).trim()}`
   ).join('\n\n---\n\n');
 
   return `${base}\n\nThe user has structured intent artifacts for this project. Use them as primary context — stay aligned with their vision, plan, and next actions.\n\n${sections}`;
@@ -336,7 +341,8 @@ async function main() {
   let sessionMode = null;          // INTENT_MODES id once picked
   let awaitingOutcome = null;      // decision id eligible for 1-4 labeling
   let awaitingWhy = null;          // { id, outcome } — next line is the reason
-  let awaitingWrap = null;         // { block } — y/N to fold shipped work into next.md
+  let awaitingReconcile = null;    // exact proposed append, applied only after y
+  let lastTransitionReport = null; // latest native preflight -> postflight comparison
   let awaitingFallback = null;     // { input, fullSystem, options } after a route failure
   let bootstrapChoices = null;     // root-bootstrap menu entries when no project here
   let nextChoices = null;          // ranked /next suggestions awaiting a numeric pick
@@ -437,14 +443,31 @@ async function main() {
     row('WEB', sage('local-only (works fine)') + slate(' · /login mirrors this at phewsh.com/intent'));
   }
 
+  // VERIFIED — the product thesis made visible: what's actually true in this
+  // repo right now, checked (not remembered). Fast + offline + fail-soft.
+  try {
+    const v = quickVerifiedState();
+    if (!v.available) {
+      row('VERIFIED', slate('not a git repo here — ') + sage('/truth') + slate(' audits whatever is present'));
+    } else {
+      const parts = [cream('HEAD ' + v.shortHead)];
+      parts.push(v.dirtyCount ? peach(`${v.dirtyCount} uncommitted`) : sage('clean'));
+      if (v.driftCommits > 0) parts.push(ember(`⚠ ${v.driftCommits} commit${v.driftCommits !== 1 ? 's' : ''} since .intent updated`));
+      row('VERIFIED', parts.join(slate(' · ')) + slate('  — /truth · /brief'));
+    }
+  } catch { /* the verified row is a glance, never a blocker */ }
+
   const oStats = outcomeStats();
-  const oLabeled = oStats.total - oStats.pending;
   if (oStats.total > 0) {
-    const keptRate = oLabeled > 0 ? Math.round((oStats.kept / oLabeled) * 100) + '% kept' : 'unlabeled';
-    row('RECORD', cream(`${oStats.total} decision${oStats.total !== 1 ? 's' : ''}`) + slate(' · ') + sage(keptRate)
-      + (oStats.pending > 0 ? slate(' · ') + peach(`${oStats.pending} awaiting outcome`) + slate(' — /outcomes') : ''));
+    // Plain language: what phewsh has logged vs what you've taught it. The
+    // kept-rate counts only the calls you actually judged (auto route-errors
+    // don't drag it down) — see /outcomes for the full picture + payoff.
+    const tail = oStats.judged > 0
+      ? slate(' · ') + sage(`${Math.round((oStats.kept / oStats.judged) * 100)}% of what you judged, you kept`)
+      : slate(' · ') + peach('none judged yet — tell it what you kept');
+    row('RECORD', cream(`${oStats.total} routed`) + tail + slate(' — /outcomes'));
   } else {
-    row('RECORD', slate('empty — decisions and outcomes accumulate as you work'));
+    row('RECORD', slate('empty — phewsh starts logging what you route as you work'));
   }
   } catch (cockpitErr) {
     console.log(`  ${slate('(cockpit row unavailable — ' + cockpitErr.message + ' · PHEWSH_DEBUG=1 phewsh for details)')}`);
@@ -489,7 +512,8 @@ async function main() {
     } catch { /* no settings = ambient off */ }
 
     let pending = 0;
-    try { pending = pendingDecisions({ project: projectName }).length; } catch { /* best-effort */ }
+    // Only substantive calls — never nag the user to "judge" a greeting.
+    try { pending = pendingDecisions({ project: projectName, substantive: true }).length; } catch { /* best-effort */ }
 
     let installed = [];
     try { installed = listHarnesses().filter(h => h.installed).map(h => h.id); } catch { /* best-effort */ }
@@ -644,7 +668,7 @@ async function main() {
       });
       lastTurnFailure = null;
       awaitingOutcome = decisionId;
-      console.log(slate(`  via ${HARNESSES[harnessId].label} · outcome? 1 kept · 2 reverted · 3 superseded · 4 failed · or keep typing`));
+      console.log(slate(`  via ${HARNESSES[harnessId].label} · how'd it go? 1 kept · 2 undid · 3 redid · 4 flopped · or keep typing`));
       return true;
     } catch (err) {
       turnInFlight = false;
@@ -653,7 +677,7 @@ async function main() {
         console.log(`\n  ${slate('cancelled — esc')}`);
         return true; // user's call, not a failure: no fallback offer
       }
-      try { labelOutcome(decisionId, 'failed'); } catch { /* keep going */ }
+      try { labelOutcome(decisionId, 'failed', null, { auto: true }); } catch { /* keep going */ }
       recordSessionEvent(harnessId, projectName, 'task_complete', {
         taskId: decisionId, success: false, summary: input.slice(0, 140),
       });
@@ -684,7 +708,7 @@ async function main() {
       if (result.promptTokens) totalPromptTokens += result.promptTokens;
       if (result.completionTokens) totalCompletionTokens += result.completionTokens;
       if (result.promptTokens || result.completionTokens) {
-        console.log(slate(`  ${result.promptTokens || '?'}→${result.completionTokens || '?'} tokens · ${modelName(currentModel)} · outcome? 1-4 or keep typing`));
+        console.log(slate(`  ${result.promptTokens || '?'}→${result.completionTokens || '?'} tokens · ${modelName(currentModel)} · how'd it go? 1-4 or keep typing`));
       }
       awaitingOutcome = decisionId;
       trackSap({
@@ -705,7 +729,7 @@ async function main() {
         console.log(`\n  ${slate('cancelled — esc')}`);
         return true; // user's call, not a failure: no fallback offer
       }
-      try { labelOutcome(decisionId, 'failed'); } catch { /* keep going */ }
+      try { labelOutcome(decisionId, 'failed', null, { auto: true }); } catch { /* keep going */ }
       messages.pop();
       console.error(`\n  ${ember('!')} ${sage('API route failed')}${slate(' — ' + err.message.split('\n')[0])}`);
       return false;
@@ -812,10 +836,10 @@ async function main() {
   // so you know it registered. Arguments stay plain. TTY-only, fail-soft.
   const KNOWN_COMMANDS = new Set([
     'quit', 'exit', 'q', 'help', 'h', 'init', 'intent', 'clarify', 'model',
-    'models', 'council', 'all', 'provider', 'route', 'use', 'work', 'run',
+    'models', 'council', 'all', 'provider', 'route', 'use', 'work', 'switch', 'run',
     'clear', 'status', 'key', 'login', 'export', 'push', 'pull', 'serve',
     'sync', 'harnesses', 'fallback', 'outcomes', 'tour', 'update', 'upgrade',
-    'agents', 'context', 'gate', 'reload', 'sequence', 'seq', 'setup', 'system', 'watch',
+    'agents', 'context', 'truth', 'brief', 'wrap', 'reconcile', 'gate', 'reload', 'sequence', 'seq', 'setup', 'system', 'watch',
     'next', 'recommend', 'guide', 'thread', 'continuity', 'learn', 'stats',
   ]);
   const installedIds = harnesses.filter(h => h.installed).map(h => h.id);
@@ -990,19 +1014,23 @@ async function main() {
       return;
     }
 
-    // /wrap confirmation: y folds the shipped-work block into next.md + heals.
-    if (awaitingWrap) {
-      const { block } = awaitingWrap;
-      awaitingWrap = null;
+    // /reconcile confirmation: apply only the exact diff the user just saw.
+    if (awaitingReconcile) {
+      const proposal = awaitingReconcile;
+      awaitingReconcile = null;
       if (/^(y|yes)$/i.test(input.trim())) {
-        const r = selfheal.appendToNext(block);
+        const r = applyReconciliation(proposal);
         if (r.written) {
-          console.log(`  ${green('✓')} ${sage('Folded into .intent/' + r.file + ' — CLAUDE.md synced too. The record matches the work now.')}`);
+          const healed = selfheal.heal({ force: true });
+          intentFiles = loadIntentContext();
+          systemPrompt = buildSystemPrompt(intentFiles);
+          console.log(`  ${green('✓')} ${sage('Applied the approved diff to ' + r.target + '.')}`);
+          console.log(`  ${slate(healed.healed ? 'Generated Claude context refreshed from the approved intent change.' : 'Intent updated; generated context did not require a write.')}`);
         } else {
-          console.log(`  ${ember('!')} ${sage('Could not write .intent/next.md — left it untouched.')}`);
+          console.log(`  ${ember('!')} ${sage('Reconciliation was not applied: ' + r.reason)}`);
         }
       } else {
-        console.log(`  ${slate('Left .intent/ as-is.')}`);
+        console.log(`  ${slate('No authoritative files were changed.')}`);
       }
       console.log('');
       rl.prompt();
@@ -1263,33 +1291,34 @@ async function main() {
         return;
       }
 
-      // ── /wrap ──────────────────────────────────────────
-      // Fold what you've shipped (git commits since .intent/ was last updated)
-      // back into next.md, then re-sync CLAUDE.md — so the record reflects the
-      // work, not last week. Deterministic from commit subjects; no LLM needed,
-      // so it works even with nothing connected. This is the cure for the drift
-      // that ate phewsh's own dogfood.
+      // ── /wrap + /reconcile ─────────────────────────────
+      // Wrap observes. Reconcile proposes. Only an explicit yes writes intent.
       if (cmd === 'wrap') {
-        const draft = selfheal.wrapDraft();
         console.log('');
-        if (!draft) {
-          console.log(`  ${teal('●')} ${sage('Nothing to fold in — your .intent/ is already current with git (or this isn\'t a repo).')}`);
+        const truth = await auditTruth();
+        const observed = observeCurrent(truth);
+        lastTransitionReport = observed;
+        console.log(formatObservedReport(observed, { title: 'Wrap — observed current state' }));
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'reconcile') {
+        console.log('');
+        const report = lastTransitionReport || observeCurrent(await auditTruth());
+        const proposal = reconciliationProposal(report);
+        if (!proposal.available) {
+          console.log(`  ${ember('!')} ${sage('No reconciliation proposal: ' + proposal.reason)}`);
           console.log('');
           rl.prompt();
           return;
         }
-        const n = draft.commits.length;
-        console.log(`  ${b(cream('Wrap'))} ${slate('— ' + n + ' commit' + (n !== 1 ? 's' : '') + ' shipped since .intent/ was last updated')}`);
-        ui.divider('line');
-        for (const s of draft.commits.slice(0, 12)) {
-          let line = s.replace(/\s+/g, ' ');
-          if (line.length > 70) line = line.slice(0, 69).trimEnd() + '…';
-          console.log(`    ${sage('+')} ${cream(line)}`);
-        }
-        if (n > 12) console.log(`    ${slate('… and ' + (n - 12) + ' more')}`);
-        ui.divider('line');
-        console.log(`  ${sage('Fold this into')} ${cream('.intent/next.md')} ${sage('and re-sync CLAUDE.md?')} ${slate('y/N')}`);
-        awaitingWrap = { block: draft.block };
+        console.log('Reconciliation proposal (no files changed):');
+        console.log(proposal.diff);
+        console.log('');
+        console.log(`  ${sage('Apply this exact diff?')} ${slate('y/N')}`);
+        awaitingReconcile = proposal;
         rl.prompt();
         return;
       }
@@ -1368,7 +1397,10 @@ async function main() {
         console.log(`  ${cream('author .intent/')}`);
         console.log(`    ${teal('/init')}        ${sage('Create .intent/ for this project')}`);
         console.log(`    ${teal('/intent')}      ${sage('Pause and reflect — view or update .intent/ before moving on')}`);
-        console.log(`    ${teal('/wrap')}        ${sage('Fold what you shipped (git) into .intent/ — keeps the record current')}`);
+        console.log(`    ${teal('/truth')}       ${sage('Read-only audit of versions, Git, intent, projections, and conflicts')}`);
+        console.log(`    ${teal('/brief')}       ${sage('Generate the current provider-ready verified briefing')}`);
+        console.log(`    ${teal('/wrap')}        ${sage('Observe changes, contradictions, unknowns, and reconciliation needs')}`);
+        console.log(`    ${teal('/reconcile')}   ${sage('Propose an exact intent diff; writes only after approval')}`);
         console.log(`    ${teal('/clarify')}     ${sage('Turn ideas into .intent/ artifacts')}`);
         console.log(`    ${teal('/gate')}        ${sage('Set constraints (budget, time, skill)')}`);
         console.log(`    ${teal('/context')}     ${sage('Show loaded .intent/ files')}`);
@@ -1391,10 +1423,11 @@ async function main() {
         console.log(`    ${teal('/harnesses')}   ${sage('Agent CLIs detected on this machine')}`);
         console.log(`    ${teal('/provider')}    ${sage('Current route + what\'s available')}`);
         console.log(`    ${teal('/fallback')}    ${sage('What happens at a usage wall: ask or auto-switch')}`);
-        console.log(`    ${teal('/outcomes')}    ${sage('Decision record — kept/reverted/superseded/failed')}`);
+        console.log(`    ${teal('/outcomes')}    ${sage('What worked — tell phewsh, and it learns which tool to trust')}`);
         console.log('');
         console.log(`  ${cream('session')}`);
-        console.log(`    ${teal('/work')} ${slate('[harness]')} ${sage('Hand off to interactive Claude Code/Codex — outcome on return')}`);
+        console.log(`    ${teal('/work')} ${slate('[harness]')} ${sage('Preflight, brief, native handoff, automatic postflight')}`);
+        console.log(`    ${teal('/switch')} ${slate('<harness>')} ${sage('Launch another native tool with a freshly verified briefing')}`);
         console.log(`    ${teal('/run')} ${slate('<prompt>')} ${sage('One-shot prompt (no history)')}`);
         console.log(`    ${teal('esc')}          ${sage('Cancel a running turn · clear the input line')}`);
         console.log(`    ${teal('/clear')}       ${sage('Clear conversation')}`);
@@ -1450,6 +1483,7 @@ async function main() {
           ui.divider('line');
           intentFiles.forEach(f => console.log(`    ${teal('●')} ${cream(f.file)} ${slate('(' + f.content.length + ' chars)')}`));
           ui.divider('line');
+          console.log(formatSourceContract({ compact: true }).split('\n').map(line => `  ${line}`).join('\n'));
         } else {
           console.log(`\n  ${sage('No .intent/ context found in')} ${slate(process.cwd())}`);
           console.log(`  ${sage('Run')} ${cream('/init')} ${sage('to create one')}`);
@@ -1459,6 +1493,23 @@ async function main() {
         return;
       }
 
+      if (cmd === 'truth') {
+        console.log('');
+        console.log(formatTruth(await auditTruth()));
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
+      if (cmd === 'brief') {
+        console.log('');
+        const { content } = await generateBrief();
+        console.log(content);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'status') {
         const turns = messages.length / 2;
         config = loadConfig();
@@ -2020,9 +2071,9 @@ async function main() {
           messages.push({ role: 'user', content: cmdArg });
           messages.push({ role: 'assistant', content: `[council of ${answers.length}]\n\n${answers.join('\n\n')}` });
           awaitingOutcome = decisionId;
-          console.log(slate(`  council of ${answers.length} · outcome? 1 kept · 2 reverted · 3 superseded · 4 failed · or keep typing`));
+          console.log(slate(`  council of ${answers.length} · how'd it go? 1 kept · 2 undid · 3 redid · 4 flopped · or keep typing`));
         } else {
-          try { labelOutcome(decisionId, 'failed'); } catch { /* keep going */ }
+          try { labelOutcome(decisionId, 'failed', null, { auto: true }); } catch { /* keep going */ }
           console.log(`  ${sage('Every council member failed — check')} ${cream('/provider')}`);
         }
         console.log('');
@@ -2227,10 +2278,9 @@ async function main() {
         return;
       }
 
-      if (cmd === 'work') {
-        // Real work needs the real harness. Hand the terminal over to an
-        // interactive session, take it back when they exit, ask the outcome.
-        // phewsh stays the front door AND the return point.
+      if (cmd === 'work' || cmd === 'switch') {
+        // Native handoff lifecycle: verify -> brief -> release the terminal ->
+        // observe -> reconcile. The harness owns its UI while it runs.
         const target = cmdArg?.trim().toLowerCase() || (route?.type === 'harness' ? route.id : 'claude-code');
         const h = HARNESSES[target];
         if (!h) {
@@ -2243,6 +2293,13 @@ async function main() {
           rl.prompt();
           return;
         }
+
+        const preflightTruth = await auditTruth();
+        const before = captureSnapshot(preflightTruth);
+        const generatedBrief = await generateBrief({ report: preflightTruth });
+        const launchBrief = `${generatedBrief.content}\n\nThis is a PHEWSH transition briefing. Use it as project context, preserve native tool behavior, and verify claims against the repository before acting. When you finish, exit this tool — PHEWSH resumes, runs an automatic postflight comparing what changed against this brief, and offers reconciliation.`;
+        const savedBrief = persistBrief(generatedBrief.content, { project: projectName, route: target });
+        const launch = interactiveLaunchArgs(target, launchBrief, { model: harnessModel });
         const decisionId = recordDecision({
           project: projectName,
           route: target,
@@ -2251,23 +2308,49 @@ async function main() {
         });
         decisionsThisSession++;
         console.log('');
-        console.log(`  ${teal('●')} ${sage('Handing the terminal to')} ${cream(h.label)} ${slate('— exit to come back to phewsh')}`);
-        if (fs.existsSync(path.join(process.cwd(), 'CLAUDE.md')) || intentFiles.length > 0) {
-          console.log(`  ${slate('your .intent/ context rides along via CLAUDE.md')}`);
-        }
+        console.log(`  ${b(cream('Work preflight'))} ${slate('— verified before native handoff')}`);
+        ui.divider('line');
+        console.log(`  ${sage('Route:')} ${cream(h.label)}${harnessModel ? slate(' · model ' + harnessModel) : slate(' · native default model')}`);
+        console.log(`  ${sage('Git:')} ${cream(preflightTruth.git.shortHead || 'unknown')} ${slate('· ' + before.dirty.length + ' uncommitted path(s) before work')}`);
+        console.log(`  ${sage('Truth:')} ${preflightTruth.conflicts.length ? peach(preflightTruth.conflicts.length + ' conflict(s) carried explicitly') : green('no explicit conflicts')}`);
+        console.log(`  ${sage('Brief:')} ${launch.briefingPassed ? green('passed directly to the native harness') : peach('not injectable for this harness; available via /brief')}`);
+        console.log(`  ${sage('Record:')} ${savedBrief.written ? slate('exact briefing saved locally for this transition') : peach('briefing persistence unavailable; launch continues')}`);
+        console.log(`  ${slate('After exit PHEWSH will compare Git, files, intent claims, generated drift, and contradictions.')}`);
+        ui.divider('line');
+        console.log(`  ${teal('●')} ${sage('Handing the terminal to')} ${cream(h.label)} ${slate('— exit to return for postflight')}`);
         console.log('');
+        recordSessionEvent(target, projectName, 'work_started', {
+          taskId: decisionId,
+          summary: `interactive ${h.label} session`,
+          gitHead: before.head,
+          dirtyPaths: before.dirty,
+          briefingHash: savedBrief.hash,
+          briefingFile: savedBrief.file,
+          briefingPassed: launch.briefingPassed,
+        });
         pasteMode(false);
         rl.pause();
         const { spawnSync } = require('child_process');
-        const res = spawnSync(h.bin, [], { stdio: 'inherit' });
+        const res = spawnSync(h.bin, launch.args, { stdio: 'inherit' });
         rl.resume();
         pasteMode(true);
+        const postflight = await createPostflight(before);
+        lastTransitionReport = postflight;
         recordSessionEvent(target, projectName, 'task_complete', {
-          taskId: decisionId, success: res.status === 0, summary: `interactive ${h.label} session`,
+          taskId: decisionId,
+          success: res.status === 0,
+          summary: `interactive ${h.label} session`,
+          gitHeadBefore: before.head,
+          gitHeadAfter: postflight.afterHead,
+          changedFiles: postflight.files,
+          conflicts: postflight.conflicts,
+          briefingHash: savedBrief.hash,
         });
         awaitingOutcome = decisionId;
         console.log('');
-        console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate('outcome? 1 kept · 2 reverted · 3 superseded · 4 failed · or keep typing')}`);
+        console.log(formatObservedReport(postflight, { title: `${h.label} session ended — postflight` }));
+        console.log('');
+        console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate("1 kept · 2 undid · 3 redid · 4 flopped · /reconcile · /switch <tool>")}`);
         console.log('');
         rl.prompt();
         return;