phewsh 0.15.63 → 0.15.65

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 phewsh (hello@phewsh.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,9 +5,24 @@ Turn intent into action. Structure your thinking, execute your next step.
 ## Install
 
 ```bash
-npm install -g phewsh
+curl -fsSL https://phewsh.com/install.sh | sh
 ```
 
+No sudo, nvm-aware. (Prefer a package manager? `npm install -g phewsh` —
+same artifact, built from this repo.)
+
+Then let it improve the AI tools you already have — without launching anything:
+
+```bash
+phewsh ambient on    # your .intent/ + a verified brief reach Claude Code, Codex,
+                     # Gemini, Cursor at the start of every session (reversible)
+```
+
+phewsh isn't just a CLI — `ambient` makes every supported tool start aligned to
+what you're building. What it reads, writes, and sends is documented, factually,
+in [SECURITY.md](./SECURITY.md). It's local-first and MIT; this repo is an exact
+mirror of the published npm package.
+
 ## Quick Start
 
 ```bash

package/SECURITY.md

@@ -0,0 +1,97 @@
+# Security & Data Flow — phewsh CLI
+
+phewsh is a **local-first** tool. It runs on your machine, reads your project's
+`.intent/` and your installed AI tools' config, and helps you carry context
+between those tools. This document states — factually, traceable to source —
+what it reads, writes, and sends. No vague claims; if something here is wrong,
+it's a bug: **hello@phewsh.com**.
+
+> Status: this is an honest self-documented inventory, **not** an independent
+> audit. The CLI source is **public and MIT-licensed** at
+> **github.com/cleverIdeaz/phewsh-cli** — an exact mirror of the published npm
+> package, so you can read exactly what you install (`bin/ commands/ lib/ mcp/`).
+> An independent review is still planned (see "Roadmap").
+
+## What phewsh reads
+- **`.intent/`** in your project (`vision.md`, `plan.md`, `status.md`, `next.md`,
+  `project.json`, `next.json`). This is the source of truth it projects.
+- **Your tools' context files** when present: `CLAUDE.md`, `AGENTS.md`,
+  `GEMINI.md`, `.cursorrules`, `.github/copilot-instructions.md`, `README.md`.
+- **Your Claude project memory** (`~/.claude/projects/<cwd>/memory/MEMORY.md` and
+  files it links) and **global per-user memory** (`~/.claude/CLAUDE.md`,
+  `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md`) — read-only, used to enrich the
+  `phewsh seq` summary. Global memory is **never** written into a project file
+  unless you pass `--include-global` (`lib/sequencer/index.js`).
+- **Git status** of the current repo (read-only: `git status`, HEAD, diff stats).
+
+## What phewsh writes (and where)
+Every generated block is wrapped in `<!-- PHEWSH:START -->` / `<!-- PHEWSH:END -->`
+markers; **content outside the markers is preserved byte-for-byte** (tested).
+- **Project context files** — the canonical `.intent/` projection into
+  `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.cursorrules` (only files that
+  already exist, unless you create them). One canonical projector
+  (`lib/selfheal.js`) is the single writer.
+- **`~/.phewsh/`** — `config.json` (your settings/keys, mode **0600**, dir 0700),
+  `briefs/` (saved handoff briefs), `sessions/`, `receipts/`, ledger files.
+- **Shell rc** — only if you run `phewsh shim on` (adds one PATH line; reversible
+  with `phewsh shim off`).
+- **Global base files** — only if you run `phewsh ambient on`: a marker-wrapped
+  block in `~/.claude/CLAUDE.md` etc. for tools you already have. Reversible with
+  `phewsh ambient off`.
+- **Claude Code hook** — `phewsh ambient on` registers `SessionStart`/`SessionEnd`
+  hooks (context injection + a metadata breadcrumb; **never your transcript**).
+
+## Network calls (exactly these)
+phewsh makes **no network calls for its core local features** (sequencing,
+projection, briefs, status). Calls happen only for these named actions:
+- **`api.anthropic.com` / `openrouter.ai` / `api.together.xyz`** — only if you set
+  a BYOK key and use `/run` or the API route. Your key goes **directly** to the
+  provider; it is **not** proxied through phewsh servers.
+- **`registry.npmjs.org`** — version check for `phewsh update` (notify-only by
+  default).
+- **`<project>.supabase.co`** — only if you `/login`: auth + optional cloud sync
+  of your `.intent/` (you initiate `push`/`pull`).
+- **`phewsh.com`** — only for `phewsh serve`/cloud-bridge actions you start.
+- **Sustainability telemetry** (`trackSap`, `lib/supabase.js`) — sends **model
+  name, token counts, and a kWh estimate only**. No prompts, no responses, no
+  file contents. Tied to your account id only when logged in.
+
+## Credentials
+- A bring-your-own key lives in `~/.phewsh/config.json` at mode **0600**
+  (`lib/config-file.js`) and is sent **directly to the provider**, never to us.
+- phewsh routes through your installed tools on **their own login** (your Claude
+  subscription, your ChatGPT plan) — it does not see or store those credentials.
+
+## The local bridge
+`phewsh serve` binds **`127.0.0.1` only** (loopback), with an origin allowlist,
+and runs only while you run it.
+
+## Known issues / hardening backlog (honest)
+- **Local shell-injection surface (medium, local-only):** a few call sites build
+  shell strings from REPL input via `execSync` (e.g. `commands/session.js` gate /
+  outcomes arg passthrough). Inputs are your own typed/pasted text on your own
+  machine, but crafted args could execute. Fix: convert to argument-safe
+  `execFileSync`/`spawnSync`. Tracked as a Next item.
+- **No release provenance yet** — npm provenance, signed tags, and a public
+  source repo are planned (Roadmap) so the published artifact is verifiable.
+
+## Disable / uninstall
+- `phewsh ambient off` — removes injected hooks and global base files; restores
+  your files.
+- `phewsh shim off` — removes the PATH line.
+- `npm uninstall -g phewsh` — removes the CLI. `rm -rf ~/.phewsh` removes local
+  state. Generated `PHEWSH:START/END` blocks can be deleted by hand; everything
+  outside them is yours and untouched.
+
+## Roadmap to verifiable trust
+Done: this doc, exec hardening, telemetry stays counts-only and explicit, and a
+**public MIT source repo** (`cleverIdeaz/phewsh-cli`) mirroring the npm package.
+Before broad promotion: npm provenance, signed tags, and dependency/secret
+scanning so the published artifact is cryptographically verifiable from the
+public source. For enterprise: a documented threat model and an independent
+security assessment. We will not call phewsh "audited" until an independent
+audit has actually occurred.
+
+## Reporting
+Security issues: **hello@phewsh.com**. Please allow reasonable time to remediate
+before public disclosure.

package/commands/ambient.js

@@ -27,6 +27,11 @@ const CLAUDE_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
 
 const HOOK_START = { type: 'command', command: 'phewsh hook session-start' };
 const HOOK_END = { type: 'command', command: 'phewsh hook session-end' };
+// Opt-in Decision Gate enforcement (separate from ambient context sync). The
+// 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' };
+const PRETOOL_MATCHER = 'Write|Edit|MultiEdit|NotebookEdit|Bash';
 
 // ANSI helpers (256-color per cli/lib/ui.js palette rules)
 const b = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -97,6 +102,35 @@ function removeClaudeHooks() {
   return removed;
 }
 
+// ── Decision Gate enforcement (PreToolUse) — opt-in, reversible ──────────────
+function preToolGateApplied() {
+  const s = loadClaudeSettings();
+  return !!s && hasHook(s, 'PreToolUse', HOOK_PRETOOL.command);
+}
+
+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;
+}
+
+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 (changed) fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
+  return changed;
+}
+
 function showConsentScreen(harnesses) {
   console.log('');
   console.log(`  ${b(cream('PHEWSH ambient'))} ${sage('— continuity without launching phewsh')}`);
@@ -365,3 +399,6 @@ async function main() {
 
 module.exports = main;
 module.exports.ensureAuto = ensureAuto;
+module.exports.enablePreToolGate = enablePreToolGate;
+module.exports.disablePreToolGate = disablePreToolGate;
+module.exports.preToolGateApplied = preToolGateApplied;

package/commands/gate.js

@@ -373,6 +373,7 @@ async function main() {
   if (subcommand === 'update' || subcommand === 'edit') { await update(); return; }
   if (subcommand === 'pause') { pause(); return; }
   if (subcommand === 'resume') { resume(); return; }
+  if (subcommand === 'enforce') { enforce(args[1]); return; }
   if (subcommand === 'reset') {
     let removed = false;
     const project = loadProjectJson();
@@ -391,6 +392,34 @@ async function main() {
   console.log(`\n  Unknown: ${subcommand}. Run \`phewsh gate --help\`.\n`);
 }
 
