phewsh 0.11.15 → 0.11.16

package/bin/phewsh.js

@@ -63,6 +63,8 @@ const COMMANDS = {
   watch:   () => require('../commands/watch')(),
   mcp:     () => require('../commands/mcp')(),
   serve:   () => require('../commands/serve')(),
+  sequence: () => require('../commands/sequence')(),
+  seq:     () => require('../commands/sequence')(),
   help:    showHelp,
   version: showVersion,
 };
@@ -88,6 +90,7 @@ function showHelp() {
   console.log(`    ${cyan('ai')}         ${g('One-shot prompt with .intent/ context')}`);
   console.log('');
   console.log(`  ${b(w('sync everywhere'))}`);
+  console.log(`    ${cyan('seq')}        ${g('Sequence all memory → optimal context for any agent')}`);
   console.log(`    ${cyan('watch')}      ${g('Auto-sync .intent/ → CLAUDE.md + cloud')}`);
   console.log(`    ${cyan('push/pull')}  ${g('Manual sync to/from phewsh.com/intent')}`);
   console.log(`    ${cyan('serve')}      ${g('Execution bridge — run from phewsh.com/intent')}`);

package/commands/sequence.js

@@ -0,0 +1,136 @@
+// phewsh sequence (phewsh seq)
+// Universal Memory Transform — reads all AI memory files, emits optimal context.
+
+const fs = require('fs');
+const path = require('path');
+const { sequence } = require('../lib/sequencer');
+const ui = require('../lib/ui');
+
+const { b, w, sage, slate, teal, cream, green, ember } = ui;
+
+const args = process.argv.slice(3);
+
+const flags = {
+  target: getFlag('--target', '-t') || getPositionalTarget(),
+  budget: getFlag('--budget', '-b') || 'standard',
+  explain: args.includes('--explain') || args.includes('-e'),
+  write: args.includes('--write') || args.includes('-w'),
+  dryRun: args.includes('--dry-run'),
+  all: args.includes('--all'),
+  sources: getFlag('--sources', '-s'),
+  help: args.includes('--help') || args.includes('-h'),
+};
+
+function getFlag(long, short) {
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === long || args[i] === short) && args[i + 1]) {
+      return args[i + 1];
+    }
+  }
+  return null;
+}
+
+function getPositionalTarget() {
+  // phewsh seq claude → target claude-md
+  // phewsh seq cursor → target cursorrules
+  const aliases = {
+    claude: 'claude-md',
+    cursor: 'cursorrules',
+    agent: 'agent-md',
+    soul: 'soul-md',
+    json: 'json',
+  };
+  const first = args.find(a => !a.startsWith('-'));
+  return aliases[first] || null;
+}
+
+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('');
+  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')} ${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('');
+  console.log(`  ${cream('targets')}`);
+  console.log(`    ${teal('claude')}     ${sage('CLAUDE.md section (between markers)')}`);
+  console.log('');
+  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('--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')}`);
+  console.log('');
+}
+
+async function main() {
+  if (flags.help) { showHelp(); return; }
+
+  const sourceFilter = flags.sources ? flags.sources.split(',') : null;
+
+  // Dry run: just show what was found
+  if (flags.dryRun) {
+    const { discover } = require('../lib/sequencer/discover');
+    let sources = discover();
+    if (sourceFilter) {
+      sources = sources.filter(s => sourceFilter.some(f => s.type === f || s.type.startsWith(f)));
+    }
+
+    console.log('');
+    console.log(`  ${b(cream('Sources discovered'))} ${slate(`(${sources.length})`)}`);
+    ui.divider('line');
+    if (sources.length === 0) {
+      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)}`);
+      }
+    }
+    ui.divider('line');
+    console.log('');
+    return;
+  }
+
+  // Default behavior: no target = stdout summary
+  const target = flags.target || 'stdout';
+
+  try {
+    const result = sequence({
+      target,
+      budget: flags.budget,
+      sources: sourceFilter,
+      explain: flags.explain,
+      write: flags.write,
+    });
+
+    // If target is stdout, emit already printed
+    if (target === 'stdout') return;
+
+    // If writing to file
+    if (flags.write) {
+      if (result.writeResult === 'updated') {
+        console.log(`\n  ${green('\u2713')} ${sage('Updated CLAUDE.md')}`);
+      } else if (result.writeResult === 'created') {
+        console.log(`\n  ${green('\u2713')} ${sage('Created CLAUDE.md')}`);
+      }
+      console.log(`  ${slate(`${result.chunks.length} chunks from ${result.sources.length} sources`)}`);
+      console.log('');
+      return;
+    }
+
+    // Otherwise print the output
+    console.log(result.output);
+
+  } catch (err) {
+    console.error(`\n  ${ember('!')} ${sage(err.message)}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = main;

package/commands/session.js

@@ -307,6 +307,8 @@ async function main() {
         console.log(`    ${teal('/reload')}      ${sage('Reload .intent/ from disk')}`);
         console.log('');
         console.log(`  ${cream('sync everywhere')}`);
+        console.log(`    ${teal('/seq')}          ${sage('Sequence all memory → optimal context')}`);
+        console.log(`    ${teal('/seq claude')}   ${sage('Sequence → write to CLAUDE.md')}`);
         console.log(`    ${teal('/watch')}       ${sage('Sync .intent/ → CLAUDE.md + cloud (background)')}`);
         console.log(`    ${teal('/export')}      ${sage('Export .intent/ for any AI tool')}`);
         console.log(`    ${teal('/push')}        ${sage('Push to phewsh.com/intent')}`);
@@ -468,6 +470,29 @@ async function main() {
         return;
       }
 
+      if (cmd === 'seq' || cmd === 'sequence') {
+        try {
+          const { sequence } = require('../lib/sequencer');
+          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`);
+            }
+          } else {
+            // Default: stdout summary
+            sequence({ target: 'stdout', explain });
+          }
+        } catch (err) {
+          console.error(`  ${ember('!')} ${sage('Sequence failed:')} ${err.message}`);
+        }
+        rl.prompt();
+        return;
+      }
+
       if (cmd === 'export') {
         try {
           const { generateContext } = require('./context');

package/lib/sequencer/compressor.js

@@ -0,0 +1,51 @@
+// Compress ranked chunks to fit a target token budget.
+// Rough estimate: 1 token ~= 4 chars (conservative for markdown).
+
+const TOKEN_BUDGETS = {
+  minimal: 500,
+  standard: 2000,
+  full: 5000,
+  unlimited: Infinity,
+};
+
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+function compress(rankedChunks, budget = 'standard') {
+  const maxTokens = TOKEN_BUDGETS[budget] || TOKEN_BUDGETS.standard;
+  if (maxTokens === Infinity) return rankedChunks;
+
+  const result = [];
+  let totalTokens = 0;
+
+  for (const chunk of rankedChunks) {
+    const tokens = estimateTokens(chunk.content);
+
+    if (totalTokens + tokens <= maxTokens) {
+      result.push(chunk);
+      totalTokens += tokens;
+    } else {
+      // Partial inclusion: if chunk is large but high-weight, take first lines
+      const remainingTokens = maxTokens - totalTokens;
+      if (remainingTokens > 50 && chunk.weight > 0.3) {
+        const charBudget = remainingTokens * 4;
+        const lines = chunk.content.split('\n');
+        let partial = '';
+        for (const line of lines) {
+          if (partial.length + line.length + 1 > charBudget) break;
+          partial += line + '\n';
+        }
+        if (partial.trim()) {
+          result.push({ ...chunk, content: partial.trim(), _truncated: true });
+          totalTokens += estimateTokens(partial);
+        }
+      }
+      break; // Budget hit
+    }
+  }
+
+  return result;
+}
+
+module.exports = { compress, estimateTokens, TOKEN_BUDGETS };

package/lib/sequencer/discover.js

@@ -0,0 +1,97 @@
+// Discover all memory/context source files in the working directory.
+// Returns a list of { path, type } for each recognized source.
+
+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'];
+const INTENT_JSON = ['project.json', 'pps.json', 'gate.json'];
+
+function discover(cwd = process.cwd()) {
+  const sources = [];
+
+  // .intent/ artifacts
+  const intentDir = path.join(cwd, '.intent');
+  if (fs.existsSync(intentDir)) {
+    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 });
+      }
+    }
+  }
+
+  // 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' });
+  }
+
+  // Claude auto-memory — project-scoped
+  // .claude/projects/<encoded-cwd>/memory/MEMORY.md
+  const claudeDir = path.join(os.homedir(), '.claude');
+  if (fs.existsSync(claudeDir)) {
+    const projectsDir = path.join(claudeDir, 'projects');
+    if (fs.existsSync(projectsDir)) {
+      // Claude encodes cwd as path with - replacing /
+      const encoded = cwd.replace(/\//g, '-');
+      const memoryDir = path.join(projectsDir, encoded, 'memory');
+      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' });
+
+          // Also discover linked memory files from MEMORY.md
+          try {
+            const content = fs.readFileSync(memoryIndex, 'utf-8');
+            const linkRegex = /\[([^\]]+\.md)\]\(([^)]+\.md)\)/g;
+            let match;
+            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] });
+              }
+            }
+          } catch { /* skip */ }
+        }
+      }
+    }
+  }
+
+  // .cursorrules
+  const cursorrules = path.join(cwd, '.cursorrules');
+  if (fs.existsSync(cursorrules)) {
+    sources.push({ path: cursorrules, type: 'cursor', name: '.cursorrules' });
+  }
+
+  // agent.md / AGENTS.md
+  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 });
+    }
+  }
+
+  // soul.md
+  const soulMd = path.join(cwd, 'soul.md');
+  if (fs.existsSync(soulMd)) {
+    sources.push({ path: soulMd, type: 'soul', name: 'soul.md' });
+  }
+
+  // .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' });
+  }
+
+  // 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' });
+  }
+
+  return sources;
+}
+
+module.exports = { discover };

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

