phewsh 0.15.42 → 0.15.44

package/commands/ambient.js

@@ -19,6 +19,7 @@ const os = require('os');
 const readline = require('readline');
 const { listHarnesses } = require('../lib/harnesses');
 const selfheal = require('../lib/selfheal');
+const slash = require('../lib/slash-commands');
 
 const PHEWSH_DIR = path.join(os.homedir(), '.phewsh');
 const LEDGER_FILE = path.join(PHEWSH_DIR, 'ambient.json');
@@ -169,6 +170,7 @@ async function turnOn(skipConfirm) {
 
   const changes = applyClaudeHooks();
   const { written } = selfheal.syncGlobalBaseFiles();
+  const slashWritten = slash.installSlashCommands().written;
   const ledger = loadLedger();
   ledger.applied['claude-code'] = {
     at: new Date().toISOString(),
@@ -184,6 +186,13 @@ async function turnOn(skipConfirm) {
       undo: 'phewsh ambient off',
     };
   }
+  if (slashWritten.length > 0 || ledger.applied.slashCommands) {
+    ledger.applied.slashCommands = {
+      at: new Date().toISOString(),
+      tools: slashWritten.length > 0 ? slashWritten : (ledger.applied.slashCommands || {}).tools || [],
+      undo: 'phewsh ambient off',
+    };
+  }
   ledger.seenHarnesses = harnesses.filter(h => h.installed).map(h => h.id);
   ledger.disabled = false; // explicit enable clears any prior opt-out
   saveLedger(ledger);
@@ -192,6 +201,7 @@ async function turnOn(skipConfirm) {
   console.log(`  ${green('●')} ${b('Ambient is on.')}`);
   changes.forEach(c => console.log(`    ${teal('+')} ${slate(c)}`));
   written.forEach(f => console.log(`    ${teal('+')} ${slate('base file ' + f + ' (machine-wide phewsh awareness)')}`));
+  if (slashWritten.length) console.log(`    ${teal('+')} ${cream('/intent')} ${slate('command added to ' + slashWritten.join(', '))}`);
   console.log('');
   console.log(`  ${sage('Next Claude Code session in a project with')} ${cream('.intent/')} ${sage('starts pre-briefed.')}`);
   if (written.length > 0) {
@@ -204,17 +214,20 @@ async function turnOn(skipConfirm) {
 function turnOff() {
   const removed = removeClaudeHooks();
   const { removed: removedGlobal } = selfheal.removeGlobalBaseFiles();
+  const { removed: removedSlash } = slash.removeSlashCommands();
   const ledger = loadLedger();
   delete ledger.applied['claude-code'];
   delete ledger.applied.globalBase;
+  delete ledger.applied.slashCommands;
   delete ledger.autoEnabledAt;
   ledger.disabled = true; // sticky opt-out — first-run auto-enable must respect this
   saveLedger(ledger);
   console.log('');
-  if (removed.length > 0 || removedGlobal.length > 0) {
+  if (removed.length > 0 || removedGlobal.length > 0 || removedSlash.length > 0) {
     console.log(`  ${green('●')} ${b('Ambient is off.')}`);
     removed.forEach(c => console.log(`    ${peach('-')} ${slate(c)}`));
     removedGlobal.forEach(f => console.log(`    ${peach('-')} ${slate('base file ' + f + ' (phewsh block removed)')}`));
+    if (removedSlash.length) console.log(`    ${peach('-')} ${slate('/intent command removed from ' + removedSlash.join(', '))}`);
     console.log(`  ${sage('Breadcrumb log kept at')} ${cream('~/.phewsh/ambient-sessions.jsonl')} ${sage('— delete it if you want; phewsh never will.')}`);
   } else {
     console.log(`  ${sage('Nothing was applied — nothing to remove.')}`);
@@ -302,6 +315,7 @@ async function ensureAuto() {
   const hasClaude = installed.some(h => h.id === 'claude-code');
   const changes = hasClaude ? applyClaudeHooks() : [];
   const { written } = selfheal.syncGlobalBaseFiles();
+  const slashWritten = slash.installSlashCommands().written;
   // Refresh existing project files only — first-run auto-enable must not dump
   // context files into whatever repo the user happens to be standing in.
   try { selfheal.syncContextFiles({ createMissing: false }); } catch { /* best-effort */ }
@@ -317,6 +331,9 @@ async function ensureAuto() {
   if (written.length > 0) {
     ledger.applied.globalBase = { at: now, files: written, undo: 'phewsh ambient off' };
   }
+  if (slashWritten.length > 0) {
+    ledger.applied.slashCommands = { at: now, tools: slashWritten, undo: 'phewsh ambient off' };
+  }
   ledger.disabled = false;
   ledger.autoEnabledAt = now;
   ledger.seenHarnesses = installed.map(h => h.id);
@@ -327,6 +344,7 @@ async function ensureAuto() {
     console.log(`  ${b(cream('phewsh set itself up across your AI tools'))} ${sage('— so they stay in sync with your project intent.')}`);
     if (hasClaude) console.log(`    ${teal('+')} ${slate('Claude Code gets a brief from a project\'s .intent/ at session start')}`);
     written.forEach(f => console.log(`    ${teal('+')} ${slate('environment note added to ' + f)}`));
+    if (slashWritten.length) console.log(`    ${teal('+')} ${cream('/intent')} ${slate('command added to ' + slashWritten.join(', '))}`);
     console.log(`    ${sage('In any project with')} ${cream('.intent/')}${sage(', your tools now read its real intent. Reversible:')} ${cream('phewsh ambient off')}`);
     console.log(`    ${sage('Want a guaranteed status line each time you launch a tool?')} ${cream('phewsh shim on')}`);
     console.log('');

package/commands/session.js

@@ -579,6 +579,9 @@ async function main() {
       ambientOn = s.includes('phewsh hook session-start');
     } catch { /* no settings = ambient off */ }
 
+    let shimOn = false;
+    try { shimOn = require('../lib/shims').shimStatus().installed.length > 0; } catch { /* shims off */ }
+
     let pending = 0;
     // Only substantive calls — never nag the user to "judge" a greeting.
     try { pending = pendingDecisions({ project: projectName, substantive: true }).length; } catch { /* best-effort */ }
@@ -601,6 +604,7 @@ async function main() {
       turnsThisSession: Math.floor(messages.length / 2),
       seqStale,
       ambientOn,
+      shimOn,
       commitsSinceIntent: (() => { try { return selfheal.commitsSinceIntent(); } catch { return 0; } })(),
       bestKeeper,
     };

package/lib/shims.js

@@ -65,24 +65,79 @@ exit 127
 `;
 }
 
-// Deterministic launch banner — computed by phewsh, offline, fast. This is the
-// proof-of-life the user asked for: it appears because phewsh printed it.
+// First meaningful line of a markdown file — past YAML frontmatter and headings.
+function firstLine(file, max = 64) {
+  try {
+    let body = fs.readFileSync(file, 'utf-8');
+    if (body.startsWith('---')) { const e = body.indexOf('\n---', 3); if (e !== -1) body = body.slice(e + 4); }
+    const line = body.split('\n').map(l => l.trim())
+      .find(l => l && !l.startsWith('#') && !l.startsWith('>') && !l.startsWith('---'));
+    if (!line) return null;
+    const clean = line.replace(/[*_`]/g, '').replace(/\s+/g, ' ').trim();
+    return clean.length > max ? clean.slice(0, max - 1) + '…' : clean;
+  } catch { return null; }
+}
+
+// How many decisions phewsh has recorded for this project (cwd basename key).
+function decisionCount(cwd) {
+  try {
+    const file = path.join(PHEWSH_DIR, 'outcomes', 'decisions.json');
+    const all = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    const key = path.basename(cwd);
+    const list = Array.isArray(all) ? all : (all.decisions || []);
+    return list.filter(d => (d.project || d.cwd && path.basename(d.cwd)) === key).length;
+  } catch { return 0; }
+}
+
+// Per-repo nudge counter — so the "create intent" coaching shows for the first
+// few launches then goes quiet (a coach, not a billboard). Best-effort.
+function bumpNudge(cwd) {
+  try {
+    const file = path.join(PHEWSH_DIR, 'shim-seen.json');
+    let seen = {};
+    try { seen = JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { /* fresh */ }
+    seen[cwd] = (seen[cwd] || 0) + 1;
+    fs.mkdirSync(PHEWSH_DIR, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(seen));
+    return seen[cwd];
+  } catch { return 99; } // on failure, assume "seen" so we don't nag
+}
+
+// Deterministic launch banner — computed by phewsh, offline, fast. Evidence +
+// VALUE + GUIDANCE, not just "active". phewsh prints it, so it's guaranteed.
+const C = { teal: s => `\x1b[38;5;79m${s}\x1b[0m`, sage: s => `\x1b[38;5;151m${s}\x1b[0m`, slate: s => `\x1b[38;5;247m${s}\x1b[0m`, cream: s => `\x1b[38;5;230m${s}\x1b[0m`, peach: s => `\x1b[38;5;216m${s}\x1b[0m` };
 function preflightBanner(bin, cwd = process.cwd()) {
-  let intent = 'no .intent here';
-  let record = '';
   try {
     const intentDir = path.join(cwd, '.intent');
-    if (fs.existsSync(intentDir)) {
-      const n = fs.readdirSync(intentDir).filter(f => /\.(md|json)$/.test(f)).length;
-      intent = `.intent loaded (${n} file${n === 1 ? '' : 's'})`;
-      try {
-        const { statusDrift } = require('./truth');
-        const d = statusDrift(cwd);
-        if (d && d.tracked) record = d.commitsSince > 0 ? ` · record ${d.commitsSince} behind` : ' · record current';
-      } catch { /* drift is a nicety */ }
+    if (!fs.existsSync(intentDir)) {
+      // No shared truth here. Coach (first few launches per repo), then go quiet.
+      const n = bumpNudge(cwd);
+      if (n <= 3) {
+        return `${C.sage('😮‍💨🤫 phewsh')} ${C.slate('· no shared project truth here yet')}\n`
+          + `   ${C.slate('so every AI tool stays in sync, create it:')} ${C.cream('phewsh intent --init')} ${C.slate('· → ' + bin)}`;
+      }
+      return `${C.sage('😮‍💨🤫 phewsh active')} ${C.slate('· → ' + bin)}`;
     }
-  } catch { /* never break the banner */ }
-  return `😮‍💨🤫 phewsh active · ${intent}${record} · → ${bin}`;
+    // Truth present — show the value + continuity health.
+    const files = fs.readdirSync(intentDir).filter(f => /\.(md|json)$/.test(f)).length;
+    const vision = firstLine(path.join(intentDir, 'vision.md'));
+    const next = firstLine(path.join(intentDir, 'next.md')) || firstLine(path.join(intentDir, 'status.md'));
+    const decisions = decisionCount(cwd);
+    let health = '✓ intent';
+    try {
+      const { statusDrift } = require('./truth');
+      const d = statusDrift(cwd);
+      if (d && d.tracked) health += d.commitsSince > 0 ? `  ${C.peach('⚠ record ' + d.commitsSince + ' behind')}` : '  ✓ record current';
+    } catch { /* nicety */ }
+
+    const lines = [`${C.sage('😮‍💨🤫 phewsh active')}  ${C.slate(health)}  ${C.slate('· → ' + bin)}`];
+    if (vision) lines.push(`   ${C.slate('vision:')} ${C.cream(vision)}`);
+    if (next) lines.push(`   ${C.slate('next:  ')} ${C.cream(next)}${decisions ? C.slate('  · ' + decisions + ' decisions') : ''}`);
+    else if (decisions) lines.push(`   ${C.slate(decisions + ' decisions · ' + files + ' intent files')}`);
+    return lines.join('\n');
+  } catch {
+    return `😮‍💨🤫 phewsh active · → ${bin}`; // never break the launch
+  }
 }
 
 // ── shell rc (PATH activation) ──────────────────────────────────────────

package/lib/slash-commands.js

@@ -0,0 +1,98 @@
+// phewsh slash commands — teach ONE verb, not a tool.
+//
+// CG's insight: the first thing a user should learn isn't `phewsh`, it's
+// `/intent`. If every AI tool has `/intent`, the user learns the BEHAVIOR they
+// want (see this project's truth) without learning the implementation. So
+// phewsh installs `/intent` into each harness's NATIVE custom-command slot —
+// a structured, user-invoked channel (not injected prose). It only does
+// something when the user types it, so there's nothing for a model to flag.
+//
+// Each harness has its own format/dir; we only install for tools present, and
+// never clobber a command the user wrote (we mark ours + check the marker).
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const MARKER = 'phewsh-managed';
+
+// The portable prompt `/intent` runs. It's a user-invoked request to surface
+// the project's own .intent/ docs — trusted because the user asked for it.
+const INTENT_PROMPT = `Show me this project's current intent, read from its \`.intent/\` directory. Be concise:
+- **Vision** — what we're building and why
+- **Current objective / next** — what's in flight
+- **Constraints** — budget, time, scope, non-negotiables
+- **Recent decisions** — and any that are still open
+
+If there is no \`.intent/\` directory here, say so and tell me I can create one with \`phewsh intent --init\` so every AI tool I use shares the same project truth.`;
+
+// Tools that support file-based custom slash commands, and how each wants them.
+// parentDir must already exist (the tool is installed) before we write.
+//
+// Claude Code is deliberately EXCLUDED: it already ships a phewsh `/intent`
+// SKILL (the artifact generator) and gets the SessionStart hook brief, so a
+// global `/intent` command here just collides with the canonical one (two
+// `/intent` entries). We add `/intent` only where it's genuinely absent.
+const SLASH_TARGETS = [
+  { id: 'codex',  parent: '.codex',  sub: 'prompts',  file: 'intent.md', fmt: 'codex' },
+  { id: 'gemini', parent: '.gemini', sub: 'commands', file: 'intent.toml', fmt: 'gemini' },
+];
+
+function bodyFor(fmt) {
+  if (fmt === 'claude') {
+    return `---\ndescription: Show this project's intent — vision, objective, constraints, decisions (phewsh)\n---\n<!-- ${MARKER} · remove with: phewsh ambient off -->\n\n${INTENT_PROMPT}\n`;
+  }
+  if (fmt === 'codex') {
+    return `<!-- ${MARKER} · remove with: phewsh ambient off -->\n${INTENT_PROMPT}\n`;
+  }
+  if (fmt === 'gemini') {
+    const esc = INTENT_PROMPT.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+    return `# ${MARKER} · remove with: phewsh ambient off\ndescription = "Show this project's intent via phewsh"\nprompt = """\n${esc}\n"""\n`;
+  }
+  return INTENT_PROMPT;
+}
+
+function targetPath(t) {
+  return path.join(os.homedir(), t.parent, t.sub, t.file);
+}
+
+// Install /intent for every present tool. Won't overwrite a user's own command
+// (only a file we previously marked, or a fresh write). Returns written ids.
+function installSlashCommands() {
+  const written = [];
+  for (const t of SLASH_TARGETS) {
+    try {
+      if (!fs.existsSync(path.join(os.homedir(), t.parent))) continue; // tool not installed
+      const fp = targetPath(t);
+      if (fs.existsSync(fp)) {
+        const cur = fs.readFileSync(fp, 'utf-8');
+        if (!cur.includes(MARKER)) continue; // user's own /intent — leave it
+        if (cur === bodyFor(t.fmt)) continue; // already current
+      }
+      fs.mkdirSync(path.dirname(fp), { recursive: true });
+      fs.writeFileSync(fp, bodyFor(t.fmt));
+      written.push(t.id);
+    } catch { /* best-effort per tool */ }
+  }
+  return { written };
+}
+
+function removeSlashCommands() {
+  const removed = [];
+  for (const t of SLASH_TARGETS) {
+    try {
+      const fp = targetPath(t);
+      if (fs.existsSync(fp) && fs.readFileSync(fp, 'utf-8').includes(MARKER)) {
+        fs.unlinkSync(fp);
+        removed.push(t.id);
+      }
+    } catch { /* best-effort */ }
+  }
+  return { removed };
+}
+
+function detectSlashTargets() {
+  return SLASH_TARGETS.filter(t => fs.existsSync(path.join(os.homedir(), t.parent)));
+}
+
+module.exports = { installSlashCommands, removeSlashCommands, detectSlashTargets, INTENT_PROMPT };

package/lib/suggest.js

@@ -38,6 +38,7 @@ function suggestAll(s = {}) {
     turnsThisSession = 0,
     seqStale = false,
     ambientOn = false,
+    shimOn = false,
     commitsSinceIntent = 0,
     bestKeeper = null,   // { route, label, keptRate, total } from the record, or null
   } = s;
@@ -132,6 +133,18 @@ function suggestAll(s = {}) {
     });
   }
 
+  // 6. Shim off — the guaranteed proof-of-life. phewsh prints a status banner
+  // when you launch any tool, then runs the real tool. Offer once it's not on.
+  if (!shimOn && installedHarnesses.length > 0) {
+    out.push({
+      id: 'enable-shim',
+      priority: 48,
+      message: `See phewsh work every time you launch a tool — a status banner (intent loaded, record current) before Claude/Codex/etc.`,
+      command: 'phewsh shim on',
+      why: 'phewsh prints the proof itself, so it\'s guaranteed; the real tool always runs. Reversible: `phewsh shim off`.',
+    });
+  }
+
   return out.sort((a, b) => b.priority - a.priority);
 }
 

package/package.json

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