phewsh 0.15.10 → 0.15.12

package/commands/sequence.js

@@ -1,5 +1,6 @@
 // phewsh sequence (phewsh seq)
-// Universal Memory Transform — reads all AI memory files, emits optimal context.
+// Universal Memory Transform — reads this directory's memory files plus the
+// user's global per-tool memory (read-only), emits optimal context per target.
 
 const fs = require('fs');
 const path = require('path');
@@ -17,6 +18,7 @@ const flags = {
   write: args.includes('--write') || args.includes('-w'),
   dryRun: args.includes('--dry-run'),
   all: args.includes('--all'),
+  includeGlobal: args.includes('--include-global'),
   sources: getFlag('--sources', '-s'),
   help: args.includes('--help') || args.includes('-h'),
 };
@@ -47,15 +49,22 @@ function getPositionalTarget() {
 function showHelp() {
   console.log('');
   console.log(`  ${b(cream('phewsh sequence'))} ${slate('(phewsh seq)')}`);
-  console.log(`  ${sage('Universal Memory Transform — reads all AI memory files,')}`);
-  console.log(`  ${sage('emits optimal context for any target agent.')}`);
+  console.log(`  ${sage('Universal Memory Transform — reads the memory files in this')}`);
+  console.log(`  ${sage('directory plus your global per-user memory across tools,')}`);
+  console.log(`  ${sage('then emits optimal context for any target agent.')}`);
+  console.log('');
+  console.log(`  ${cream('reads')} ${slate('(read-only — phewsh never edits these)')}`);
+  console.log(`    ${sage('project  .intent/, CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules,')}`);
+  console.log(`    ${sage('         copilot-instructions, README, + this project’s Claude memory')}`);
+  console.log(`    ${sage('global   ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md')}`);
+  console.log(`    ${slate('global memory is per-user and travels across every project.')}`);
   console.log('');
   console.log(`  ${cream('usage')}`);
-  console.log(`    ${teal('phewsh seq')}              ${sage('Sequence → stdout summary')}`);
-  console.log(`    ${teal('phewsh seq')} ${slate('claude')}      ${sage('Sequence → CLAUDE.md section')}`);
+  console.log(`    ${teal('phewsh seq')}              ${sage('Sequence → stdout summary (project + global)')}`);
+  console.log(`    ${teal('phewsh seq')} ${slate('claude')}      ${sage('Sequence → CLAUDE.md section (project only)')}`);
   console.log(`    ${teal('phewsh seq')} ${slate('-w')}          ${sage('Write to target file')}`);
   console.log(`    ${teal('phewsh seq')} ${slate('--explain')}   ${sage('Show full ranking breakdown')}`);
-  console.log(`    ${teal('phewsh seq')} ${slate('--dry-run')}   ${sage('Show sources found, no output')}`);
+  console.log(`    ${teal('phewsh seq')} ${slate('--dry-run')}   ${sage('Show sources found (with scope), no output')}`);
   console.log('');
   console.log(`  ${cream('targets')}`);
   console.log(`    ${teal('claude')}     ${sage('CLAUDE.md section (between markers)')}`);
@@ -63,6 +72,8 @@ function showHelp() {
   console.log(`  ${cream('options')}`);
   console.log(`    ${teal('--budget')} ${slate('<level>')}   ${sage('Token budget: minimal|standard|full|unlimited')}`);
   console.log(`    ${teal('--sources')} ${slate('<list>')}  ${sage('Limit sources: intent,claude-md,claude-memory')}`);
+  console.log(`    ${teal('--include-global')}    ${sage('Allow global memory into a written project file')}`);
+  console.log(`    ${slate('                       (off by default — keeps personal notes out of committed files)')}`);
   console.log(`    ${teal('--write, -w')}         ${sage('Write output to target file')}`);
   console.log(`    ${teal('--explain, -e')}       ${sage('Full ranking breakdown')}`);
   console.log(`    ${teal('--dry-run')}           ${sage('Discover sources only')}`);
@@ -82,6 +93,9 @@ async function main() {
       sources = sources.filter(s => sourceFilter.some(f => s.type === f || s.type.startsWith(f)));
     }
 
+    const projectCount = sources.filter(s => s.scope !== 'global').length;
+    const globalCount = sources.filter(s => s.scope === 'global').length;
+
     console.log('');
     console.log(`  ${b(cream('Sources discovered'))} ${slate(`(${sources.length})`)}`);
     ui.divider('line');
@@ -89,10 +103,13 @@ async function main() {
       console.log(`  ${sage('No recognized memory files found in')} ${slate(process.cwd())}`);
     } else {
       for (const source of sources) {
-        console.log(`    ${teal(source.type.padEnd(20))} ${sage(source.name)}`);
+        const tag = source.scope === 'global' ? slate('global ') : sage('project');
+        console.log(`    ${tag} ${teal(source.type.padEnd(18))} ${sage(source.name)}`);
       }
     }
     ui.divider('line');
+    console.log(`  ${slate(`${projectCount} project · ${globalCount} global`)}`);
+    console.log(`  ${slate('global = per-user memory across all tools; summary-only unless --include-global on write')}`);
     console.log('');
     return;
   }
@@ -107,6 +124,7 @@ async function main() {
       sources: sourceFilter,
       explain: flags.explain,
       write: flags.write,
+      includeGlobal: flags.includeGlobal,
     });
 
     // If target is stdout, emit already printed

package/commands/session.js

@@ -19,6 +19,7 @@ const { readPPS } = require('../lib/pps');
 const { push, pull, ensureValidToken } = require('./sync');
 const { HARNESSES, listHarnesses, runViaHarness, cancelActive } = require('../lib/harnesses');
 const { recordDecision, labelOutcome, pendingDecisions, outcomeStats, OUTCOMES } = require('../lib/outcomes');
+const { suggest, suggestAll } = require('../lib/suggest');
 const { recordSessionEvent } = require('../lib/receipts-data');
 const configFile = require('../lib/config-file');
 const { createFailureTracker, createLineDispatcher } = require('../lib/session-input');
@@ -330,6 +331,7 @@ async function main() {
   let awaitingOutcome = null;      // decision id eligible for 1-4 labeling
   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
   let decisionsThisSession = 0;
 
   // ── The Exhale: animated brand reveal ──────────────────
@@ -454,6 +456,55 @@ async function main() {
     console.log(`  ${slate('pick a number, or just type — your context travels with every route')}`);
   }
 
+  // Self-aware guidance: snapshot the session's state so phewsh can recommend
+  // the one next step worth taking, instead of leaving the user to know commands.
+  function buildSuggestState() {
+    let seqStale = false;
+    try {
+      const cwd = process.cwd();
+      const claudePath = path.join(cwd, 'CLAUDE.md');
+      const intentDir = path.join(cwd, '.intent');
+      if (fs.existsSync(claudePath) && fs.existsSync(intentDir)) {
+        const claudeT = fs.statSync(claudePath).mtimeMs;
+        const newestIntent = fs.readdirSync(intentDir)
+          .filter(f => f.endsWith('.md') || f.endsWith('.json'))
+          .reduce((m, f) => Math.max(m, fs.statSync(path.join(intentDir, f)).mtimeMs), 0);
+        seqStale = newestIntent > claudeT + 1000; // >1s newer = drift
+      }
+    } catch { /* drift detection is best-effort */ }
+
+    let ambientOn = false;
+    try {
+      const s = fs.readFileSync(path.join(os.homedir(), '.claude', 'settings.json'), 'utf-8');
+      ambientOn = s.includes('phewsh hook session-start');
+    } catch { /* no settings = ambient off */ }
+
+    let pending = 0;
+    try { pending = pendingDecisions({ project: projectName }).length; } catch { /* best-effort */ }
+
+    let installed = [];
+    try { installed = listHarnesses().filter(h => h.installed).map(h => h.id); } catch { /* best-effort */ }
+
+    return {
+      hasIntentDir: fs.existsSync(path.join(process.cwd(), '.intent')),
+      intentFileCount: intentFiles.length,
+      pendingOutcomes: pending,
+      installedHarnesses: installed,
+      route,
+      turnsThisSession: Math.floor(messages.length / 2),
+      seqStale,
+      ambientOn,
+    };
+  }
+
+  // One subtle line under the menu — the single highest-leverage nudge, if any.
+  function showInlineTip() {
+    let tip = null;
+    try { tip = suggest(buildSuggestState()); } catch { /* never block the prompt on guidance */ }
+    if (!tip) return;
+    console.log(`  ${teal('⤷')} ${sage(tip.message)} ${cream(tip.command.trim())} ${slate('· /next for options')}`);
+  }
+
   // Open a known project from the bootstrap menu: chdir, reload memory,
   // back to the normal flow. The session is the cockpit; projects swap in.
   function openProjectAt(dir) {
@@ -470,6 +521,7 @@ async function main() {
     console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage(`.intent/ ${intentFiles.length} file${intentFiles.length !== 1 ? 's' : ''} loaded`)} ${slate('· via ' + routeLabel(route, config))}`);
     console.log('');
     showModeMenu();
+    showInlineTip();
     console.log('');
   }
 
@@ -502,6 +554,7 @@ async function main() {
     showBootstrapMenu(recents);
   } else {
     showModeMenu();
+    showInlineTip();
   }
   console.log('');
 
@@ -696,7 +749,8 @@ async function main() {
     'models', 'council', 'all', 'provider', 'route', 'use', 'work', 'run',
     'clear', 'status', 'key', 'login', 'export', 'push', 'pull', 'serve',
     'sync', 'harnesses', 'fallback', 'outcomes', 'tour', 'update', 'upgrade',
-    'agents', 'context', 'gate', 'reload', 'sequence', 'setup', 'system', 'watch',
+    'agents', 'context', 'gate', 'reload', 'sequence', 'seq', 'setup', 'system', 'watch',
+    'next', 'recommend', 'guide',
   ]);
   const installedIds = harnesses.filter(h => h.installed).map(h => h.id);
   let turnAbort = null;       // AbortController while an API turn streams
@@ -892,6 +946,29 @@ async function main() {
       return;
     }
 
+    // /next pick: a bare number runs the chosen suggestion (slash = in place).
+    // Any non-digit input means the user moved on — drop the offer so it never
+    // shadows a later mode pick.
+    if (nextChoices && !/^[0-9]$/.test(input)) nextChoices = null;
+    if (nextChoices && /^[0-9]$/.test(input)) {
+      const pick = nextChoices[parseInt(input, 10) - 1];
+      if (!pick) {
+        console.log(`  ${sage('Pick 1-' + nextChoices.length + ', or keep typing')}`);
+        rl.prompt();
+        return;
+      }
+      const command = pick.command.trim();
+      nextChoices = null;
+      if (command.startsWith('/')) {
+        await handleInput(command);   // re-dispatch the slash command in place
+        return;
+      }
+      console.log(`  ${teal('⤷')} ${sage('run this in your shell:')} ${cream(command)}`);
+      console.log('');
+      rl.prompt();
+      return;
+    }
+
     // Root bootstrap: a bare number opens a project, inits, or scans
     if (bootstrapChoices && messages.length === 0 && /^[0-9]{1,2}$/.test(input)) {
       const choice = bootstrapChoices[parseInt(input, 10) - 1];
@@ -996,10 +1073,41 @@ async function main() {
         process.exit(0);
       }
 
+      // ── /next ──────────────────────────────────────────
+      // The self-aware "what should I do?" button: phewsh reads the session's
+      // state and hands back ranked, pickable next steps — no command to recall.
+      if (cmd === 'next' || cmd === 'recommend' || cmd === 'guide') {
+        let ranked = [];
+        try { ranked = suggestAll(buildSuggestState()); } catch { /* best-effort */ }
+        console.log('');
+        if (ranked.length === 0) {
+          console.log(`  ${teal('●')} ${sage("You're aligned — nothing pressing. Keep working, or /help for everything.")}`);
+          console.log('');
+          nextChoices = null;
+          rl.prompt();
+          return;
+        }
+        console.log(`  ${b(cream('What would move you forward'))} ${slate('— pick a number, or ignore me')}`);
+        console.log('');
+        nextChoices = ranked.slice(0, 3);
+        nextChoices.forEach((s, i) => {
+          console.log(`  ${teal(String(i + 1))} ${cream(s.command.trim())}  ${sage(s.message)}`);
+          console.log(`     ${slate(s.why)}`);
+        });
+        console.log('');
+        console.log(`  ${slate('a slash command runs in place; anything else, I show you the line to run')}`);
+        console.log('');
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'help' || cmd === 'h') {
         console.log('');
         console.log(`  ${sage('the loop: define .intent/ → sync → work → evolve → repeat')}`);
         console.log('');
+        console.log(`  ${cream('not sure what to do?')}`);
+        console.log(`    ${teal('/next')}        ${sage("phewsh reads your state and hands back the next step worth taking")}`);
+        console.log('');
         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')}`);

package/lib/sequencer/discover.js

@@ -1,5 +1,15 @@
-// Discover all memory/context source files in the working directory.
-// Returns a list of { path, type } for each recognized source.
+// Discover all memory/context source files for the working directory.
+// Returns a list of { path, type, name, scope } for each recognized source.
+//
+// Two scopes:
+//   'project' — files in the working directory (this repo/project)
+//   'global'  — per-user memory that travels across every project
+//               (your global CLAUDE.md, Codex AGENTS.md, Gemini GEMINI.md)
+//
+// Global sources enrich the summary so `phewsh seq` reflects cross-tool
+// continuity even in a bare directory. They are deliberately kept OUT of
+// project-file writes by default (see sequence() includeGlobal) so personal
+// global notes never leak into a committed project CLAUDE.md.
 
 const fs = require('fs');
 const path = require('path');
@@ -8,8 +18,18 @@ const os = require('os');
 const INTENT_FILES = ['vision.md', 'plan.md', 'status.md', 'narrative.md', 'next.md'];
 const INTENT_JSON = ['project.json', 'pps.json', 'gate.json'];
 
-function discover(cwd = process.cwd()) {
+function discover(cwd = process.cwd(), home = os.homedir()) {
   const sources = [];
+  const seenPaths = new Set();
+
+  const add = (s) => {
+    const real = path.resolve(s.path);
+    if (seenPaths.has(real)) return; // never list the same file twice
+    seenPaths.add(real);
+    sources.push(s);
+  };
+
+  // ── Project scope ──────────────────────────────────────────────
 
   // .intent/ artifacts
   const intentDir = path.join(cwd, '.intent');
@@ -17,7 +37,7 @@ function discover(cwd = process.cwd()) {
     for (const file of [...INTENT_FILES, ...INTENT_JSON]) {
       const p = path.join(intentDir, file);
       if (fs.existsSync(p)) {
-        sources.push({ path: p, type: 'intent', name: file });
+        add({ path: p, type: 'intent', name: file, scope: 'project' });
       }
     }
   }
@@ -25,12 +45,12 @@ function discover(cwd = process.cwd()) {
   // CLAUDE.md — split into manual and generated sections later by parser
   const claudeMd = path.join(cwd, 'CLAUDE.md');
   if (fs.existsSync(claudeMd)) {
-    sources.push({ path: claudeMd, type: 'claude-md', name: 'CLAUDE.md' });
+    add({ path: claudeMd, type: 'claude-md', name: 'CLAUDE.md', scope: 'project' });
   }
 
   // Claude auto-memory — project-scoped
-  // .claude/projects/<encoded-cwd>/memory/MEMORY.md
-  const claudeDir = path.join(os.homedir(), '.claude');
+  // ~/.claude/projects/<encoded-cwd>/memory/MEMORY.md
+  const claudeDir = path.join(home, '.claude');
   if (fs.existsSync(claudeDir)) {
     const projectsDir = path.join(claudeDir, 'projects');
     if (fs.existsSync(projectsDir)) {
@@ -40,7 +60,7 @@ function discover(cwd = process.cwd()) {
       if (fs.existsSync(memoryDir)) {
         const memoryIndex = path.join(memoryDir, 'MEMORY.md');
         if (fs.existsSync(memoryIndex)) {
-          sources.push({ path: memoryIndex, type: 'claude-memory', name: 'MEMORY.md' });
+          add({ path: memoryIndex, type: 'claude-memory', name: 'MEMORY.md', scope: 'project' });
 
           // Also discover linked memory files from MEMORY.md
           try {
@@ -50,7 +70,7 @@ function discover(cwd = process.cwd()) {
             while ((match = linkRegex.exec(content)) !== null) {
               const linked = path.join(memoryDir, match[2]);
               if (fs.existsSync(linked)) {
-                sources.push({ path: linked, type: 'claude-memory-file', name: match[2] });
+                add({ path: linked, type: 'claude-memory-file', name: match[2], scope: 'project' });
               }
             }
           } catch { /* skip */ }
@@ -62,33 +82,54 @@ function discover(cwd = process.cwd()) {
   // .cursorrules
   const cursorrules = path.join(cwd, '.cursorrules');
   if (fs.existsSync(cursorrules)) {
-    sources.push({ path: cursorrules, type: 'cursor', name: '.cursorrules' });
+    add({ path: cursorrules, type: 'cursor', name: '.cursorrules', scope: 'project' });
   }
 
-  // agent.md / AGENTS.md
+  // agent.md / AGENTS.md (Codex / generic agent instructions, project scope)
   for (const name of ['agent.md', 'AGENTS.md']) {
     const p = path.join(cwd, name);
     if (fs.existsSync(p)) {
-      sources.push({ path: p, type: 'agent', name });
+      add({ path: p, type: 'agent', name, scope: 'project' });
     }
   }
 
+  // GEMINI.md (project scope)
+  const geminiMd = path.join(cwd, 'GEMINI.md');
+  if (fs.existsSync(geminiMd)) {
+    add({ path: geminiMd, type: 'agent', name: 'GEMINI.md', scope: 'project' });
+  }
+
   // soul.md
   const soulMd = path.join(cwd, 'soul.md');
   if (fs.existsSync(soulMd)) {
-    sources.push({ path: soulMd, type: 'soul', name: 'soul.md' });
+    add({ path: soulMd, type: 'soul', name: 'soul.md', scope: 'project' });
   }
 
   // .github/copilot-instructions.md
   const copilot = path.join(cwd, '.github', 'copilot-instructions.md');
   if (fs.existsSync(copilot)) {
-    sources.push({ path: copilot, type: 'copilot', name: 'copilot-instructions.md' });
+    add({ path: copilot, type: 'copilot', name: 'copilot-instructions.md', scope: 'project' });
   }
 
   // README.md (low priority but useful for identity)
   const readme = path.join(cwd, 'README.md');
   if (fs.existsSync(readme)) {
-    sources.push({ path: readme, type: 'readme', name: 'README.md' });
+    add({ path: readme, type: 'readme', name: 'README.md', scope: 'project' });
+  }
+
+  // ── Global scope (per-user, travels across every project) ──────
+  // Canonical global memory files for each agent CLI. Read-only; never
+  // written to. These give value even with no .intent/ in the directory.
+  // De-dup via seenPaths handles the edge where cwd === home.
+  const globals = [
+    { path: path.join(home, '.claude', 'CLAUDE.md'), type: 'claude-md', name: '~/.claude/CLAUDE.md' },
+    { path: path.join(home, '.codex', 'AGENTS.md'), type: 'agent', name: '~/.codex/AGENTS.md' },
+    { path: path.join(home, '.gemini', 'GEMINI.md'), type: 'agent', name: '~/.gemini/GEMINI.md' },
+  ];
+  for (const g of globals) {
+    if (fs.existsSync(g.path)) {
+      add({ path: g.path, type: g.type, name: g.name, scope: 'global' });
+    }
   }
 
   return sources;

package/lib/sequencer/emitters/stdout.js

@@ -58,7 +58,8 @@ function emitExplain(chunks, sources, { b, w, g, sage, slate, teal, cream, green
   // Sources discovered
   console.log(`  ${b(cream('Sources'))}`);
   for (const source of sources) {
-    console.log(`    ${teal(source.type.padEnd(16))} ${sage(source.name)}`);
+    const tag = source.scope === 'global' ? slate('global ') : sage('project');
+    console.log(`    ${tag} ${teal(source.type.padEnd(14))} ${sage(source.name)}`);
   }
   console.log('');
 

package/lib/sequencer/index.js

@@ -45,12 +45,20 @@ function sequence(options = {}) {
     sources: sourceFilter = null,
     explain = false,
     write = false,
+    includeGlobal = false,
     cwd = process.cwd(),
   } = options;
 
-  // 1. Discover all source files
+  // 1. Discover all source files (project + global)
   let sources = discover(cwd);
 
+  // Privacy guard: global per-user memory enriches the summary (stdout), but
+  // never bleeds into a project-file target (CLAUDE.md) unless asked for —
+  // so personal global notes don't land in a committed project file.
+  if (target !== 'stdout' && !includeGlobal) {
+    sources = sources.filter(s => s.scope !== 'global');
+  }
+
   // Filter sources if requested
   if (sourceFilter && sourceFilter.length > 0) {
     sources = sources.filter(s =>

package/lib/sequencer/parsers/claude-md.js

@@ -39,8 +39,9 @@ function parse(source) {
 
       const kind = classifySection(section.title);
       chunks.push({
-        source: `CLAUDE.md:${section.title || 'root'}`,
+        source: `${source.name}:${section.title || 'root'}`,
         sourceType: 'claude-md-manual',
+        scope: source.scope || 'project',
         kind,
         content: section.body.trim(),
         timestamp: mtime,
@@ -52,8 +53,9 @@ function parse(source) {
   // Generated section — lower authority, will get deduped against .intent/
   if (generatedContent) {
     chunks.push({
-      source: 'CLAUDE.md:phewsh-generated',
+      source: `${source.name}:phewsh-generated`,
       sourceType: 'claude-md-generated',
+      scope: source.scope || 'project',
       kind: 'context',
       content: generatedContent,
       timestamp: mtime,

package/lib/sequencer/parsers/generic.js

@@ -21,6 +21,7 @@ function parse(source) {
   return [{
     source: source.name,
     sourceType: source.type,
+    scope: source.scope || 'project',
     kind,
     content: content.trim(),
     timestamp: mtime,

package/lib/suggest.js

@@ -0,0 +1,111 @@
+// Self-aware guidance — phewsh watching the user's state and surfacing the
+// single most useful next step, so nobody has to memorize commands like
+// `phewsh seq --dry-run`. Pure and deterministic: feed it a state snapshot,
+// get back ranked suggestions. The session layer renders + offers them.
+//
+// Each suggestion: { id, priority, message, command, why }
+//   message — one plain line, what's true right now (the caller colorizes)
+//   command — the exact thing to run (a slash command or shell command)
+//   why     — one short clause: why it helps (shown on /next, not inline)
+//
+// Design rules:
+//   - Never nag: a suggestion only fires when its trigger is genuinely met.
+//   - One at a time inline; up to a few on demand via /next.
+//   - Ordered by leverage — capture-intent and learn-from-outcomes first,
+//     because those are the moat; convenience nudges last.
+
+/**
+ * @param {object} s state snapshot
+ * @param {boolean} s.hasIntentDir      — .intent/ exists in cwd
+ * @param {number}  s.intentFileCount   — .intent/ files loaded
+ * @param {number}  s.pendingOutcomes   — unlabeled decisions (this project)
+ * @param {string[]} s.installedHarnesses — harness ids present on the machine
+ * @param {string[]} [s.usedRoutes]     — harness ids used this session
+ * @param {string|null} s.route         — current route id
+ * @param {number}  s.turnsThisSession  — exchanges so far
+ * @param {boolean} s.seqStale          — .intent/ newer than CLAUDE.md (drift)
+ * @param {boolean} s.ambientOn         — ambient hooks installed
+ * @returns {Array} ranked suggestions (highest leverage first)
+ */
+function suggestAll(s = {}) {
+  const {
+    hasIntentDir = false,
+    intentFileCount = 0,
+    pendingOutcomes = 0,
+    installedHarnesses = [],
+    usedRoutes = [],
+    route = null,
+    turnsThisSession = 0,
+    seqStale = false,
+    ambientOn = false,
+  } = s;
+
+  const out = [];
+
+  // 1. Working without captured intent — the biggest miss. Every AI tool here
+  //    could be reading the same goal; right now none are.
+  if (intentFileCount === 0 && turnsThisSession >= 2) {
+    out.push({
+      id: 'capture-intent',
+      priority: 100,
+      message: `${turnsThisSession} messages in, no captured intent — every AI here is guessing.`,
+      command: '/clarify',
+      why: 'Turns what you just said into a spec every tool (this one, Claude Code, Codex) reads.',
+    });
+  }
+
+  // 2. Decisions piling up unlabeled — the record only gets smarter if labeled.
+  if (pendingOutcomes >= 3) {
+    out.push({
+      id: 'label-outcomes',
+      priority: 90,
+      message: `${pendingOutcomes} decisions unlabeled — phewsh can't learn what you keep until you say.`,
+      command: '/outcomes',
+      why: 'Labeling kept/reverted is the dataset; it weights future routing and recall.',
+    });
+  }
+
+  // 3. .intent/ drifted from CLAUDE.md — the editor's AI is reading stale context.
+  if (hasIntentDir && seqStale) {
+    out.push({
+      id: 'resync-claude-md',
+      priority: 80,
+      message: `Your .intent/ changed but CLAUDE.md didn't — editor AIs are reading stale context.`,
+      command: '/seq claude',
+      why: 'Re-sequences the latest intent + memory into CLAUDE.md so every tool sees today.',
+    });
+  }
+
+  // 4. Multiple harnesses installed, only leaning on one — council is free leverage.
+  const others = installedHarnesses.filter(h => h !== route);
+  if (installedHarnesses.length >= 2 && turnsThisSession >= 3 && others.length >= 1) {
+    out.push({
+      id: 'try-council',
+      priority: 60,
+      message: `You have ${installedHarnesses.length} agents installed but lean on one — the rest are idle.`,
+      command: '/council ',
+      why: 'Asks every installed harness in parallel; you keep the best answer, context shared.',
+    });
+  }
+
+  // 5. Ambient off — continuity that costs nothing once turned on.
+  if (hasIntentDir && !ambientOn && installedHarnesses.includes('claude-code')) {
+    out.push({
+      id: 'enable-ambient',
+      priority: 50,
+      message: `Ambient is off — Claude Code sessions here won't get the brief unless you launch phewsh.`,
+      command: 'phewsh ambient',
+      why: 'Installs a silent SessionStart hook so continuity travels even when you forget phewsh.',
+    });
+  }
+
+  return out.sort((a, b) => b.priority - a.priority);
+}
+
+/** The single highest-leverage suggestion, or null. */
+function suggest(s = {}) {
+  const all = suggestAll(s);
+  return all.length ? all[0] : null;
+}
+
+module.exports = { suggest, suggestAll };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.15.10",
+  "version": "0.15.12",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"