@@ -0,0 +1,173 @@
+// Emit a CLAUDE.md section from ranked, compressed chunks.
+// This is the primary "continuity" output — what makes Claude Code
+// instantly aware of everything across all sources.
+
+const fs = require('fs');
+const path = require('path');
+
+const START_MARKER = '<!-- PHEWSH:START -->';
+const END_MARKER = '<!-- PHEWSH:END -->';
+
+function emit(chunks, options = {}) {
+  const projectName = options.projectName || path.basename(process.cwd());
+  const sections = [];
+
+  sections.push(`# PHEWSH Adaptive Context — ${projectName}`);
+  sections.push(`> Auto-synced by \`phewsh seq\` | ${new Date().toISOString().split('T')[0]}`);
+  sections.push(`> This section is regenerated from ${countSources(chunks)} sources. Do not edit manually.`);
+  sections.push('');
+
+  // Group chunks by kind for structured output
+  const byKind = groupByKind(chunks);
+
+  // 1. Identity — what this project is
+  if (byKind.identity?.length > 0) {
+    sections.push('## Project');
+    for (const chunk of byKind.identity) {
+      sections.push(chunk.content);
+    }
+    sections.push('');
+  }
+
+  // 2. Constraints — operational reality
+  if (byKind.constraint?.length > 0) {
+    sections.push('## Operational Reality');
+    sections.push('These constraints MUST shape every suggestion and implementation decision:');
+    sections.push('');
+    for (const chunk of byKind.constraint) {
+      // If this has structured constraint metadata, emit rich format
+      if (chunk.metadata?.constraints) {
+        sections.push(formatConstraints(chunk.metadata.constraints));
+      } else {
+        sections.push(chunk.content);
+      }
+    }
+    sections.push('');
+  }
+
+  // 3. State — what's happening now
+  if (byKind.state?.length > 0) {
+    sections.push('## Current State');
+    for (const chunk of byKind.state) {
+      sections.push(chunk.content);
+    }
+    sections.push('');
+  }
+
+  // 4. Feedback — learned behaviors
+  if (byKind.feedback?.length > 0) {
+    sections.push('## Behavioral Rules');
+    sections.push('Learned from prior work:');
+    sections.push('');
+    for (const chunk of byKind.feedback) {
+      // Memory files are already concise — include as-is
+      const label = chunk.metadata?.name || chunk.source;
+      sections.push(`**${label}**: ${chunk.content.split('\n')[0]}`);
+      // If multi-line, include the rest indented
+      const rest = chunk.content.split('\n').slice(1).filter(l => l.trim());
+      if (rest.length > 0) {
+        rest.forEach(l => sections.push(`  ${l}`));
+      }
+    }
+    sections.push('');
+  }
+
+  // 5. Context — architecture, systems, plan
+  if (byKind.context?.length > 0) {
+    sections.push('## Context');
+    for (const chunk of byKind.context) {
+      // Skip generated PHEWSH sections (they're derivative)
+      if (chunk.metadata?.generated) continue;
+      sections.push(chunk.content);
+    }
+    sections.push('');
+  }
+
+  // 6. Actions — current tasks
+  if (byKind.action?.length > 0) {
+    sections.push('## Active Actions');
+    for (const chunk of byKind.action) {
+      sections.push(chunk.content);
+    }
+    sections.push('');
+  }
+
+  // 7. References — pointers to external systems
+  if (byKind.reference?.length > 0) {
+    sections.push('## References');
+    for (const chunk of byKind.reference) {
+      const label = chunk.metadata?.name || chunk.source;
+      sections.push(`- **${label}**: ${chunk.content.split('\n')[0]}`);
+    }
+    sections.push('');
+  }
+
+  sections.push('---');
+  sections.push('*Auto-synced from [PHEWSH](https://phewsh.com/intent)*');
+
+  return sections.join('\n');
+}
+
+function formatConstraints(c) {
+  const lines = [];
+
+  if (c.budget > 0) {
+    lines.push(`- Budget: $${c.budget}. ${
+      c.budget < 100 ? 'Extremely tight — free/open-source only.'
+      : c.budget < 500 ? 'Limited — justify any paid tool.'
+      : c.budget < 2000 ? 'Moderate — strategic spending OK.'
+      : 'Substantial — professional tools welcome.'
+    }`);
+  }
+  if (c.timeHoursPerWeek > 0) {
+    lines.push(`- Time: ${c.timeHoursPerWeek} hrs/week. ${
+      c.timeHoursPerWeek <= 5 ? 'Micro-steps only.'
+      : c.timeHoursPerWeek <= 15 ? 'Part-time. Clear stopping points.'
+      : c.timeHoursPerWeek <= 30 ? 'Near full-time.'
+      : 'Full-time+.'
+    }`);
+  }
+  if (c.skillLevel) lines.push(`- Skill: ${c.skillLevel}`);
+  if (c.urgency) lines.push(`- Urgency: ${c.urgency}`);
+  if (c.autonomy) lines.push(`- Autonomy: ${c.autonomy}`);
+
+  return lines.join('\n');
+}
+
+function groupByKind(chunks) {
+  const groups = {};
+  for (const chunk of chunks) {
+    if (!groups[chunk.kind]) groups[chunk.kind] = [];
+    groups[chunk.kind].push(chunk);
+  }
+  return groups;
+}
+
+function countSources(chunks) {
+  return new Set(chunks.map(c => c.source.split(':')[0])).size;
+}
+
+// Write the emitted content into CLAUDE.md (between markers)
+function writeToFile(content, cwd = process.cwd()) {
+  const claudePath = path.join(cwd, 'CLAUDE.md');
+  const wrapped = `${START_MARKER}\n${content}\n${END_MARKER}`;
+
+  if (fs.existsSync(claudePath)) {
+    let existing = fs.readFileSync(claudePath, 'utf-8');
+    const startIdx = existing.indexOf(START_MARKER);
+    const endIdx = existing.indexOf(END_MARKER);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      existing = existing.slice(0, startIdx) + wrapped + existing.slice(endIdx + END_MARKER.length);
+    } else {
+      existing = existing.trimEnd() + '\n\n' + wrapped + '\n';
+    }
+    fs.writeFileSync(claudePath, existing);
+    return 'updated';
+  } else {
+    fs.writeFileSync(claudePath, wrapped + '\n');
+    return 'created';
+  }
+}
+
+module.exports = { emit, writeToFile };