+// Opt-in deterministic enforcement: register/unregister the Claude Code
+// PreToolUse hook that makes the Decision Gate act BEFORE a tool runs. Reversible,
+// Claude-Code-only for now (it's the one provider with a real veto hook).
+function enforce(action) {
+  let amb;
+  try { amb = require('./ambient'); } catch { console.log('\n  Enforcement unavailable.\n'); return; }
+  const on = (action || 'status').toLowerCase();
+  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  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`);
+    return;
+  }
+  // status
+  const applied = amb.preToolGateApplied();
+  console.log(`\n  Gate enforcement: ${applied ? green('ON') : g('off')} ${g('(Claude Code PreToolUse)')}`);
+  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('ask before high-blast-radius shell (rm -rf, force-push, sudo…).')}`);
+  console.log(`  ${g('Opt-in, local-only, fail-open. Other tools: advisory only for now.')}\n`);
+}
+
 module.exports = main;
 
 main().catch(err => {

package/commands/hook.js

@@ -163,10 +163,63 @@ function sessionEnd() {
   setTimeout(() => { appendBreadcrumb('session-end'); process.exit(0); }, 1500);
 }
 
+// Load the Decision Gate context (constraints + protected files) for the project
+// being worked in. Best-effort: missing/garbled → empty context (gate allows).
+function loadGateContext(cwd) {
+  try {
+    const pj = JSON.parse(fs.readFileSync(path.join(cwd, '.intent', 'project.json'), 'utf-8'));
+    const dg = pj.decisionGate || {};
+    return {
+      constraints: dg.constraints || {},
+      protectedFiles: dg.protectedFiles || pj.protectedFiles || [],
+    };
+  } catch { return { constraints: {}, protectedFiles: [] }; }
+}
+
+// PreToolUse adapter — the Decision Gate acting BEFORE a tool runs. Reads Claude
+// Code's PreToolUse JSON from stdin, evaluates against the project's constraints
+// + protected files, and emits a permission decision. FAIL-SAFE: any error, no
+// stdin, or no policy hit → exit 0 (allow). A broken gate must never trap you.
+// It logs only a redacted decision line (never the tool payload).
+function preTool() {
+  try {
+    if (process.stdin.isTTY) process.exit(0); // not a real hook invocation
+    const { evaluateAction, auditLine } = require('../lib/gate-policy');
+    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 cwd = payload.cwd || process.cwd();
+    const envelope = {
+      toolName: payload.tool_name || payload.toolName,
+      toolInput: payload.tool_input || payload.toolInput || {},
+      ...loadGateContext(cwd),
+    };
+    let result = { decision: 'allow', reason: '' };
+    try { result = evaluateAction(envelope); } catch { process.exit(0); }
+
+    if (result.decision !== 'allow') {
+      try { appendBreadcrumb('pre-tool', { decision: result.decision, action: auditLine(envelope, result) }); } catch { /* audit is best-effort */ }
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: result.decision, // 'deny' | 'ask'
+          permissionDecisionReason: result.reason,
+        },
+      }));
+    }
+    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();
   // Unknown event: exit silently — hooks must never error the host tool.
   process.exit(0);
 }

