phewsh 0.15.9 → 0.15.11

package/commands/clarify.js

@@ -37,7 +37,7 @@ async function askForInput() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
     console.log('\n  Describe what you\'re building. Be as messy as you want.\n');
-    console.log('  (You\'re the David Rose. PHEWSH is the business registration clerk.)\n');
+    console.log('  (You bring the messy idea. PHEWSH compiles it into a clear, structured spec.)\n');
     process.stdout.write('  > ');
     let input = '';
     rl.on('line', (line) => { input += (input ? ' ' : '') + line.trim(); });

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

@@ -244,6 +244,13 @@ async function streamChat(apiKey, messages, systemPrompt, modelId, opts = {}) {
   let completionTokens = null;
   let firstToken = true;
 
+  // Line-buffered markdown render at a TTY; raw passthrough otherwise. The
+  // spinner stops on first rendered output, not first raw token.
+  const stopSpin = () => { if (firstToken) { spin.stop(); firstToken = false; } };
+  const render = process.stdout.isTTY
+    ? require('../lib/md').streamRenderer((out) => { stopSpin(); process.stdout.write(out); })
+    : null;
+
   for await (const chunk of response.body) {
     const text = Buffer.from(chunk).toString('utf-8');
     const lines = text.split('\n').filter(l => l.startsWith('data: '));
@@ -253,11 +260,8 @@ async function streamChat(apiKey, messages, systemPrompt, modelId, opts = {}) {
       try {
         const parsed = JSON.parse(data);
         if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
-          if (firstToken) {
-            spin.stop();
-            firstToken = false;
-          }
-          process.stdout.write(parsed.delta.text);
+          if (render) render.push(parsed.delta.text);
+          else { stopSpin(); process.stdout.write(parsed.delta.text); }
           fullResponse += parsed.delta.text;
         }
         if (parsed.type === 'message_start' && parsed.message?.usage) {
@@ -270,6 +274,7 @@ async function streamChat(apiKey, messages, systemPrompt, modelId, opts = {}) {
     }
   }
 
+  if (render) render.flush();
   if (firstToken) spin.stop();
   process.stdout.write('\n');
 

package/lib/harnesses.js

@@ -106,20 +106,30 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
     child.stdin.end();
 
     let stderr = '';
-    let assembled = '';        // text shown to the user and returned
+    let assembled = '';        // raw text — returned + kept in history (never ANSI)
     let resultFallback = '';   // claude's final `result` field — never-blank guard
     let jsonBuf = '';
     let firstByte = false;
 
+    // Spinner stop + leading newline fire on first *displayed* output, so the
+    // line-buffered renderer never leaves a spinner-stopped-but-blank gap.
+    function onFirstShow() {
+      if (firstByte) return;
+      firstByte = true;
+      if (spin) { spin.stop(); spin = null; }
+      if (show) process.stdout.write('\n');
+    }
+    // Render markdown only at a real TTY; pipes/quiet get raw passthrough so
+    // council parsing and scripted use stay clean (no stray ANSI).
+    const render = (show && process.stdout.isTTY)
+      ? require('./md').streamRenderer((out) => { onFirstShow(); process.stdout.write(out); })
+      : null;
+
     function emit(text) {
       if (!text) return;
-      if (!firstByte) {
-        firstByte = true;
-        if (spin) { spin.stop(); spin = null; }
-        if (show) process.stdout.write('\n');
-      }
-      assembled += text;
-      if (show) process.stdout.write(text);
+      assembled += text; // always raw
+      if (render) render.push(text);
+      else if (show) { onFirstShow(); process.stdout.write(text); }
     }
 
     child.stdout.on('data', (d) => {
@@ -157,11 +167,13 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
           if (obj.type === 'result' && typeof obj.result === 'string') resultFallback = obj.result;
         } catch { /* partial trailing line */ }
       }
+      if (render) render.flush(); // render any trailing partial line
       // Streaming produced nothing but the result has text → show it. Never blank.
       let finalText = assembled;
       if (!assembled.trim() && resultFallback) {
         finalText = resultFallback;
-        if (show) process.stdout.write('\n' + resultFallback);
+        if (render) { render.push(resultFallback); render.flush(); }
+        else if (show) { onFirstShow(); process.stdout.write(resultFallback); }
       }
       if (show) process.stdout.write('\n');
       if (child._phewshCancelled) return reject(new Error(`${h.label} cancelled`));

package/lib/md.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// Terminal markdown rendering, safe for line-buffered streaming.
+//
+// Each completed line is rendered on its own — no cursor movement, no
+// in-place rewrites. That is deliberate: mid-stream cursor tricks under line
+// wrapping are the exact Apple Terminal hazard that has bitten this project
+// before. We hold tokens until a newline, render that finished line, and print
+// it. The only block-level state carried across lines is the code-fence flag,
+// so fenced code renders literally instead of as inline markdown.
+
+const A = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  ital: '\x1b[3m', italOff: '\x1b[23m',
+  uline: '\x1b[4m',
+  cream: '\x1b[38;5;230m',  // bold emphasis
+  teal: '\x1b[38;5;79m',    // code, links, headers
+  sage: '\x1b[38;5;151m',   // list items
+  slate: '\x1b[38;5;247m',  // dividers, quotes, link urls
+};
+
+// Inline spans: bold, italic, code, links. `base` is the SGR sequence to
+// restore the line's colour after each span's reset, so the rest of the line
+// keeps its block colour. Pass '' for default-foreground body text.
+function inlineMd(t, base = '') {
+  return t
+    .replace(/\*\*([^*]+)\*\*/g, (_, x) => `${A.bold}${A.cream}${x}${A.reset}${base}`)
+    .replace(/(^|\W)\*([^*\n]+)\*(?=\W|$)/g, (_, p, x) => `${p}${A.ital}${x}${A.italOff}${base}`)
+    .replace(/`([^`]+)`/g, (_, x) => `${A.teal}${x}${A.reset}${base}`)
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g,
+      (_, x, u) => `${A.uline}${A.teal}${x}${A.reset}${base} ${A.dim}${A.slate}(${u})${A.reset}${base}`);
+}
+
+// Render one complete line, mutating `state` for block-level context.
+// Body text keeps the default terminal foreground (bright) — only structural
+// elements get colour, so a reply reads as a reply, not as dimmed UI chrome.
+function renderLine(line, state = {}) {
+  const fence = line.match(/^\s*```+\s*\w*\s*$/);
+  if (fence) {
+    state.inFence = !state.inFence;
+    return `  ${A.slate}${A.dim}┄┄┄${A.reset}`;
+  }
+  if (state.inFence) {
+    return `  ${A.teal}${line}${A.reset}`; // literal code, no inline md
+  }
+  if (/^#{1,2}\s/.test(line)) return `\n${A.bold}${A.teal}${inlineMd(line.replace(/^#+\s*/, ''), A.teal)}${A.reset}`;
+  if (/^#{3,}\s/.test(line)) return `${A.cream}${inlineMd(line.replace(/^#+\s*/, ''), A.cream)}${A.reset}`;
+  if (/^\s*[-*]\s/.test(line)) return `  ${A.teal}·${A.reset} ${A.sage}${inlineMd(line.replace(/^\s*[-*]\s*/, ''), A.sage)}${A.reset}`;
+  if (/^\s*\d+\.\s/.test(line)) return `  ${A.sage}${inlineMd(line.trim(), A.sage)}${A.reset}`;
+  if (/^\s*>\s?/.test(line)) return `  ${A.slate}${A.ital}${inlineMd(line.replace(/^\s*>\s?/, ''), A.slate)}${A.italOff}${A.reset}`;
+  if (/^---+\s*$/.test(line)) return `  ${A.slate}${'─'.repeat(40)}${A.reset}`;
+  if (line.trim() === '') return '';
+  return inlineMd(line, ''); // body: default foreground, inline styling only
+}
+
+// Line-buffered streaming renderer. Feed raw token text via push(); each time a
+// newline completes a line, the rendered line (with its trailing '\n') is handed
+// to write(). flush() renders any trailing partial line at stream end. The
+// caller's write() is where first-output side effects (stop the spinner, print a
+// leading newline) belong, so they fire on first *rendered* output, not on the
+// first raw token — no spinner-stopped-but-blank gap.
+function streamRenderer(write) {
+  let buf = '';
+  const state = { inFence: false };
+  return {
+    push(text) {
+      buf += text;
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        write(renderLine(line, state) + '\n');
+      }
+    },
+    flush() {
+      if (buf.length) {
+        write(renderLine(buf, state) + '\n');
+        buf = '';
+      }
+    },
+  };
+}
+
+module.exports = { inlineMd, renderLine, streamRenderer };

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/package.json

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