package/lib/sequencer/emitters/stdout.js

@@ -0,0 +1,89 @@
+// Human-readable terminal output of the sequencing result.
+// Shows what was found, how it was ranked, and the final output.
+
+const ui = require('../../ui');
+
+function emit(chunks, options = {}) {
+  const { explain = false, sources = [] } = options;
+  const { b, w, g, sage, slate, teal, cream, green, yellow, ember, peach } = ui;
+
+  console.log('');
+
+  if (explain) {
+    return emitExplain(chunks, sources, ui);
+  }
+
+  // Compact summary
+  const sourceCount = new Set(chunks.map(c => c.source.split(':')[0])).size;
+  const kindCounts = {};
+  for (const chunk of chunks) {
+    kindCounts[chunk.kind] = (kindCounts[chunk.kind] || 0) + 1;
+  }
+
+  console.log(`  ${b(cream('Sequenced'))} ${teal(String(chunks.length))} ${sage('chunks from')} ${teal(String(sourceCount))} ${sage('sources')}`);
+  ui.divider('line');
+
+  // Show kind breakdown
+  const kindOrder = ['constraint', 'identity', 'feedback', 'state', 'action', 'context', 'reference'];
+  for (const kind of kindOrder) {
+    if (!kindCounts[kind]) continue;
+    const icon = KIND_ICONS[kind] || '?';
+    console.log(`    ${icon} ${cream(kind.padEnd(12))} ${slate(String(kindCounts[kind]))}`);
+  }
+
+  ui.divider('line');
+
+  // Show top 5 chunks by weight
+  console.log(`  ${sage('top signal:')}`);
+  const top = chunks.slice(0, 5);
+  for (const chunk of top) {
+    const weight = chunk.weight.toFixed(2);
+    const preview = chunk.content.split('\n')[0].slice(0, 60);
+    console.log(`    ${slate(weight)} ${teal(chunk.kind.padEnd(10))} ${sage(preview)}`);
+  }
+
+  // Token estimate
+  const totalChars = chunks.reduce((sum, c) => sum + c.content.length, 0);
+  const estTokens = Math.ceil(totalChars / 4);
+  console.log('');
+  console.log(`  ${slate(`~${estTokens} tokens`)}`);
+  console.log('');
+}
+
+function emitExplain(chunks, sources, { b, w, g, sage, slate, teal, cream, green, yellow, ember }) {
+  // Full ranking breakdown
+  console.log(`  ${b(cream('Sequencer Explain'))}`);
+  console.log('');
+
+  // Sources discovered
+  console.log(`  ${b(cream('Sources'))}`);
+  for (const source of sources) {
+    console.log(`    ${teal(source.type.padEnd(16))} ${sage(source.name)}`);
+  }
+  console.log('');
+
+  // All chunks with full weight breakdown
+  console.log(`  ${b(cream('Chunks'))} ${slate(`(${chunks.length} total, ranked by weight)`)}`);
+  console.log('');
+
+  for (const chunk of chunks) {
+    const weight = chunk.weight.toFixed(3);
+    const preview = chunk.content.split('\n')[0].slice(0, 50);
+    const truncated = chunk._truncated ? ` ${ember('[truncated]')}` : '';
+    console.log(`  ${cream(weight)} ${teal(chunk.kind.padEnd(12))} ${sage(chunk.source)}`);
+    console.log(`         ${slate(preview)}${truncated}`);
+  }
+  console.log('');
+}
+
+const KIND_ICONS = {
+  constraint: '\u2588',  // solid block — constraints are load-bearing
+  identity: '\u25C6',    // diamond — core
+  feedback: '\u25B6',    // triangle — directional
+  state: '\u25CF',       // circle — current
+  action: '\u25A0',      // square — tasks
+  context: '\u25CB',     // open circle — background
+  reference: '\u25B7',   // open triangle — pointer
+};
+
+module.exports = { emit };