package/commands/mbhd.js

@@ -1,16 +1,17 @@
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
 const WEB_URL = 'https://phewsh.com/mbhd';
 
 console.log(`\n  🎵 Opening MBHD Music Engine...\n`);
 
 try {
+  // execFileSync (no shell) — argument-safe even though the URL is constant.
   if (process.platform === 'darwin') {
-    execSync(`open "${WEB_URL}"`);
+    execFileSync('open', [WEB_URL]);
   } else if (process.platform === 'win32') {
-    execSync(`start "${WEB_URL}"`);
+    execFileSync('cmd', ['/c', 'start', '', WEB_URL]);
   } else {
-    execSync(`xdg-open "${WEB_URL}"`);
+    execFileSync('xdg-open', [WEB_URL]);
   }
 } catch {
   console.log(`  Could not open browser. Visit: ${WEB_URL}\n`);

package/commands/mcp.js

@@ -48,7 +48,7 @@ function loadLocalProject() {
     decisionGate: null,
   };
 
-  const files = ['vision.md', 'plan.md', 'next.md', 'status.md', 'narrative.md'];
+  const files = ['vision.md', 'plan.md', 'next.md', 'status.md'];
   for (const file of files) {
     const filePath = path.join(INTENT_DIR, file);
     if (fs.existsSync(filePath)) {

package/commands/sequence.js

@@ -117,6 +117,20 @@ async function main() {
   // Default behavior: no target = stdout summary
   const target = flags.target || 'stdout';
 
+  // CANONICAL WRITE. Writing a native projection (e.g. `phewsh seq claude -w`)
+  // goes through the one canonical projector (self-heal), NOT the broad
+  // sequencer — identical block, identical source policy, no stale clobber.
+  if (flags.write && target === 'claude-md') {
+    const selfheal = require('../lib/selfheal');
+    const res = selfheal.syncContextFiles({ targets: ['CLAUDE.md'], createMissing: true });
+    if (res.synced && res.synced.length) {
+      console.log(`\n  ${green('✓')} ${sage('CLAUDE.md — canonical .intent/ projection (same block self-heal & watch write)')}\n`);
+    } else {
+      console.log(`\n  ${slate('CLAUDE.md already current' + (res.reason ? ' (' + res.reason + ')' : ''))}\n`);
+    }
+    return;
+  }
+
   try {
     const result = sequence({
       target,

package/commands/session.js

@@ -1714,7 +1714,6 @@ async function main() {
         console.log(`    ${teal('/key')}         ${sage('Set API key (optional — harnesses need none)')}`);
         console.log(`    ${teal('/login')}       ${sage('Identity + cloud sync')}`);
         console.log(`    ${teal('/model')} ${slate('<name>')} ${sage('Switch model — passed through, the provider validates')}`);
-        console.log(`    ${teal('/width')} ${slate('[n]')}   ${sage('Fix mid-word wrapping if your terminal misreports its size')}`);
         console.log(`    ${teal('/update')}      ${sage('Update phewsh')}`);
         console.log(`    ${teal('/tour')}        ${sage('Quick walkthrough')}`);
         console.log('');
@@ -1927,9 +1926,11 @@ async function main() {
 
       if (cmd === 'gate') {
         try {
-          const { execSync } = require('child_process');
-          const gateArg = cmdArg || 'status';
-          execSync(`node ${path.join(__dirname, 'gate.js')} ${gateArg}`, { stdio: 'inherit' });
+          // execFileSync with an argv array — no shell, so REPL input can never
+          // be interpreted as shell metacharacters (hardening: was execSync).
+          const { execFileSync } = require('child_process');
+          const gateArgs = (cmdArg || 'status').split(/\s+/).filter(Boolean);
+          execFileSync(process.execPath, [path.join(__dirname, 'gate.js'), ...gateArgs], { stdio: 'inherit' });
           intentFiles = loadIntentContext();
           systemPrompt = buildSystemPrompt(intentFiles);
         } catch (err) {
@@ -1942,17 +1943,43 @@ async function main() {
       if (cmd === 'seq' || cmd === 'sequence') {
         try {
           const { sequence } = require('../lib/sequencer');
+          const { resolveProjectRoot, discover } = require('../lib/sequencer/discover');
           const target = cmdArg?.split(/\s+/)[0];
           const explain = cmdArg?.includes('explain') || cmdArg?.includes('-e');
-          const write = cmdArg?.includes('-w') || cmdArg?.includes('write');
 
           if (target === 'claude' || target === 'claude-md') {
-            const result = sequence({ target: 'claude-md', write: true });
-            if (result.writeResult) {
-              console.log(`\n  ${teal('●')} ${sage('CLAUDE.md ' + result.writeResult)} ${slate('(' + result.chunks.length + ' chunks)')}\n`);
+            // CANONICAL WRITE. /seq claude writes the SAME deterministic block as
+            // self-heal and watch — one source policy (.intent canonical), one
+            // renderer — so a manual sequence can never produce a divergent or
+            // stale CLAUDE.md. (Previously this called the broad sequencer, which
+            // ingested narrative.md + memory logs and clobbered the canonical block.)
+            const res = selfheal.syncContextFiles({ targets: ['CLAUDE.md'], createMissing: true });
+            if (res.synced && res.synced.length) {
+              console.log(`\n  ${teal('●')} ${sage('CLAUDE.md updated — canonical .intent/ projection')} ${slate('(same block self-heal & watch write)')}\n`);
+            } else {
+              console.log(`\n  ${slate('CLAUDE.md already current' + (res.reason ? ' (' + res.reason + ')' : ''))}\n`);
+            }
+          } else if (explain || target === 'sources' || target === 'root') {
+            // Diagnostic: show what the sequencer sees — resolved root, selected
+            // sources (with scope), and the canonical projection's restricted set.
+            const root = resolveProjectRoot(process.cwd());
+            const found = discover(process.cwd());
+            console.log('');
+            console.log(`  ${b(cream('Sequence diagnostics'))}`);
+            ui.divider('line');
+            console.log(`  ${sage('resolved root')}  ${cream(root)}${root !== process.cwd() ? slate(' (walked up from ' + process.cwd() + ')') : ''}`);
+            console.log(`  ${sage('canonical write set')}  ${slate('vision.md · project.json · status.md · next.md · next.json')}`);
+            console.log(`  ${sage('broad read (this preview)')}`);
+            for (const s of found) {
+              const tag = s.scope === 'global' ? slate('global ') : sage('project');
+              const canon = ['vision.md','project.json','status.md','next.md','next.json'].includes(s.name) ? teal(' ✓ canonical') : slate(' · preview-only');
+              console.log(`    ${tag} ${cream(s.name.padEnd(20))}${canon}`);
             }
+            ui.divider('line');
+            console.log(`  ${slate('write the canonical projection with')} ${cream('/seq claude')}`);
+            console.log('');
           } else {
-            // Default: stdout summary
+            // Default: broad, READ-ONLY synthesis to stdout — never writes a file.
             sequence({ target: 'stdout', explain });
           }
         } catch (err) {
@@ -2546,10 +2573,11 @@ async function main() {
 
       if (cmd === 'outcomes') {
         try {
-          // execSync so the labeling prompt owns stdin while it runs
-          const { execSync } = require('child_process');
-          const outcomesArgs = cmdArg ? ' ' + cmdArg : '';
-          execSync(`node ${path.join(__dirname, '..', 'bin', 'phewsh.js')} outcomes${outcomesArgs}`, { stdio: 'inherit' });
+          // execFileSync (argv array, no shell) so the labeling prompt owns
+          // stdin AND REPL input can't be shell-interpreted (hardening).
+          const { execFileSync } = require('child_process');
+          const outcomesArgs = cmdArg ? cmdArg.split(/\s+/).filter(Boolean) : [];
+          execFileSync(process.execPath, [path.join(__dirname, '..', 'bin', 'phewsh.js'), 'outcomes', ...outcomesArgs], { stdio: 'inherit' });
         } catch { /* user quit mid-labeling — fine */ }
         rl.prompt();
         return;
@@ -2727,6 +2755,20 @@ async function main() {
           console.log(`  ${teal('●')} ${sage('Back in phewsh.')} ${slate('No changes detected. 1 kept · 2 undid · 3 redid · 4 flopped · /reconcile · /switch <tool>')}`);
         }
         console.log(`  ${slate('continuing elsewhere?')} ${cream('/handoff')} ${slate('shows the updated brief the next tool inherits')}`);
+        // Auto-reconcile OFFER (human-gated, never auto-writes). Only when the
+        // work left project UNDERSTANDING stale — the docs now disagree with the
+        // code or a projection drifted. Ordinary implementation diffs and a merely
+        // dirty tree do NOT trigger this; that would be noise.
+        try {
+          const truthDrift = (postflight.conflicts || []).filter(c =>
+            /current-state intent disagrees|current-state claims may be stale|should be regenerated|before authoritative intent updated/i.test(c));
+          if (truthDrift.length) {
+            console.log('');
+            console.log(`  ${ember('⚠')} ${sage('Your project understanding may now be stale:')}`);
+            console.log(`    ${slate(truthDrift[0])}`);
+            console.log(`  ${sage('Bring the record up to date so the next tool inherits the truth →')} ${cream('/reconcile')} ${slate('(proposes an exact diff; writes only after you approve)')}`);
+          }
+        } catch { /* the offer is a nicety, never a blocker */ }
         console.log('');
         rl.prompt();
         return;

package/lib/gate-policy.js

@@ -0,0 +1,117 @@
+'use strict';
+
+// Deterministic pre-action policy — the enforcement core of the Decision Gate.
+//
+// Pure and provider-neutral: given an action envelope it returns a decision.
+// No I/O, no provider coupling — the hook adapter (commands/hook.js pre-tool)
+// feeds it the action and renders the provider-specific response. This is the
+// "deterministic enforcement" layer from cli/docs/pre-action-architecture.md;
+// it does NOT replace the Decision Gate, it is how the gate acts before a tool
+// runs. Decisions: 'allow' | 'ask' (require human) | 'deny' (block).
+//
+// Design rules: fail OPEN (an empty/garbled envelope returns allow — a policy
+// must never trap the user), and never inspect file CONTENTS (we judge the
+// action's target/shape, not your code or secrets).
+
+const path = require('path');
+
+// Tools that write/modify the filesystem — common names across providers.
+const WRITE_TOOLS = new Set([
+  'Write', 'Edit', 'MultiEdit', 'NotebookEdit',
+  'create_file', 'apply_patch', 'str_replace_editor', 'edit_file',
+]);
+
+// Shell/command tools.
+const SHELL_TOOLS = new Set(['Bash', 'shell', 'run_command', 'run_terminal_cmd']);
+
+// Paths an agent should never silently write — credentials, keys, VCS internals.
+const DEFAULT_PROTECTED = [
+  '.env', '.env.*', '*.pem', '*.key', 'id_rsa', 'id_ed25519',
+  '.git/', '.npmrc', '.aws/', '.ssh/', '.phewsh/config.json',
+];
+
+// High-blast-radius shell patterns that warrant a human OK.
+const DESTRUCTIVE = [
+  { re: /\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r/, label: 'recursive force delete' },
+  { re: /\bgit\s+push\b[^\n]*--force/, label: 'git force-push' },
+  { re: /\bgit\s+reset\s+--hard\b/, label: 'git hard reset' },
+  { re: /\bDROP\s+(TABLE|DATABASE)\b/i, label: 'SQL DROP' },
+  { re: /\bsudo\b/, label: 'sudo' },
+  { re: /\bchmod\s+-R\b/, label: 'recursive chmod' },
+  { re: /\bmkfs\b|\bdd\s+if=/, label: 'disk write' },
+  { re: /\bcurl\b[^\n]*\|\s*(sh|bash)\b|\bwget\b[^\n]*\|\s*(sh|bash)\b/, label: 'pipe-to-shell' },
+];
+
+function globToRegExp(glob) {
+  const esc = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp('^' + esc + '$');
+}
+
+// Does `target` match any protected entry? Directory entries (trailing '/')
+// match anywhere in the path; file globs match the basename or full path.
+function isProtected(target, protectedList) {
+  if (!target || typeof target !== 'string') return false;
+  const norm = target.replace(/^\.\//, '');
+  const base = path.basename(norm);
+  return protectedList.some(p => {
+    if (p.endsWith('/')) return norm.split('/').includes(p.slice(0, -1)) || norm.startsWith(p);
+    const re = globToRegExp(p);
+    return re.test(base) || re.test(norm);
+  });
+}
+
+function writeTarget(toolInput = {}) {
+  return toolInput.file_path || toolInput.path || toolInput.notebook_path
+    || toolInput.filename || toolInput.target_file || null;
+}
+
+// envelope: { toolName, toolInput, constraints, protectedFiles }
+function evaluateAction(envelope = {}) {
+  try {
+    const { toolName, toolInput = {}, constraints = {}, protectedFiles = [] } = envelope;
+    if (!toolName) return { decision: 'allow', reason: '' };
+    const protectedList = [...DEFAULT_PROTECTED, ...(Array.isArray(protectedFiles) ? protectedFiles : [])];
+
+    // 1. Writes to a protected path → deny (only a deliberate human act should).
+    if (WRITE_TOOLS.has(toolName)) {
+      const target = writeTarget(toolInput);
+      if (isProtected(target, protectedList)) {
+        return { decision: 'deny', reason: `phewsh gate: ${toolName} targets a protected path (${target}). Credentials/keys/VCS internals are off-limits to automated edits.` };
+      }
+    }
+
+    // 2. High-blast-radius shell → ask (require human confirmation).
+    if (SHELL_TOOLS.has(toolName)) {
+      const cmd = String(toolInput.command || toolInput.cmd || '');
+      const hit = DESTRUCTIVE.find(d => d.re.test(cmd));
+      if (hit) {
+        return { decision: 'ask', reason: `phewsh gate: high-blast-radius command (${hit.label}) — confirm before it runs.` };
+      }
+    }
+
+    // 3. Strict autonomy asks before any write. "delegated"/"guided" do not —
+    //    that would turn every edit into ceremony.
+    const autonomy = String(constraints.autonomy || '').toLowerCase();
+    if ((autonomy === 'manual' || autonomy === 'review') && WRITE_TOOLS.has(toolName)) {
+      return { decision: 'ask', reason: `phewsh gate: your autonomy is "${autonomy}" — confirm this ${toolName} before it runs.` };
+    }
+
+    return { decision: 'allow', reason: '' };
+  } catch {
+    return { decision: 'allow', reason: '' }; // fail OPEN: never trap the user
+  }
+}
+
+// A redacted one-line audit record — decision + target shape only, never the
+// tool payload (which may contain code or secrets).
+function auditLine(envelope = {}, result = {}) {
+  const target = WRITE_TOOLS.has(envelope.toolName)
+    ? writeTarget(envelope.toolInput || {})
+    : (SHELL_TOOLS.has(envelope.toolName) ? '<command>' : '');
+  return `${result.decision || 'allow'} ${envelope.toolName || '?'}${target ? ' ' + target : ''}`;
+}
+
+module.exports = {
+  evaluateAction, isProtected, auditLine, writeTarget,
+  WRITE_TOOLS, SHELL_TOOLS, DEFAULT_PROTECTED, DESTRUCTIVE,
+};

package/lib/selfheal.js

@@ -205,6 +205,7 @@ function projectionStatus({ cwd = process.cwd(), targets = TARGET_FILES } = {})
 // `seq`), where the user is actually working in the project.
 function syncContextFiles({ cwd = process.cwd(), targets = TARGET_FILES, createMissing = true } = {}) {
   try {
+    cwd = require('./sequencer/discover').resolveProjectRoot(cwd);
     const intentDir = path.join(cwd, '.intent');
     if (!fs.existsSync(intentDir)) return { synced: [], reason: 'no-intent' };
     const core = buildContextCore(cwd);

package/lib/sequencer/discover.js

@@ -15,10 +15,38 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const INTENT_FILES = ['vision.md', 'plan.md', 'status.md', 'narrative.md', 'next.md'];
+// narrative.md is intentionally NOT a source: it is a deprecated artifact that
+// predates the four-word model (Project · Next · Work · Record) and is no longer
+// authoritative project truth. It must never enter a native projection. See
+// resolveProjectRoot + the canonical projection in selfheal.
+const INTENT_FILES = ['vision.md', 'plan.md', 'status.md', 'next.md'];
 const INTENT_JSON = ['project.json', 'next.json', 'pps.json', 'gate.json'];
 
+// Resolve the project root by walking UP from `start` to the nearest ancestor
+// (including start) that contains a `.intent/` directory — bounded by the home
+// dir and the filesystem root. This stops a nested dir (e.g. an app folder under
+// a monorepo) from being treated as its own project, and makes every
+// context-generating path agree on the same root. Returns `start` unchanged when
+// no `.intent/` exists anywhere upward (so bare-directory behavior is untouched).
+function resolveProjectRoot(start = process.cwd(), home = os.homedir()) {
+  let dir;
+  try { dir = path.resolve(start); } catch { return start; }
+  const fsRoot = path.parse(dir).root;
+  const homeReal = (() => { try { return fs.realpathSync(home); } catch { return home; } })();
+  while (true) {
+    if (fs.existsSync(path.join(dir, '.intent'))) return dir;
+    if (dir === fsRoot) break;
+    let real; try { real = fs.realpathSync(dir); } catch { real = dir; }
+    if (real === homeReal) break; // don't escape above the user's home
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(start);
+}
+
 function discover(cwd = process.cwd(), home = os.homedir()) {
+  cwd = resolveProjectRoot(cwd, home);
   const sources = [];
   const seenPaths = new Set();
 
@@ -119,4 +147,4 @@ function discover(cwd = process.cwd(), home = os.homedir()) {
   return sources;
 }
 
-module.exports = { discover };
+module.exports = { discover, resolveProjectRoot };

package/lib/sequencer/index.js

@@ -3,7 +3,7 @@
 // The core pipeline: discover → parse → rank → compress → emit
 // One function. N inputs. 1 optimal output per target format.
 
-const { discover } = require('./discover');
+const { discover, resolveProjectRoot } = require('./discover');
 const { rank } = require('./ranker');
 const { compress } = require('./compressor');
 
@@ -53,8 +53,12 @@ function sequence(options = {}) {
     cwd = process.cwd(),
   } = options;
 
+  // Resolve to the canonical project root once, so discovery, naming, and any
+  // file write all agree on the same project (a nested dir never self-resolves).
+  const root = resolveProjectRoot(cwd);
+
   // 1. Discover all source files (project + global)
-  let sources = discover(cwd);
+  let sources = discover(root);
 
   // Privacy guard: global per-user memory enriches the summary (stdout), but
   // never bleeds into a project-file target (CLAUDE.md) unless asked for —
@@ -112,12 +116,12 @@ function sequence(options = {}) {
   }
 
   const output = emitter.emit(chunks, {
-    projectName: getProjectName(chunks, cwd),
+    projectName: getProjectName(chunks, root),
   });
 
   // Write to file if requested
   if (write && emitter.writeToFile) {
-    const result = emitter.writeToFile(output, cwd);
+    const result = emitter.writeToFile(output, root);
     return { chunks, output, sources, writeResult: result };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.15.63",
+  "version": "0.15.65",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"
@@ -10,7 +10,9 @@
     "commands/",
     "lib/",
     "mcp/",
-    "README.md"
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
   ],
   "keywords": [
     "intent",
@@ -29,7 +31,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cleverIdeaz/phewsh.git"
+    "url": "git+https://github.com/cleverIdeaz/phewsh-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cleverIdeaz/phewsh-cli/issues"
   },
   "homepage": "https://phewsh.com",
   "engines": {