phewsh 0.15.70 → 0.15.72

package/commands/ambient.js

@@ -31,6 +31,10 @@ const HOOK_END = { type: 'command', command: 'phewsh hook session-end' };
 // matcher scopes the hook to the tools the policy actually judges, so it never
 // fires on harmless reads.
 const HOOK_PRETOOL = { type: 'command', command: 'phewsh hook pre-tool' };
+// The receipt half of the lifecycle: after a write-ish tool runs, record a
+// redacted breadcrumb (tool + target, never args/content). Installed and
+// removed together with the pre-tool gate — one toggle, whole lifecycle.
+const HOOK_POSTTOOL = { type: 'command', command: 'phewsh hook post-tool' };
 const PRETOOL_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit|Bash';
 
 // ANSI helpers (256-color per cli/lib/ui.js palette rules)
@@ -111,22 +115,31 @@ function preToolGateApplied() {
 function enablePreToolGate() {
   const settings = loadClaudeSettings() || {};
   settings.hooks = settings.hooks || {};
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
-  if (hasHook(settings, 'PreToolUse', HOOK_PRETOOL.command)) return false;
-  settings.hooks.PreToolUse.push({ matcher: PRETOOL_MATCHER, hooks: [HOOK_PRETOOL] });
-  fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
-  return true;
+  let changed = false;
+  for (const [event, hook] of [['PreToolUse', HOOK_PRETOOL], ['PostToolUse', HOOK_POSTTOOL]]) {
+    settings.hooks[event] = settings.hooks[event] || [];
+    if (hasHook(settings, event, hook.command)) continue;
+    settings.hooks[event].push({ matcher: PRETOOL_MATCHER, hooks: [hook] });
+    changed = true;
+  }
+  if (changed) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  return changed;
 }
 
 function disablePreToolGate() {
   const settings = loadClaudeSettings();
-  if (!settings?.hooks?.PreToolUse) return false;
-  const before = settings.hooks.PreToolUse.length;
-  settings.hooks.PreToolUse = settings.hooks.PreToolUse
-    .map(e => ({ ...e, hooks: (e.hooks || []).filter(h => h.command !== HOOK_PRETOOL.command) }))
-    .filter(e => e.hooks.length > 0);
-  if ((settings.hooks.PreToolUse || []).length === 0) delete settings.hooks.PreToolUse;
-  const changed = before !== (settings.hooks.PreToolUse?.length ?? 0);
+  if (!settings?.hooks) return false;
+  let changed = false;
+  for (const [event, hook] of [['PreToolUse', HOOK_PRETOOL], ['PostToolUse', HOOK_POSTTOOL]]) {
+    const entries = settings.hooks[event];
+    if (!entries) continue;
+    const before = entries.length;
+    settings.hooks[event] = entries
+      .map(e => ({ ...e, hooks: (e.hooks || []).filter(h => h.command !== hook.command) }))
+      .filter(e => e.hooks.length > 0);
+    if ((settings.hooks[event] || []).length === 0) delete settings.hooks[event];
+    if (before !== (settings.hooks[event]?.length ?? 0)) changed = true;
+  }
   if (changed) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
   return changed;
 }

package/commands/clarify.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
-const { readPPS, writePPS, createPPS, generateViews } = require('../lib/pps');
+const { readPPS, createPPS, writeGuardedViews } = require('../lib/pps');
 const configFile = require('../lib/config-file');
 
 const CONFIG_PATH = path.join(os.homedir(), '.phewsh', 'config.json');
@@ -45,35 +45,28 @@ async function askForInput() {
   });
 }
 
-// The guided walk — the five strongest nodes of the web's 12-node Intent
-// Compass, asked one at a time. The web compass helps the user *see* what
-// they're building; this brings that to the terminal. Not a form: every
-// question is skippable, and the point is to help you think, not interrogate.
-const GUIDE_NODES = [
-  { id: 'purpose', title: 'Purpose', directive: 'the core reason this exists',
-    q: 'What outcome are you really after — and why does this need to exist?' },
-  { id: 'audience', title: 'Audience', directive: 'the people this serves',
-    q: 'Who is this for? Who feels it most when it works?' },
-  { id: 'method', title: 'Method', directive: 'the mechanism and approach',
-    q: 'How does it actually work — the core mechanism or approach?' },
-  { id: 'scope', title: 'Scope', directive: 'boundaries, in and out',
-    q: "What's in — and just as important, what's deliberately out, for now?" },
-  { id: 'differentiation', title: 'Edge', directive: 'what makes this yours',
-    q: 'What would be lost if someone else built this instead of you?' },
-];
+// The guided walk — nodes of the 12-node Intent Compass, asked one at a
+// time. Default: the five strongest (CORE_NODES). --deep: all twelve. The
+// web compass helps the user *see* what they're building; this brings that
+// to the terminal. Not a form: every question is skippable, and the point
+// is to help you think, not interrogate.
+const { INTENT_NODES, CORE_NODES } = require('../lib/intent-nodes');
+const GUIDE_NODES = CORE_NODES;
 
 function ask(rl, question) {
   return new Promise((resolve) => rl.question(question, (a) => resolve((a || '').trim())));
 }
 
 // rl is injectable so the walk can be driven deterministically in tests.