package/lib/sequencer/index.js

@@ -0,0 +1,116 @@
+// Sequencer — Universal Memory Transform Layer
+//
+// The core pipeline: discover → parse → rank → compress → emit
+// One function. N inputs. 1 optimal output per target format.
+
+const { discover } = require('./discover');
+const { rank } = require('./ranker');
+const { compress } = require('./compressor');
+
+// Parsers by source type
+const parsers = {
+  intent: require('./parsers/intent'),
+  'claude-md': require('./parsers/claude-md'),
+  'claude-memory': require('./parsers/claude-memory'),
+  'claude-memory-file': require('./parsers/claude-memory'),
+  cursor: require('./parsers/generic'),
+  agent: require('./parsers/generic'),
+  soul: require('./parsers/generic'),
+  copilot: require('./parsers/generic'),
+  readme: require('./parsers/generic'),
+};
+
+// Emitters by target format
+const emitters = {
+  'claude-md': require('./emitters/claude-md'),
+  stdout: require('./emitters/stdout'),
+};
+
+/**
+ * Run the full sequencing pipeline.
+ *
+ * @param {object} options
+ * @param {string} options.target - Output format: 'claude-md' | 'stdout' | 'json'
+ * @param {string} options.budget - Token budget: 'minimal' | 'standard' | 'full' | 'unlimited'
+ * @param {string[]} options.sources - Limit to specific source types (null = all)
+ * @param {boolean} options.explain - Show full ranking breakdown
+ * @param {boolean} options.write - Write to file (for claude-md target)
+ * @param {string} options.cwd - Working directory
+ * @returns {{ chunks: object[], output: string, sources: object[] }}
+ */
+function sequence(options = {}) {
+  const {
+    target = 'claude-md',
+    budget = 'standard',
+    sources: sourceFilter = null,
+    explain = false,
+    write = false,
+    cwd = process.cwd(),
+  } = options;
+
+  // 1. Discover all source files
+  let sources = discover(cwd);
+
+  // Filter sources if requested
+  if (sourceFilter && sourceFilter.length > 0) {
+    sources = sources.filter(s =>
+      sourceFilter.some(f => s.type === f || s.type.startsWith(f))
+    );
+  }
+
+  // 2. Parse all sources into chunks
+  let chunks = [];
+  for (const source of sources) {
+    const parser = parsers[source.type];
+    if (!parser) continue;
+
+    const parsed = parser.parse(source);
+    chunks.push(...parsed);
+  }
+
+  // 3. Rank all chunks
+  chunks = rank(chunks);
+
+  // 4. Compress to budget
+  chunks = compress(chunks, budget);
+
+  // 5. Emit
+  const emitter = emitters[target];
+  if (!emitter) {
+    throw new Error(`Unknown target format: ${target}. Available: ${Object.keys(emitters).join(', ')}`);
+  }
+
+  if (target === 'stdout') {
+    emitter.emit(chunks, { explain, sources });
+    return { chunks, output: null, sources };
+  }
+
+  const output = emitter.emit(chunks, {
+    projectName: getProjectName(chunks, cwd),
+  });
+
+  // Write to file if requested
+  if (write && emitter.writeToFile) {
+    const result = emitter.writeToFile(output, cwd);
+    return { chunks, output, sources, writeResult: result };
+  }
+
+  return { chunks, output, sources };
+}
+
+/**
+ * Get project name from chunks or fall back to directory name.
+ */
+function getProjectName(chunks, cwd) {
+  // Check identity chunks from intent source for a project name
+  for (const chunk of chunks) {
+    if (chunk.sourceType === 'intent' && chunk.kind === 'identity') {
+      const nameMatch = chunk.content.match(/\*\*Name\*\*:\s*(.+)/);
+      if (nameMatch) return nameMatch[1].trim();
+    }
+  }
+  const path = require('path');
+  return path.basename(cwd);
+}
+
+module.exports = { sequence };

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

