phewsh 0.15.29 → 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

@@ -170,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,6 +443,20 @@ 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();
   if (oStats.total > 0) {
     // Plain language: what phewsh has logged vs what you've taught it. The
@@ -816,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);
@@ -994,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();
@@ -1267,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;
       }
@@ -1372,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')}`);
@@ -1398,7 +1426,8 @@ async function main() {
         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')}`);
@@ -1454,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')}`);
@@ -1463,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();
@@ -2231,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) {
@@ -2247,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,
@@ -2255,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("how'd it go? 1 kept · 2 undid · 3 redid · 4 flopped · 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;

package/commands/truth.js

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

package/lib/brief.js

@@ -0,0 +1,81 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { auditTruth } = require('./truth');
+
+function concise(value, max = 280) {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+
+function formatBrief(report, { cwd = process.cwd(), maxClaims = 5 } = {}) {
+  const lines = [];
+  const npm = report.package.npmLatest.status === 'known'
+    ? report.package.npmLatest.version
+    : `unknown (${report.package.npmLatest.reason})`;
+  const dirtyCount = report.git.tracked.length + report.git.untracked.length;
+
+  lines.push('# PHEWSH Verified Project Brief');
+  lines.push(`Project: ${path.basename(cwd)}`);
+  lines.push(`Generated: ${report.auditedAt}`);
+  lines.push('');
+  lines.push('## Verified State');
+  lines.push(`- Git HEAD: ${report.git.available ? report.git.shortHead : 'unknown'}`);
+  if (report.git.committedPackageVersion) lines.push(`- Package at Git HEAD: ${report.git.committedPackageVersion}`);
+  lines.push(`- Working package: ${report.package.version}`);
+  lines.push(`- npm latest: ${npm}`);
+  lines.push(`- Working tree: ${dirtyCount ? `${dirtyCount} changed path(s), uncommitted` : 'clean'}`);
+  lines.push('');
+  lines.push('## Intent Claims');
+  lines.push('These sources are authoritative for purpose and priorities, but code/release claims below remain claims until verified.');
+  report.intent.authoritative.slice(0, maxClaims).forEach(claim => {
+    lines.push(`- ${claim.file} [declared ${claim.declaredUpdated || 'unknown'}]: ${concise(claim.summary)}`);
+  });
+  lines.push('');
+  lines.push('## Conflicts And Unknowns');
+  if (!report.conflicts.length) lines.push('- No explicit conflicts detected.');
+  report.conflicts.forEach(item => lines.push(`- Conflict: ${concise(item, 360)}`));
+  if (!report.unknowns.length) lines.push('- No additional unknowns recorded.');
+  report.unknowns.slice(0, 6).forEach(item => lines.push(`- Unknown: ${concise(item, 360)}`));
+  lines.push('');
+  lines.push('## Continuity Evidence');
+  lines.push(`- Outcomes: ${report.outcomes.total} routed; ${report.outcomes.judged} human-judged; ${report.outcomes.pending} pending.`);
+  lines.push(`- Receipts: ${report.receipts.totalEvents} local event(s); ${report.receipts.completed} completed; ${report.receipts.failed} failed.`);
+  for (const item of report.outcomes.recent.slice(0, 3)) {
+    lines.push(`- Recent ${item.route || 'unknown'}: ${concise(item.summary, 180)}${item.outcome ? ` [${item.outcome}]` : ' [pending]'}`);
+  }
+  lines.push('');
+  lines.push('## Operating Contract');
+  lines.push('- Prefer verified runtime and repository evidence over generated summaries or model memory.');
+  lines.push('- Treat .intent/ as authoritative for goals and declared decisions, not as proof that implementation shipped.');
+  lines.push('- Do not describe working-tree changes as committed, published, or deployed.');
+  lines.push('- Surface disagreement explicitly. Do not silently merge conflicting sources.');
+  lines.push('- Before finishing, report what changed, what remains unknown, and what should be reconciled.');
+  return lines.join('\n');
+}
+
+async function generateBrief(options = {}) {
+  const report = options.report || await auditTruth(options);
+  return { report, content: formatBrief(report, options) };
+}
+
+function persistBrief(content, {
+  project = path.basename(process.cwd()),
+  route = 'unknown',
+  root = path.join(os.homedir(), '.phewsh', 'briefs'),
+} = {}) {
+  const hash = crypto.createHash('sha256').update(content).digest('hex');
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = path.join(root, project);
+  const file = path.join(dir, `${stamp}-${route}.md`);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, content);
+    return { written: true, file, hash };
+  } catch (err) {
+    return { written: false, file: null, hash, reason: err.message };
+  }
+}
+
+module.exports = { concise, formatBrief, generateBrief, persistBrief };

package/lib/harnesses.js

@@ -20,11 +20,11 @@ const { execSync, spawn } = require('child_process');
 // list of its own, so it can never go stale. Harnesses without a known
 // model flag ignore the preference and use their own config.
 const HARNESSES = {
-  'claude-code': { bin: 'claude',       label: 'Claude Code',  role: 'writes code',          auth: 'Claude subscription / Console', models: true, modelHints: ['sonnet', 'opus', 'haiku'], streamFormat: 'claude-json', args: (p, m) => ['-p', p, '--output-format', 'stream-json', '--include-partial-messages', '--verbose', ...(m ? ['--model', m] : [])] },
-  'codex':       { bin: 'codex',        label: 'Codex CLI',    role: 'reasons & reviews',    auth: 'ChatGPT plan',                  models: true, args: (p, m) => ['exec', '--skip-git-repo-check', ...(m ? ['-m', m] : []), p] },
-  'gemini':      { bin: 'gemini',       label: 'Gemini CLI',   role: "another model's take", auth: 'Google login',                  models: true, args: (p, m) => ['-p', p, ...(m ? ['-m', m] : [])] },
+  'claude-code': { bin: 'claude',       label: 'Claude Code',  role: 'writes code',          auth: 'Claude subscription / Console', models: true, modelHints: ['sonnet', 'opus', 'haiku'], streamFormat: 'claude-json', args: (p, m) => ['-p', p, '--output-format', 'stream-json', '--include-partial-messages', '--verbose', ...(m ? ['--model', m] : [])], interactiveArgs: (brief, m) => ['--append-system-prompt', brief, ...(m ? ['--model', m] : [])] },
+  'codex':       { bin: 'codex',        label: 'Codex CLI',    role: 'reasons & reviews',    auth: 'ChatGPT plan',                  models: true, args: (p, m) => ['exec', '--skip-git-repo-check', ...(m ? ['-m', m] : []), p], interactiveArgs: (brief, m) => [...(m ? ['-m', m] : []), brief] },
+  'gemini':      { bin: 'gemini',       label: 'Gemini CLI',   role: "another model's take", auth: 'Google login',                  models: true, args: (p, m) => ['-p', p, ...(m ? ['-m', m] : [])], interactiveArgs: (brief, m) => ['--prompt-interactive', brief, ...(m ? ['--model', m] : [])] },
   'cursor':      { bin: 'cursor-agent', label: 'Cursor Agent', role: 'edits files',          auth: 'Cursor account',                models: true, args: (p, m) => ['-p', p, '--output-format', 'text', ...(m ? ['--model', m] : [])] },
-  'opencode':    { bin: 'opencode',     label: 'OpenCode',     role: 'general agent',        auth: 'OpenCode Zen / configured',     args: (p) => ['run', p] },
+  'opencode':    { bin: 'opencode',     label: 'OpenCode',     role: 'general agent',        auth: 'OpenCode Zen / configured',     args: (p) => ['run', p], interactiveArgs: (brief) => ['--prompt', brief] },
   'grok':        { bin: 'grok',         label: 'Grok Build',   role: "xAI's take",           auth: 'SuperGrok / X Premium+',        args: (p) => ['-p', p] },
   'kiro':        { bin: 'kiro-cli',     label: 'Kiro CLI',     role: 'spec-driven dev',      auth: 'Kiro / AWS account',            args: (p) => ['chat', '--no-interactive', p] },
   'copilot':     { bin: 'copilot',      label: 'Copilot CLI',  role: 'github-native',        auth: 'GitHub Copilot plan',           args: (p) => ['-p', p] },
@@ -75,6 +75,16 @@ function listHarnesses() {
   return Object.entries(HARNESSES).map(([id, h]) => ({ id, ...h, headless: !!h.args, installed: isInstalled(id) }));
 }
 
+function interactiveLaunchArgs(id, brief, { model } = {}) {
+  const h = HARNESSES[id];
+  if (!h) throw new Error(`Unknown harness: ${id}`);
+  if (!h.interactiveArgs) return { args: [], briefingPassed: false };
+  return {
+    args: h.interactiveArgs(brief, h.models ? model : undefined),
+    briefingPassed: true,
+  };
+}
+
 /**
  * Run a prompt through a harness, streaming stdout to the terminal.
  * stderr is buffered and only surfaced on failure (codex/gemini chat on it).
@@ -187,4 +197,12 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
   });
 }
 
-module.exports = { HARNESSES, isInstalled, detectInstalled, listHarnesses, runViaHarness, cancelActive };
+module.exports = {
+  HARNESSES,
+  isInstalled,
+  detectInstalled,
+  interactiveLaunchArgs,
+  listHarnesses,
+  runViaHarness,
+  cancelActive,
+};