-async function askGuided(rl = readline.createInterface({ input: process.stdin, output: process.stdout })) {
-  console.log('\n  Five quick questions to align your own thinking first —');
+// nodes defaults to the five-node core walk; --deep passes all twelve.
+async function askGuided(rl = readline.createInterface({ input: process.stdin, output: process.stdout }), nodes = GUIDE_NODES) {
+  const count = nodes.length === 5 ? 'Five quick questions' : `${nodes.length} questions — the full compass`;
+  console.log(`\n  ${count} to align your own thinking first —`);
   console.log('  a sentence or two each. Blank skips. (esc stops, nothing saved.)\n');
   const answers = [];
-  for (let i = 0; i < GUIDE_NODES.length; i++) {
-    const n = GUIDE_NODES[i];
-    console.log(`  ${i + 1}/${GUIDE_NODES.length}  ${n.title} — ${n.directive}`);
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    console.log(`  ${i + 1}/${nodes.length}  ${n.title} — ${n.directive}`);
     const a = await ask(rl, `  ${n.q}\n  > `);
     if (a) answers.push({ ...n, answer: a });
     console.log('');
@@ -169,13 +162,6 @@ async function callClarifyViaHarness(harnessId, raw, existing) {
   return extractJson(out || '');
 }
 
-function writeViews(intentDir, pps) {
-  const { vision, plan, next } = generateViews(pps);
-  fs.writeFileSync(path.join(intentDir, 'vision.md'), vision);
-  fs.writeFileSync(path.join(intentDir, 'plan.md'), plan);
-  fs.writeFileSync(path.join(intentDir, 'next.md'), next);
-}
-
 async function main() {
   // ESC backs out cleanly at any point — nothing half-written, no error.
   if (process.stdin.isTTY) {
@@ -194,17 +180,19 @@ async function main() {
 
   Usage:
     phewsh clarify                    Guided: a 5-question walk that aligns your thinking, then compiles
+    phewsh clarify --deep             The full 12-node compass, one question at a time
     phewsh clarify --freeform         Free-form: describe it all in one messy blob
     phewsh clarify --text "..."       Inline: pass raw text directly
-    phewsh clarify --update           Refine existing PPS with new input
+    phewsh clarify --update           Refine existing intent with new input
 
   What it does:
-    Walks you through the five strongest nodes of the Intent Compass —
-    Purpose, Audience, Method, Scope, Edge — one question at a time, so the
-    terminal helps you *think*, not just compile. Then turns your answers
-    into a structured project spec (PPS):
-    Writes .intent/pps.json as the source of truth.
-    Generates vision.md, plan.md, next.md as human-readable views.
+    Walks you through the strongest nodes of the 12-node Intent Compass —
+    Purpose, Audience, Method, Scope, Edge (--deep adds Context, Resources,
+    Strategy, Signals, Risks, Values, Impact) — one question at a time, so
+    the terminal helps you *think*, not just compile. Then it writes
+    vision.md, plan.md, next.md — YOUR files, the project truth every AI
+    tool reads. Files you've edited by hand are never overwritten.
+    (.intent/pps.json holds the compiled spec + generation receipts.)
 
   Requires:
     An installed agent CLI (Claude Code, Codex, Gemini…) — phewsh uses its
@@ -249,7 +237,9 @@ async function main() {
       raw = await askForInput();
     } else {
       // Guided is the default interactive path: help the user think first.
-      const answers = await askGuided();
+      // --deep walks the full 12-node compass instead of the strongest five.
+      const deep = args.includes('--deep') || args.includes('-d');
+      const answers = await askGuided(undefined, deep ? INTENT_NODES : GUIDE_NODES);
       raw = assembleRaw(answers);
       if (!raw) {
         // Skipped every question — fall back to a single free-form description.
@@ -310,14 +300,19 @@ async function main() {
     pps.state.phase = 'plan';
   }
 
-  fs.mkdirSync(INTENT_DIR, { recursive: true });
-  writePPS(INTENT_DIR, pps);
-  writeViews(INTENT_DIR, pps);
-
-  console.log(`  ✓ .intent/pps.json       — structured project spec`);
-  console.log(`  ✓ .intent/vision.md      — ${pps.intent.goal}`);
-  console.log(`  ✓ .intent/plan.md        — ${pps.intent.success_criteria.length} outcomes, ${pps.intent.constraints.length} constraints`);
-  console.log(`  ✓ .intent/next.md        — ${pps.tasks.length} actions\n`);
+  // The truth guard: the .md files are user-owned truth. Hand-edited (or
+  // pre-existing hand-authored) files are preserved, never regenerated.
+  const { written, preserved } = writeGuardedViews(INTENT_DIR, pps);
+
+  console.log(`  ✓ .intent/pps.json       — compiled spec (the .md files are the truth)`);
+  const detail = {
+    'vision.md': pps.intent.goal,
+    'plan.md': `${pps.intent.success_criteria.length} outcomes, ${pps.intent.constraints.length} constraints`,
+    'next.md': `${pps.tasks.length} actions`,
+  };
+  for (const f of written) console.log(`  ✓ .intent/${f.padEnd(14)} — ${detail[f]}`);
+  for (const f of preserved) console.log(`  ● .intent/${f.padEnd(14)} — kept as-is (yours — edited by hand, phewsh won't overwrite it)`);
+  console.log('');
   console.log(`  Goal: ${pps.intent.goal}\n`);
   if (pps.tasks.length > 0) {
     console.log('  First actions:');
@@ -338,4 +333,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { run: main, GUIDE_NODES, assembleRaw, askGuided, extractJson };
+module.exports = { run: main, GUIDE_NODES, INTENT_NODES, assembleRaw, askGuided, extractJson };

package/commands/gate.js

@@ -402,21 +402,22 @@ function enforce(action) {
   if (on === 'on' || on === 'enable') {
     const changed = amb.enablePreToolGate();
     console.log(changed
-      ? `\n  ${green('●')} Gate enforcement ${green('ON')} — Claude Code asks/denies on protected-path writes and high-blast-radius commands before they run.\n  ${g('Reversible:')} phewsh gate enforce off\n`
+      ? `\n  ${green('●')} Gate enforcement ${green('ON')} — before a tool runs, Claude Code asks/denies on protected-path writes and high-blast-radius commands; after, a redacted receipt records what ran (tool + target, never content).\n  ${g('Reversible:')} phewsh gate enforce off\n`
       : `\n  Gate enforcement already on.\n`);
     return;
   }
   if (on === 'off' || on === 'disable') {
     const changed = amb.disablePreToolGate();
-    console.log(changed ? `\n  Gate enforcement ${yellow('OFF')} — PreToolUse hook removed.\n` : `\n  Gate enforcement was not on.\n`);
+    console.log(changed ? `\n  Gate enforcement ${yellow('OFF')} — PreToolUse + PostToolUse hooks removed.\n` : `\n  Gate enforcement was not on.\n`);
     return;
   }
   // status
   const applied = amb.preToolGateApplied();
-  console.log(`\n  Gate enforcement: ${applied ? green('ON') : g('off')} ${g('(Claude Code PreToolUse)')}`);
+  console.log(`\n  Gate enforcement: ${applied ? green('ON') : g('off')} ${g('(Claude Code PreToolUse + PostToolUse)')}`);
   console.log(`  ${g('Turn on:')} phewsh gate enforce on   ${g('· off:')} phewsh gate enforce off`);
-  console.log(`  ${g('What it does: deny writes to protected paths (.env, keys, .git/…),')}`);
+  console.log(`  ${g('Before: deny writes to protected paths (.env, keys, .git/…),')}`);
   console.log(`  ${g('ask before high-blast-radius shell (rm -rf, force-push, sudo…).')}`);
+  console.log(`  ${g('After: redacted receipt of what ran — tool + target, never args or content.')}`);
   console.log(`  ${g('Opt-in, local-only, fail-open. Other tools: advisory only for now.')}\n`);
 }
 

package/commands/hook.js

@@ -215,11 +215,41 @@ function preTool() {
   }
 }
 
+// PostToolUse adapter — the other half of the lifecycle. After a write-ish
+// tool runs, leave a redacted receipt (tool name + relative target, or just
+// the binary name for shell — NEVER args, content, or output) so `phewsh`
+// can show what agents actually did here. Always silent to the host, always
+// fail-open: a broken receipt must never slow or break the tool that ran.
+function postTool() {
+  try {
+    if (process.stdin.isTTY) process.exit(0); // not a real hook invocation
+    let raw = '';
+    try { raw = fs.readFileSync(0, 'utf-8'); } catch { process.exit(0); }
+    let payload = {};
+    try { payload = JSON.parse(raw || '{}'); } catch { process.exit(0); }
+    const tool = payload.tool_name || payload.toolName;
+    if (!tool) process.exit(0);
+    const input = payload.tool_input || payload.toolInput || {};
+    const cwd = payload.cwd || process.cwd();
+    let target = null;
+    if (typeof input.file_path === 'string') {
+      target = path.relative(cwd, input.file_path) || input.file_path;
+    } else if (typeof input.command === 'string') {
+      target = String(input.command).trim().split(/\s+/)[0] || null; // binary only, never args
+    }
+    appendBreadcrumb('post-tool', { tool, ...(target ? { target } : {}) });
+    process.exit(0);
+  } catch {
+    process.exit(0); // fail open, always
+  }
+}
+
 function main() {
   const event = process.argv[3];
   if (event === 'session-start') return sessionStart();
   if (event === 'session-end') return sessionEnd();
   if (event === 'pre-tool') return preTool();
+  if (event === 'post-tool') return postTool();
   // Unknown event: exit silently — hooks must never error the host tool.
   process.exit(0);
 }

package/commands/intent.js

@@ -2,7 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
-const { createPPS, writePPS, generateViews } = require('../lib/pps');
+const { createPPS, writeGuardedViews } = require('../lib/pps');
 
 const os = require('os');
 const configFile = require('../lib/config-file');
@@ -136,16 +136,14 @@ async function initIntent() {
     },
   });
 
-  writePPS(INTENT_DIR, pps);
-  const { vision, plan, next } = generateViews(pps);
-  fs.writeFileSync(path.join(INTENT_DIR, 'vision.md'), vision);
-  fs.writeFileSync(path.join(INTENT_DIR, 'plan.md'), plan);
-  fs.writeFileSync(path.join(INTENT_DIR, 'next.md'), next);
+  // Truth guard: never overwrite a hand-authored file (a partial .intent/
+  // slips past hasExistingArtifacts — e.g. vision.md alone).
+  const { written, preserved } = writeGuardedViews(INTENT_DIR, pps);
 
-  console.log(`  ✓ .intent/pps.json     — Structured project spec (source of truth)`);
-  console.log(`  ✓ .intent/vision.md    — The north star`);
-  console.log(`  ✓ .intent/plan.md      — The strategy`);
-  console.log(`  ✓ .intent/next.md      — What to do right now`);
+  console.log(`  ✓ .intent/pps.json     — Compiled spec (the .md files are the truth)`);
+  const label = { 'vision.md': 'The north star', 'plan.md': 'The strategy', 'next.md': 'What to do right now' };
+  for (const f of written) console.log(`  ✓ .intent/${f.padEnd(12)} — ${label[f]}`);
+  for (const f of preserved) console.log(`  ● .intent/${f.padEnd(12)} — kept as-is (yours, hand-authored)`);
   console.log(`
   Tip: Run \`phewsh clarify\` to have AI compile your messy intent into a precise spec.
 

package/commands/session.js

@@ -50,7 +50,7 @@ const {
   relativeFolder,
   shouldCollapsePaste,
 } = require('../lib/session-display');
-const { recordProject, listProjects, scanForProjects, fmtAgo } = require('../lib/projects-index');
+const { recordProject, listProjects, scanForProjects, scanForCandidates, fmtAgo } = require('../lib/projects-index');
 
 // Brand palette shortcuts
 const { b, d, w, g, green, cyan, yellow,
@@ -500,7 +500,7 @@ async function main() {
   } else if (atHome || recents.length > 0) {
     row('PROJECT', slate('none here — your projects are listed below'));
   } else {
-    row('PROJECT', cream(projectName) + slate(' · no memory yet — ') + sage('/init'));
+    row('PROJECT', cream(projectName) + slate(' · no memory yet — ') + sage('/init') + slate(' fast · ') + sage('/clarify') + slate(' guided'));
   }
 
   row('ROUTE', route
@@ -718,7 +718,13 @@ async function main() {
     try { recordProject(dir); } catch { /* best-effort */ }
     bootstrapChoices = null;
     console.log('');
-    console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage(`.intent/ ${intentFiles.length} file${intentFiles.length !== 1 ? 's' : ''} loaded`)} ${slate('· via ' + routeLabel(route, config))}`);
+    if (intentFiles.length === 0) {
+      // A candidate, not yet a project — invite intent, don't fake context.
+      console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage('no .intent/ yet')} ${slate('· via ' + routeLabel(route, config))}`);
+      console.log(`  ${sage('Ground it:')} ${cream('/init')} ${sage('two questions, instant artifacts')} ${slate('·')} ${cream('/clarify')} ${sage('guided — compiles your messy idea into a spec')}`);
+    } else {
+      console.log(`  ${teal('●')} ${cream(projectName)} ${slate('·')} ${sage(`.intent/ ${intentFiles.length} file${intentFiles.length !== 1 ? 's' : ''} loaded`)} ${slate('· via ' + routeLabel(route, config))}`);
+    }
     console.log('');
     maybeHealOnEntry();
     showContinuity();
@@ -1305,17 +1311,31 @@ async function main() {
       if (choice.kind === 'scan') {
         const spin = ui.spinner('scanning your usual folders');
         const found = scanForProjects();
+        // Likely candidates: real repos with no .intent/ yet — the projects
+        // most worth grounding. Same shallow scan; shown with their reason.
+        let candidates = [];
+        try { candidates = scanForCandidates(); } catch { /* advisory — scan still useful without it */ }
         spin.stop();
-        if (found.length === 0) {
+        if (found.length === 0 && candidates.length === 0) {
           bootstrapChoices = null;
           console.log(`  ${sage('No .intent/ projects found in the usual folders.')}`);
           console.log(`  ${slate('cd into a project and run phewsh, or /init to start one here.')}`);
         } else {
-          console.log(`  ${teal('●')} ${sage(`Found ${found.length} project${found.length !== 1 ? 's' : ''}:`)}`);
-          bootstrapChoices = found.map(p => ({ kind: 'open', path: p.path }));
-          found.forEach((p, i) => {
-            console.log(`  ${teal(String(i + 1))} ${cream(p.name)} ${slate('· ' + tildify(p.path))}`);
-          });
+          bootstrapChoices = [];
+          if (found.length > 0) {
+            console.log(`  ${teal('●')} ${sage(`Found ${found.length} project${found.length !== 1 ? 's' : ''} with .intent/:`)}`);
+            for (const p of found) {
+              bootstrapChoices.push({ kind: 'open', path: p.path });
+              console.log(`  ${teal(String(bootstrapChoices.length))} ${cream(p.name)} ${slate('· ' + tildify(p.path))}`);
+            }
+          }
+          if (candidates.length > 0) {
+            console.log(`  ${teal('●')} ${sage(`${candidates.length} likely candidate${candidates.length !== 1 ? 's' : ''} — no shared memory yet:`)}`);
+            for (const p of candidates) {
+              bootstrapChoices.push({ kind: 'open', path: p.path });
+              console.log(`  ${teal(String(bootstrapChoices.length))} ${cream(p.name)} ${slate('· ' + tildify(p.path) + ' · ' + p.reason)}`);
+            }
+          }
           console.log(`  ${slate('pick a number to open it')}`);
         }
         console.log('');

package/commands/task.js

@@ -123,11 +123,41 @@ function runnerArgs(harnessId, prompt) {
   return HARNESSES[harnessId].args(prompt);
 }
 
+async function memberNames(config, projectId) {
+  try {
+    const rows = await supa.rpc('project_member_names', { pid: projectId }, config.supabaseAccessToken);
+    const m = {};
+    for (const r of rows || []) m[r.user_id] = r.display_name;
+    return m;
+  } catch { return {}; }
+}
+
+// Close the loop from verified GitHub state: any listed task whose PR has
+// actually merged gets recorded as merged (best-effort, never blocks the list).
+function syncMergedFromGitHub(config, rows) {
+  const candidates = rows.filter((t) => ['pr_open', 'approved'].includes(t.status) && t.pull_request_url);
+  const updated = [];
+  for (const t of candidates) {
+    try {
+      const out = execFileSync('gh', ['pr', 'view', t.pull_request_url, '--json', 'state'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+      if (JSON.parse(out).state === 'MERGED') updated.push(t);
+    } catch { /* gh missing or PR unreachable — leave as-is */ }
+  }
+  return Promise.all(updated.map((t) =>
+    supa.rpc('mark_merged', { p_task_id: t.id, p_metadata: { via: 'gh pr view' } }, config.supabaseAccessToken)
+      .then(() => { t.status = 'merged'; })
+      .catch(() => {})
+  ));
+}
+
 async function listTasks(config) {
   const project = await loadProject(config);
   const rows = await supa.select('tasks',
-    `project_id=eq.${project.id}&select=id,title,status,claimed_by,pull_request_url,created_at&order=created_at.desc&limit=20`,
+    `project_id=eq.${project.id}&select=id,title,status,claimed_by,assigned_to,suggested_harness,pull_request_url,created_at&order=created_at.desc&limit=20`,
     config.supabaseAccessToken);
+  await syncMergedFromGitHub(config, rows);
+  const names = await memberNames(config, project.id);
+  const nameOf = (id) => id === config.supabaseUserId ? 'you' : (names[id] || 'a teammate');
   console.log(`\n  ${b(w(project.name))} ${g('— shared tasks')}\n`);
   if (!rows.length) {
     console.log(`  ${g('No tasks yet.')} ${w('phewsh task new "<title>"')} ${g('to request one.')}\n`);
@@ -135,13 +165,40 @@ async function listTasks(config) {
   }
   for (const t of rows) {
     const color = STATUS_COLOR[t.status] || w;
-    const mine = t.claimed_by === config.supabaseUserId ? g(' · claimed by you') : '';
-    console.log(`  ${color('●')} ${w(t.title)}  ${g(t.id.slice(0, 8))} ${color(t.status)}${mine}`);
+    const bits = [];
+    if (t.claimed_by) bits.push(`claimed by ${nameOf(t.claimed_by)}`);
+    else if (t.assigned_to) bits.push(`assigned to ${nameOf(t.assigned_to)}`);
+    if (t.suggested_harness && !t.claimed_by) bits.push(`suggests ${HARNESSES[t.suggested_harness]?.label || t.suggested_harness}`);
+    console.log(`  ${color('●')} ${w(t.title)}  ${g(t.id.slice(0, 8))} ${color(t.status)}${bits.length ? g(' · ' + bits.join(' · ')) : ''}`);
     if (t.pull_request_url) console.log(`      ${cyan(t.pull_request_url)}`);
+    if (t.status === 'merged') console.log(`      ${g('merged — record it:')} ${w(`phewsh task reconcile ${t.id.slice(0, 8)}`)}`);
   }
   console.log(`\n  ${g('Claim one:')} ${w('phewsh task claim <id>')}\n`);
 }
 
+// Promote a merged task into the repo's durable Record (.intent/decisions.md)
+// and mark it reconciled — the last beat of the loop.
+async function reconcileTask(config, idArg) {
+  if (!idArg) throw new Error('Usage: phewsh task reconcile <task-id>');
+  const project = await loadProject(config);
+  const rows = await supa.select('tasks', `project_id=eq.${project.id}&id=like.${idArg}*&select=*`, config.supabaseAccessToken);
+  const task = rows[0];
+  if (!task) throw new Error(`Task ${idArg} not found in this project.`);
+  if (task.status !== 'merged') {
+    await syncMergedFromGitHub(config, [task]);
+    if (task.status !== 'merged') throw new Error(`Task is ${task.status} — only merged tasks can be reconciled.`);
+  }
+  const names = await memberNames(config, project.id);
+  const nameOf = (id) => names[id] || 'a teammate';
+  const decisionsPath = path.join(process.cwd(), '.intent', 'decisions.md');
+  const line = `- ${new Date().toISOString().slice(0, 10)} — Shared task "${task.title}" (${task.id.slice(0, 8)}) merged and recorded: requested by ${nameOf(task.created_by)}, executed by ${nameOf(task.claimed_by)}, reviewed on GitHub. PR: ${task.pull_request_url || 'n/a'}\n`;
+  if (fs.existsSync(decisionsPath)) fs.appendFileSync(decisionsPath, line);
+  else console.log(`  ${g('(no .intent/decisions.md here — recording in the cloud only)')}`);
+  await supa.rpc('mark_reconciled', { p_task_id: task.id }, config.supabaseAccessToken);
+  console.log(`\n  ${green('✓')} Recorded into project truth: ${w(task.title)}`);
+  if (fs.existsSync(decisionsPath)) console.log(`  ${g('Appended to .intent/decisions.md — commit it with your normal flow.')}\n`);
+}
+
 async function inviteTeammate(config, email) {
   if (!email || !email.includes('@')) throw new Error('Usage: phewsh task invite <email>');
   const project = await loadProject(config);
@@ -296,6 +353,7 @@ module.exports = async function run() {
     if (sub === 'claim') return await claimTask(config, rest[0], via);
     if (sub === 'invite') return await inviteTeammate(config, rest[0]);
     if (sub === 'join') return await joinProjects(config);
+    if (sub === 'reconcile') return await reconcileTask(config, rest[0]);
     console.log(`\n  Usage: phewsh task [list | new "<title>" | claim <id> [--via <harness>] | invite <email> | join]\n         phewsh dispatch ["<title>" | <id> | next] [--via <harness>]\n`);
   } catch (err) {
     console.error(`\n  ${red('✗')} ${err.message}\n`);

package/lib/intent-nodes.js

@@ -0,0 +1,38 @@
+// The 12-node Intent Compass — the CLI's canonical copy of the model the web
+// compass renders (intent/app/src/lib/intent-analysis.ts). One definition,
+// two surfaces: the web helps you SEE your intent; the terminal helps you
+// SAY it. Ordered as a ladder — the first five are the strongest nodes and
+// form the default clarify walk; --deep continues through all twelve.
+
+const INTENT_NODES = [
+  { id: 'purpose', title: 'Purpose', directive: 'the core reason this exists',
+    q: 'What outcome are you really after — and why does this need to exist?' },
+  { id: 'audience', title: 'Audience', directive: 'the people this serves',
+    q: 'Who is this for? Who feels it most when it works?' },
+  { id: 'method', title: 'Method', directive: 'the mechanism and approach',
+    q: 'How does it actually work — the core mechanism or approach?' },
+  { id: 'scope', title: 'Scope', directive: 'boundaries, in and out',
+    q: "What's in — and just as important, what's deliberately out, for now?" },
+  { id: 'differentiation', title: 'Edge', directive: 'what makes this yours',
+    q: 'What would be lost if someone else built this instead of you?' },
+  // ── the deep walk continues here (--deep) ──
+  { id: 'context', title: 'Context', directive: 'the situation that led here',
+    q: "What's happening right now that makes this relevant — what led to it?" },
+  { id: 'resources', title: 'Resources', directive: 'time, money, energy, tools',
+    q: 'What does this require — time, money, energy, tools you already have?' },
+  { id: 'strategy', title: 'Strategy', directive: 'the roadmap and sequence',
+    q: 'How do you get from here to success — what happens first, second, third?' },
+  { id: 'signals', title: 'Signals', directive: 'metrics, validation, feedback',
+    q: 'How will you know this is working — what would you actually measure?' },
+  { id: 'risks', title: 'Risks', directive: 'threats, unknowns, failure modes',
+    q: "What could go wrong — what's the biggest unknown or exposure?" },
+  { id: 'values', title: 'Values', directive: 'ethics, trust, non-negotiables',
+    q: 'What do you refuse to compromise on, even under pressure?' },
+  { id: 'impact', title: 'Impact', directive: 'long-term effects and sustainability',
+    q: 'If this fully succeeds, what changes — and how does it sustain itself?' },
+];
+
+// The five strongest nodes — the default clarify walk.
+const CORE_NODES = INTENT_NODES.slice(0, 5);
+
+module.exports = { INTENT_NODES, CORE_NODES };

package/lib/intro.js

@@ -57,6 +57,8 @@ async function playIntro(opts = {}) {
     delay = sleep,
     out = console.log,
     listHarnesses = require('./harnesses').listHarnesses,
+    scanProjects = require('./projects-index').scanForProjects,
+    scanCandidates = require('./projects-index').scanForCandidates,
   } = opts;
 
   const { b, cream, sage, slate, teal, green } = ui;
@@ -93,6 +95,24 @@ async function playIntro(opts = {}) {
   }
   out('');
   await pause(160);
+
+  // Second beat: the tools share memory *per project* — so show the projects.
+  // Shallow scan of the usual folders only (same rules as /scan): existing
+  // .intent/ projects, plus likely candidates (git repos with no .intent yet).
+  let projects = [];
+  let candidates = [];
+  try { projects = scanProjects(); } catch { /* none */ }
+  try { candidates = scanCandidates(); } catch { /* none */ }
+  if (projects.length > 0 || candidates.length > 0) {
+    const bits = [];
+    if (projects.length > 0) bits.push(`${projects.length} project${projects.length !== 1 ? 's' : ''} already share memory (.intent/)`);
+    if (candidates.length > 0) bits.push(`${candidates.length} likely candidate${candidates.length !== 1 ? 's' : ''} (git, no .intent yet)`);
+    out(`  ${teal('●')} ${sage(bits.join(' · '))}`);
+    out(`  ${slate('run phewsh inside one — or pick from the list when the session opens.')}`);
+    out('');
+    await pause(160);
+  }
+
   if (harnesses.length > 0) {
     out(`  ${sage('Next:')} ${cream('just type to start')} ${slate('·')} ${cream('phewsh setup')} ${slate('to pick a default route')}`);
   } else {
@@ -100,7 +120,7 @@ async function playIntro(opts = {}) {
   }
   out('');
 
-  return { toolsFound: harnesses.length };
+  return { toolsFound: harnesses.length, projectsFound: projects.length, candidatesFound: candidates.length };
 }
 
 // Quiet sign-off — the shush mark, printed static (no animation; exit is instant).

package/lib/pps.js

@@ -1,5 +1,10 @@
-// PPS — Portable Project Spec
-// pps.json is the source of truth. .md files are generated views.
+// PPS — Portable Project Spec compiler.
+//
+// TRUTH RULING (decisions.md, Jul 5 2026): the .md files ARE the project
+// truth — user-owned, hand-editable, what every tool reads. pps.json is the
+// compiler's receipt: structured output from clarify/init plus the hashes of
+// what it generated, so regeneration can tell machine-owned files from
+// hand-authored ones. phewsh never overwrites a file the human has edited.
 
 const fs = require('fs');
 const path = require('path');
@@ -63,6 +68,10 @@ function createPPS({ entity, archetype = 'product', raw = '', intent = {} }) {
   };
 }
 
+// One line of provenance in every generated file — the user must never
+// mistake compiled output for something they wrote (or vice versa).
+const PROVENANCE = 'provenance: compiled by phewsh clarify — yours to edit; phewsh never regenerates a file you have edited';
+
 function generateViews(pps) {
   const { entity, intent, tasks, created, updated, archetype } = pps;
 
@@ -71,6 +80,7 @@ entity: ${entity}
 archetype: ${archetype}
 created: ${created}
 updated: ${updated}
+${PROVENANCE}
 ---
 
 # Vision
@@ -97,6 +107,7 @@ entity: ${entity}
 archetype: ${archetype}
 created: ${created}
 updated: ${updated}
+${PROVENANCE}
 ---
 
 # Plan
@@ -131,6 +142,7 @@ entity: ${entity}
 archetype: ${archetype}
 created: ${created}
 updated: ${updated}
+${PROVENANCE}
 ---
 
 # Next
@@ -155,4 +167,37 @@ ${tasks.length > 0
   return { vision, plan, next };
 }
 
-module.exports = { readPPS, writePPS, createPPS, generateViews, genId };
+function hashContent(s) {
+  return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+
+// The truth guard. Writes generated views, but a file is only machine-owned
+// while its on-disk content still matches the hash recorded when we generated
+// it. Hand-edited since then — or existing before we ever generated it (a
+// hand-authored .intent/, like phewsh's own) — means it IS the truth now:
+// preserve it, never overwrite. Records fresh hashes in pps.generated and
+// persists pps.json. Returns { written, preserved }.
+function writeGuardedViews(intentDir, pps) {
+  fs.mkdirSync(intentDir, { recursive: true });
+  const views = generateViews(pps);
+  const prior = (pps.generated && pps.generated.hashes) || {};
+  const written = [];
+  const preserved = [];
+  pps.generated = { ...(pps.generated || {}), hashes: { ...prior } };
+  for (const [key, file] of [['vision', 'vision.md'], ['plan', 'plan.md'], ['next', 'next.md']]) {
+    const fp = path.join(intentDir, file);
+    let current = null;
+    try { current = fs.readFileSync(fp, 'utf-8'); } catch { /* absent → ours to write */ }
+    if (current !== null && (!prior[file] || hashContent(current) !== prior[file])) {
+      preserved.push(file);
+      continue;
+    }
+    fs.writeFileSync(fp, views[key]);
+    pps.generated.hashes[file] = hashContent(views[key]);
+    written.push(file);
+  }
+  writePPS(intentDir, pps);
+  return { written, preserved };
+}
+
+module.exports = { readPPS, writePPS, createPPS, generateViews, writeGuardedViews, genId };

package/lib/projects-index.js

@@ -64,10 +64,10 @@ function listProjects() {
 }
 
 /** Shallow scan: direct children of common roots that contain .intent/. */
-function scanForProjects() {
+function scanForProjects(roots = SCAN_ROOTS) {
   const found = [];
   const seen = new Set(); // realpath-dedupe — case-insensitive FS makes ~/Projects and ~/projects one dir
-  for (const root of SCAN_ROOTS) {
+  for (const root of roots) {
     let entries;
     try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { continue; }
     for (const e of entries) {
@@ -86,6 +86,34 @@ function scanForProjects() {
   return found;
 }
 
+// Likely candidates: real projects (a .git repo is the conservative signal)
+// that don't have .intent/ yet. Same shallow, opt-in scan as scanForProjects —
+// one level deep in the usual folders, never recursive, never dotfiles read.
+// Each hit carries its `reason` so the user sees WHY it was suggested.
+const CANDIDATE_CAP = 15;
+function scanForCandidates(roots = SCAN_ROOTS) {
+  const found = [];
+  const seen = new Set();
+  for (const root of roots) {
+    let entries;
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.name.startsWith('.')) continue;
+      const dir = path.join(root, e.name);
+      try {
+        if (!fs.existsSync(path.join(dir, '.git'))) continue;
+        if (fs.existsSync(path.join(dir, '.intent'))) continue; // already phewsh-enabled (or partially)
+        const real = fs.realpathSync(dir);
+        if (seen.has(real)) continue;
+        seen.add(real);
+        found.push({ name: e.name, path: real, reason: 'git repo, no .intent/ yet' });
+        if (found.length >= CANDIDATE_CAP) return found;
+      } catch { /* unreadable dir — skip */ }
+    }
+  }
+  return found;
+}
+
 function fmtAgo(ts) {
   if (!ts) return '';
   const mins = Math.floor((Date.now() - new Date(ts).getTime()) / 60000);
@@ -95,4 +123,4 @@ function fmtAgo(ts) {
   return `${Math.floor(hrs / 24)}d ago`;
 }
 
-module.exports = { INDEX_FILE, SCAN_ROOTS, recordProject, listProjects, scanForProjects, fmtAgo };
+module.exports = { INDEX_FILE, SCAN_ROOTS, recordProject, listProjects, scanForProjects, scanForCandidates, fmtAgo };

package/package.json

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