@@ -0,0 +1,106 @@
+// Parse CLAUDE.md into MemoryChunks.
+// Critical distinction: manual sections (user-curated, high authority)
+// vs generated sections (PHEWSH markers, lower authority — derivative).
+
+const fs = require('fs');
+
+const PHEWSH_START = '<!-- PHEWSH:START -->';
+const PHEWSH_END = '<!-- PHEWSH:END -->';
+
+function parse(source) {
+  const content = fs.readFileSync(source.path, 'utf-8');
+  const mtime = fs.statSync(source.path).mtime.toISOString();
+  const chunks = [];
+
+  const startIdx = content.indexOf(PHEWSH_START);
+  const endIdx = content.indexOf(PHEWSH_END);
+
+  let manualContent = content;
+  let generatedContent = null;
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Split manual from generated
+    manualContent = (
+      content.slice(0, startIdx) +
+      content.slice(endIdx + PHEWSH_END.length)
+    ).trim();
+
+    generatedContent = content.slice(
+      startIdx + PHEWSH_START.length,
+      endIdx
+    ).trim();
+  }
+
+  // Parse manual sections
+  if (manualContent) {
+    const sections = splitSections(manualContent);
+    for (const section of sections) {
+      if (!section.body.trim()) continue;
+
+      const kind = classifySection(section.title);
+      chunks.push({
+        source: `CLAUDE.md:${section.title || 'root'}`,
+        sourceType: 'claude-md-manual',
+        kind,
+        content: section.body.trim(),
+        timestamp: mtime,
+        metadata: { section: section.title },
+      });
+    }
+  }
+
+  // Generated section — lower authority, will get deduped against .intent/
+  if (generatedContent) {
+    chunks.push({
+      source: 'CLAUDE.md:phewsh-generated',
+      sourceType: 'claude-md-generated',
+      kind: 'context',
+      content: generatedContent,
+      timestamp: mtime,
+      metadata: { generated: true },
+    });
+  }
+
+  return chunks;
+}
+
+function splitSections(content) {
+  const sections = [];
+  let current = { title: '', body: '' };
+
+  for (const line of content.split('\n')) {
+    const heading = line.match(/^(#{1,2})\s+(.+)/);
+    if (heading) {
+      if (current.body.trim() || current.title) {
+        sections.push(current);
+      }
+      current = { title: heading[2], body: '' };
+    } else {
+      current.body += line + '\n';
+    }
+  }
+  if (current.body.trim() || current.title) {
+    sections.push(current);
+  }
+
+  return sections;
+}
+
+function classifySection(title) {
+  if (!title) return 'context';
+  const t = title.toLowerCase();
+
+  if (/architect|structure|infrastructure|system|stack/.test(t)) return 'context';
+  if (/convention|rule|style|format|lint/.test(t)) return 'feedback';
+  if (/deploy|build|ship|ci|cd/.test(t)) return 'context';
+  if (/constraint|budget|time|limit/.test(t)) return 'constraint';
+  if (/product|about|what|mission|vision/.test(t)) return 'identity';
+  if (/command|usage|api|endpoint/.test(t)) return 'reference';
+  if (/status|progress|current|state/.test(t)) return 'state';
+  if (/key|secret|env|config/.test(t)) return 'reference';
+  if (/monetiz|payment|stripe|billing/.test(t)) return 'context';
+
+  return 'context';
+}
+
+module.exports = { parse };

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

@@ -0,0 +1,53 @@
+// Parse Claude auto-memory files into MemoryChunks.
+// Reads individual .md files with YAML-like frontmatter (name, description, type).
+
+const fs = require('fs');
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^(\w+):\s*(.+)$/);
+    if (kv) meta[kv[1]] = kv[2].trim();
+  }
+  return { meta, body: match[2] };
+}
+
+// Map Claude memory types to our chunk kinds
+const TYPE_TO_KIND = {
+  user: 'identity',
+  feedback: 'feedback',
+  project: 'context',
+  reference: 'reference',
+};
+
+function parse(source) {
+  const content = fs.readFileSync(source.path, 'utf-8');
+  const mtime = fs.statSync(source.path).mtime.toISOString();
+
+  // MEMORY.md index file — skip, we read the linked files directly
+  if (source.type === 'claude-memory') return [];
+
+  // Individual memory files
+  const { meta, body } = parseFrontmatter(content);
+  if (!body.trim()) return [];
+
+  const kind = TYPE_TO_KIND[meta.type] || 'context';
+
+  return [{
+    source: `claude-memory:${source.name}`,
+    sourceType: 'claude-memory-file',
+    kind,
+    content: body.trim(),
+    timestamp: mtime,
+    metadata: {
+      name: meta.name,
+      description: meta.description,
+      memoryType: meta.type,
+    },
+  }];
+}
+
+module.exports = { parse };

package/lib/sequencer/parsers/generic.js

@@ -0,0 +1,31 @@
+// Generic parser for .cursorrules, agent.md, soul.md, README.md, copilot-instructions.md
+// These are all "read the whole file as one chunk" sources with type-appropriate kind.
+
+const fs = require('fs');
+
+const TYPE_TO_KIND = {
+  cursor: 'feedback',     // .cursorrules are behavioral rules
+  agent: 'identity',      // agent.md defines agent capabilities
+  soul: 'identity',       // soul.md defines project soul
+  copilot: 'feedback',    // copilot-instructions are behavioral rules
+  readme: 'context',      // README is broad project context
+};
+
+function parse(source) {
+  const content = fs.readFileSync(source.path, 'utf-8');
+  if (!content.trim()) return [];
+
+  const mtime = fs.statSync(source.path).mtime.toISOString();
+  const kind = TYPE_TO_KIND[source.type] || 'context';
+
+  return [{
+    source: source.name,
+    sourceType: source.type,
+    kind,
+    content: content.trim(),
+    timestamp: mtime,
+    metadata: {},
+  }];
+}
+
+module.exports = { parse };

package/lib/sequencer/parsers/intent.js

@@ -0,0 +1,237 @@
+// Parse .intent/ artifacts into MemoryChunks.
+// This is the highest-authority source — user-authored canonical intent.
+
+const fs = require('fs');
+const path = require('path');
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^(\w+):\s*(.+)$/);
+    if (kv) meta[kv[1]] = kv[2].trim();
+  }
+  return { meta, body: match[2] };
+}
+
+function extractSections(body) {
+  const sections = [];
+  let current = null;
+
+  for (const line of body.split('\n')) {
+    const heading = line.match(/^##\s+(.+)/);
+    if (heading) {
+      if (current) sections.push(current);
+      current = { title: heading[1], lines: [] };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  if (current) sections.push(current);
+  return sections;
+}
+
+function parseVision(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const { meta, body } = parseFrontmatter(content);
+  const mtime = fs.statSync(filePath).mtime.toISOString();
+  const timestamp = meta.updated || meta.created || mtime;
+  const chunks = [];
+
+  // Whole vision as identity
+  chunks.push({
+    source: '.intent/vision.md',
+    sourceType: 'intent',
+    kind: 'identity',
+    content: body.trim(),
+    timestamp,
+    metadata: { frontmatter: meta },
+  });
+
+  return chunks;
+}
+
+function parsePlan(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const { meta, body } = parseFrontmatter(content);
+  const mtime = fs.statSync(filePath).mtime.toISOString();
+  const timestamp = meta.updated || meta.created || mtime;
+
+  return [{
+    source: '.intent/plan.md',
+    sourceType: 'intent',
+    kind: 'context',
+    content: body.trim(),
+    timestamp,
+    metadata: { frontmatter: meta },
+  }];
+}
+
+function parseStatus(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const { meta, body } = parseFrontmatter(content);
+  const mtime = fs.statSync(filePath).mtime.toISOString();
+  const timestamp = meta.updated || meta.created || mtime;
+
+  return [{
+    source: '.intent/status.md',
+    sourceType: 'intent',
+    kind: 'state',
+    content: body.trim(),
+    timestamp,
+    metadata: { frontmatter: meta },
+  }];
+}
+
+function parseNext(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const { meta, body } = parseFrontmatter(content);
+  const mtime = fs.statSync(filePath).mtime.toISOString();
+  const timestamp = meta.updated || meta.created || mtime;
+
+  return [{
+    source: '.intent/next.md',
+    sourceType: 'intent',
+    kind: 'state',
+    content: body.trim(),
+    timestamp,
+    metadata: { frontmatter: meta },
+  }];
+}
+
+function parseNarrative(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const { meta, body } = parseFrontmatter(content);
+  const mtime = fs.statSync(filePath).mtime.toISOString();
+  const timestamp = meta.updated || meta.created || mtime;
+
+  return [{
+    source: '.intent/narrative.md',
+    sourceType: 'intent',
+    kind: 'identity',
+    content: body.trim(),
+    timestamp,
+    metadata: { frontmatter: meta },
+  }];
+}
+
+function parseProjectJson(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const mtime = fs.statSync(filePath).mtime.toISOString();
+  let data;
+  try { data = JSON.parse(raw); } catch { return []; }
+
+  const chunks = [];
+
+  // Project identity
+  const identityParts = [];
+  if (data.name) identityParts.push(`**Name**: ${data.name}`);
+  if (data.tldr) identityParts.push(`**TLDR**: ${data.tldr}`);
+  if (data.archetype) identityParts.push(`**Type**: ${data.archetype}`);
+  if (identityParts.length > 0) {
+    chunks.push({
+      source: '.intent/project.json',
+      sourceType: 'intent',
+      kind: 'identity',
+      content: identityParts.join('\n'),
+      timestamp: mtime,
+      metadata: {},
+    });
+  }
+
+  // Decision gate constraints
+  const gate = data.decisionGate;
+  if (gate?.constraints) {
+    const c = gate.constraints;
+    const lines = [];
+    if (c.budget > 0) lines.push(`Budget: $${c.budget}`);
+    if (c.timeHoursPerWeek > 0) lines.push(`Time: ${c.timeHoursPerWeek} hrs/week`);
+    if (c.skillLevel) lines.push(`Skill: ${c.skillLevel}`);
+    if (c.urgency) lines.push(`Urgency: ${c.urgency}`);
+    if (c.autonomy) lines.push(`Autonomy: ${c.autonomy}`);
+
+    chunks.push({
+      source: '.intent/project.json:constraints',
+      sourceType: 'intent',
+      kind: 'constraint',
+      content: lines.join('\n'),
+      timestamp: gate.createdAt || mtime,
+      metadata: { constraints: c },
+    });
+  }
+
+  // Success criteria
+  if (gate?.successCriteria?.length > 0) {
+    chunks.push({
+      source: '.intent/project.json:success',
+      sourceType: 'intent',
+      kind: 'identity',
+      content: 'Success criteria:\n' + gate.successCriteria.map(c => `- ${c}`).join('\n'),
+      timestamp: gate.createdAt || mtime,
+      metadata: {},
+    });
+  }
+
+  // Responsibility split
+  if (gate?.responsibilitySplit) {
+    const lines = [];
+    if (gate.responsibilitySplit.ai?.length > 0) {
+      lines.push('AI can handle:');
+      gate.responsibilitySplit.ai.forEach(r => lines.push(`- ${r}`));
+    }
+    if (gate.responsibilitySplit.human?.length > 0) {
+      lines.push('Requires human:');
+      gate.responsibilitySplit.human.forEach(r => lines.push(`- ${r}`));
+    }
+    if (lines.length > 0) {
+      chunks.push({
+        source: '.intent/project.json:responsibilities',
+        sourceType: 'intent',
+        kind: 'constraint',
+        content: lines.join('\n'),
+        timestamp: gate.createdAt || mtime,
+        metadata: {},
+      });
+    }
+  }
+
+  // Actions as state
+  if (data.actions?.length > 0) {
+    const active = data.actions.filter(a => a.state !== 'reconciled');
+    if (active.length > 0) {
+      chunks.push({
+        source: '.intent/project.json:actions',
+        sourceType: 'intent',
+        kind: 'action',
+        content: active.map(a => `- [${a.state}] ${a.intent} (${a.category})`).join('\n'),
+        timestamp: mtime,
+        metadata: {},
+      });
+    }
+  }
+
+  return chunks;
+}
+
+const FILE_PARSERS = {
+  'vision.md': parseVision,
+  'plan.md': parsePlan,
+  'status.md': parseStatus,
+  'next.md': parseNext,
+  'narrative.md': parseNarrative,
+  'project.json': parseProjectJson,
+};
+
+function parse(source) {
+  const parser = FILE_PARSERS[source.name];
+  if (!parser) return [];
+  try {
+    return parser(source.path);
+  } catch {
+    return [];
+  }
+}
+
+module.exports = { parse };

package/lib/sequencer/ranker.js

@@ -0,0 +1,84 @@
+// Rank memory chunks by recency, impact, source authority, and deduplication.
+// Weight = recency * impact * sourceAuthority * dedupPenalty
+
+const crypto = require('crypto');
+
+// Impact by chunk kind — what matters most across all contexts
+const KIND_IMPACT = {
+  constraint: 1.0,
+  identity: 0.9,
+  feedback: 0.8,
+  state: 0.7,
+  action: 0.6,
+  reference: 0.4,
+  context: 0.5,
+};
+
+// Source authority — how much to trust this origin
+const SOURCE_AUTHORITY = {
+  'intent': 1.0,            // User-authored canonical intent
+  'claude-md-manual': 0.9,  // User-curated CLAUDE.md sections
+  'claude-md-generated': 0.5, // Machine-generated CLAUDE.md sections (derivative)
+  'agent': 0.8,             // Deliberate agent identity docs
+  'soul': 0.8,              // Project soul/values
+  'claude-memory-file': 0.7, // AI-observed memories (may be stale)
+  'claude-memory': 0.6,     // Memory index (pointers, not content)
+  'cursor': 0.7,            // Tool-specific rules
+  'copilot': 0.7,           // Tool-specific rules
+  'readme': 0.4,            // Often stale, broad
+};
+
+function recencyScore(timestamp) {
+  if (!timestamp) return 0.3;
+
+  const now = Date.now();
+  const then = new Date(timestamp).getTime();
+  if (isNaN(then)) return 0.3;
+
+  const daysAgo = (now - then) / (1000 * 60 * 60 * 24);
+
+  if (daysAgo < 1) return 1.0;
+  if (daysAgo < 7) return 0.8;
+  if (daysAgo < 30) return 0.6;
+  return 0.3;
+}
+
+function contentHash(content) {
+  return crypto.createHash('md5').update(content.trim().toLowerCase()).digest('hex');
+}
+
+function rank(chunks) {
+  // Assign raw weights
+  for (const chunk of chunks) {
+    const recency = recencyScore(chunk.timestamp);
+    const impact = KIND_IMPACT[chunk.kind] || 0.5;
+    const authority = SOURCE_AUTHORITY[chunk.sourceType] || 0.5;
+    chunk.weight = recency * impact * authority;
+  }
+
+  // Deduplication: penalize near-duplicate content across sources
+  const seen = new Map(); // hash → highest-weight chunk
+  for (const chunk of chunks) {
+    const hash = contentHash(chunk.content);
+    chunk._hash = hash;
+
+    if (seen.has(hash)) {
+      const existing = seen.get(hash);
+      if (chunk.weight > existing.weight) {
+        existing.weight *= 0.05; // near-zero the weaker duplicate
+        seen.set(hash, chunk);
+      } else {
+        chunk.weight *= 0.05;
+      }
+    } else {
+      seen.set(hash, chunk);
+    }
+  }
+
+  // Sort by weight descending
+  chunks.sort((a, b) => b.weight - a.weight);
+
+  return chunks;
+}
+
+module.exports = { rank, recencyScore, KIND_IMPACT, SOURCE_AUTHORITY };

package/package.json

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