syntropic 0.8.0 → 0.9.0

package/README.md

@@ -1,127 +1,112 @@
 # syntropic
 
-A development methodology for AI-assisted coding. Works with **Claude Code**, **Cursor**, **Windsurf**, **GitHub Copilot**, and **OpenAI Codex**.
+**Ship better software. Prove it on your own code first.**
 
-One command gives your AI coding tools a disciplined development pipeline — so they research before they plan, plan before they build, and review before they ship.
+A development methodology for AI-assisted coding. Works with **Claude Code**, **Cursor**, **Windsurf**, **GitHub Copilot**, and **OpenAI Codex**.
 
-## Quick Start
+## Try Before You Install
 
 ```bash
-npx syntropic init my-project
+npx syntropic audit
 ```
 
-Or add to an existing project:
+Analyses your last 20 git commits for process issues — localhost references, env files in git, commit discipline, fix ratios, governance docs. No install needed. Nothing sent anywhere. See what the methodology catches on **your** code.
+
+## Install
 
 ```bash
-cd my-project
 npx syntropic init
 ```
 
-You'll be asked which AI tools you use. The CLI generates a minimal instruction file for each:
-
-| Tool | File Generated |
-|------|---------------|
-| Claude Code | `CLAUDE.md` |
-| Cursor | `.cursorrules` |
-| Windsurf | `.windsurfrules` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| OpenAI Codex | `AGENTS.md` |
-
-## How It Works
-
-**Server-served, client-computed.** Your instruction file contains a single bootstrap rule (EG13) that tells your AI tool to fetch the full methodology from the Syntropic server at the start of every development cycle. All rules, agents, and learning data are served fresh — always up to date, zero local files to maintain.
-
-Your LLM does all the compute. Syntropic serves the methodology but runs zero inference. Your data stays on your machine.
+You get: a disciplined development pipeline, governance doc templates, and a connection to the PRISM methodology network — so your rules stay current as the methodology evolves.
 
 ## What You Get
 
-**Evergreen Rules (EG1-EG13)** — fetched at runtime from the PRISM network:
+**Evergreen Rules** — battle-tested development rules fetched fresh at every cycle:
 
-- **EG1: Pre-Flight Loop** — build must pass, no localhost refs, verify after deploy
-- **EG2: Ship and Iterate** — bias to action, only pause for destructive/expensive/irreversible
-- **EG3: Hypothesis-Driven Debugging** — state hypothesis, test without code changes, only code if confirmed
-- **EG7: Implementation Pipeline** — scale process to task size (Full / Lightweight / Minimum cycle)
-- **EG8: Live Site Testing** — test page first, promote to production with approval
-- **EG9: Session Continuity** — re-read rules on reset, verify state before proceeding
-- **EG13: PRISM Sync** — fetch methodology at cycle start, report at cycle end
+| Rule | What it prevents | Real-world save |
+|------|-----------------|-----------------|
+| **EG1: Pre-flight** | Localhost refs, broken builds reaching production | Caught 3 localhost references pre-deploy |
+| **EG7: Pipeline** | AI jumping to code without research or planning | Structured 123 features across Full/Lightweight/Minimum cycles |
+| **EG8: Test first** | Untested changes reaching production users | Every fix caught on test page — 12 verified promotions |
+| **EG10: Env hygiene** | Env var corruption (trailing newlines, wrong formats) | Prevented silent API failures across 6 providers |
+| **EG11: Prod sync** | Access control divergence between test and production | Caught lockout bug before 8+ users were affected |
+| **EG14: Doc discipline** | Lost decisions, repeated mistakes, no project memory | Backlog, issues, and ADRs updated every cycle |
 
-**Generic Agents** (Claude Code, Codex) — dev, qa, research, plan, devops, security — served from the PRISM network, never cached to disk
+**Governance Docs** — project management templates your AI assistant reads before every cycle:
 
-**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs)
+```
+.claude/docs/NORTH_STAR.md     Your vision, goals, and design principles
+.claude/docs/BACKLOG.md        Prioritised work with status tracking
+.claude/docs/ISSUES.md         Bug log and iteration tracker
+.claude/docs/adr/              Architectural Decision Records
+```
 
-**PRISM Network** — anonymous networked learning. Your AI tool fetches the latest methodology intelligence at cycle start, and optionally reports anonymous structural metadata at cycle end. Every user's cycles improve the methodology for everyone. Zero inference cost — your LLM does all compute.
+**Pipeline Agents** — research, dev, plan, qa, devops, security — fetched from the PRISM network so they're always up to date.
 
-## Commands
+**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs).
 
-```bash
-# Scaffold a new project
-npx syntropic init my-project
+## Track Record
 
-# Select specific tools
-npx syntropic init my-project --tools claude,cursor
+Built in production on a real product (27 AI agents, 8-lens analyser, CLI, 7 free tools) over 10 weeks:
 
-# Customise project URLs (optional — sensible defaults applied)
-npx syntropic init my-project --name "My App" --domain myapp.com --test-url /staging --prod-url /
+- **123 features shipped**, each through a structured pipeline
+- **12 test→production promotions** — every feature verified on test page first
+- **3 bug classes prevented** by specific EG rules before reaching users
+- **0 undetected production incidents** after methodology adoption
 
-# Add a tool to an existing project
-npx syntropic add cursor
-npx syntropic add windsurf copilot
+## Trust & Privacy
 
-# Run a local health check (EG1 pre-flight)
-npx syntropic health
+**Everything is local.** Your `.claude/` directory — rules, agents, governance docs — lives in your repo. It's yours.
 
-# Manage anonymous telemetry (opt-out, default on)
-npx syntropic telemetry status
-npx syntropic telemetry disable
-npx syntropic telemetry enable
+**Telemetry is optional.** PRISM collects anonymous structural metadata (cycle weight, file count, framework — never code, names, or content). Double-hashed before transmission. Default: on. Opt out anytime:
 
-# Submit a PRISM cycle report (CLI handles hashing + signing)
-npx syntropic report --weight lightweight --phases research,plan,dev,qa,test --success true --iterations 1
+```bash
+syntropic telemetry disable
 ```
 
-## Existing Projects
-
-Running `syntropic init` in a project that already has a `CLAUDE.md` or `.cursorrules` will **append** the methodology to your existing file — it never overwrites. A `<!-- syntropic -->` marker prevents duplicate rules on re-runs.
+**What's collected:** cycle weight, phases, success/failure, tool, OS, project shape.
+**Never collected:** file contents, names, code, diffs, commits, identity, API keys.
 
-## The Methodology
+**Clean exit.** Remove everything syntropic added (preserves your governance docs):
 
-The core idea: AI coding tools are powerful but undisciplined. Without rules, they jump straight to code, skip investigation, retry failed approaches, and introduce regressions.
-
-Syntropic gives them a process:
+```bash
+syntropic remove
+```
 
-1. **Research** — understand the problem before proposing solutions
-2. **Plan** — break work into sequenced steps, identify risks
-3. **Build** — implement with minimal changes, match existing patterns
-4. **Review** — check security, quality, and correctness
-5. **Verify** — test on a live URL, not just locally
+**Inspect the output.** Run `npm pack` on the package — everything that ships is plain text templates. The methodology is served from a public API endpoint you can curl yourself.
 
-Scale the process to the task. A typo fix doesn't need research. A new feature does.
+## Commands
 
-## Privacy
+```bash
+syntropic audit                    # Analyse git history (no install needed)
+syntropic init [project-name]      # Install methodology + docs
+syntropic add cursor windsurf      # Add tools to existing project
+syntropic remove                   # Clean uninstall (preserves docs)
+syntropic health                   # Run pre-flight checks
+syntropic report                   # Submit anonymous cycle report
+syntropic telemetry status         # Check telemetry setting
+syntropic analyse                  # Deep-dive analysis (8 philosophy lenses)
+```
 
-Syntropic collects pseudonymised usage patterns to improve the methodology for everyone. **Default: on (opt-out).**
+## How It Works
 
-**What is collected:** cycle weight, phases run, success/failure, iteration count, tool, OS, Node.js major version, project shape (has TypeScript/CI/tests, framework, file change bucket).
+Your instruction file contains a bootstrap rule (EG13) that fetches the full methodology from the PRISM network at cycle start. Rules, agents, and patterns are served fresh — always current, zero maintenance. Your LLM does all compute. Syntropic serves the methodology but runs zero inference.
 
-**What is NEVER collected:** file contents, file names, project names, code, diffs, commit messages, user identity, email, API keys.
+The governance docs give your AI assistant project memory — it checks priorities before coding and logs issues after. Over time, your docs become a structured record of every decision, bug, and iteration.
 
-**Pseudonymisation:** A random device ID is generated locally at install time. Before transmission, it is hashed client-side with a daily-rotating salt (`SHA-256(device_id + date)`), then hashed again server-side with a separate salt (`SHA-256(client_hash + server_salt)`). Neither the client hash nor the original device ID is stored server-side — only the double-hashed value, which cannot be reversed to identify a device or user. Inspired by [TelemetryDeck's MIT-licensed approach](https://telemetrydeck.com/docs/articles/anonymization-how-it-works/). GDPR-compliant by design.
+## Existing Projects
 
-Opt out anytime: `npx syntropic telemetry disable`
+Running `syntropic init` in a project that already has a `CLAUDE.md` or `.cursorrules` **appends** the methodology — never overwrites. A `<!-- syntropic -->` marker prevents duplicates.
 
-## Philosophy
+## Research
 
-- **Ship and iterate** — momentum over perfection
-- **Hypothesis-driven** — test before you code
-- **Outcome-aligned** — if the user succeeds, do we succeed?
-- **No workarounds** — no bypasses, no "fix later", no shortcuts without approval
+The methodology is grounded in published research: [zenodo.org/records/17894441](https://zenodo.org/records/17894441)
 
 ## Links
 
 - [Website](https://www.syntropicworks.com)
-- [GitHub](https://github.com/petercholford-ship-it/syntropic-cli)
-- [Research Paper](https://zenodo.org/records/17894441) — the underlying research behind the methodology
-- [Intelligent Analyser](https://www.syntropicworks.com/analyser) — deep-dive analysis through 8 philosophy lenses
+- [Intelligent Analyser](https://www.syntropicworks.com/analyser) — deep-dive product analysis through 8 philosophy lenses
 
 ## License
 

package/bin/syntropic.js

@@ -14,8 +14,10 @@ const args = process.argv.slice(2);
 const command = args[0];
 
 const COMMANDS = {
+  audit: () => require('../commands/audit'),
   init: () => require('../commands/init'),
   add: () => require('../commands/add'),
+  remove: () => require('../commands/remove'),
   health: () => require('../commands/health'),
   telemetry: () => require('../commands/telemetry'),
   report: () => require('../commands/report'),
@@ -39,8 +41,10 @@ if (!command || args.includes('--help') || args.includes('-h')) {
   syntropic — Philosophy-as-code development pipeline
 
   Usage:
+    syntropic audit                 Analyse your git history for process issues (no install needed)
     syntropic init [project-name]   Scaffold a new project with the Syntropic pipeline
     syntropic add <tool> [tool...]  Add support for another AI tool
+    syntropic remove                Remove syntropic from this project (preserves your docs)
     syntropic analyse               Analyse your product using 8 philosophy lenses
     syntropic login                 Sign in to Syntropic (required for analyse)
     syntropic logout                Sign out

package/commands/audit.js

@@ -0,0 +1,293 @@
+/**
+ * syntropic audit [--commits <n>]
+ *
+ * Analyse your git history for development process issues.
+ * Proves value on your own code before installing anything.
+ * Pure local analysis — sends nothing, requires nothing.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULTS = { commits: 20 };
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--help' || args[i] === '-h') { flags.help = true; continue; }
+    if (args[i].startsWith('--')) {
+      const key = args[i].replace('--', '');
+      flags[key] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
+    }
+  }
+  return flags;
+}
+
+function git(cmd) {
+  try {
+    return execSync(`git ${cmd}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function colour(text, code) {
+  if (!process.stdout.isTTY) return text;
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+
+const green = (t) => colour(t, '32');
+const yellow = (t) => colour(t, '33');
+const red = (t) => colour(t, '31');
+const dim = (t) => colour(t, '2');
+const bold = (t) => colour(t, '1');
+
+function checkLocalhost(n) {
+  // Find commits that introduced localhost/127.0.0.1 references
+  const log = git(`log --oneline -${n} --format=%H`);
+  if (!log) return { issues: 0, detail: '' };
+
+  const hashes = log.split('\n').filter(Boolean);
+  let hits = 0;
+  const examples = [];
+
+  for (const hash of hashes) {
+    const diff = git(`diff ${hash}~1 ${hash} -- . ":(exclude)*.lock" ":(exclude)node_modules" 2>/dev/null`);
+    if (!diff) continue;
+
+    const addedLines = diff.split('\n').filter(l => l.startsWith('+') && !l.startsWith('+++'));
+    for (const line of addedLines) {
+      if (/localhost|127\.0\.0\.1/.test(line) && !/\/\/.*localhost/.test(line.replace(/https?:\/\/localhost/, 'MATCH'))) {
+        hits++;
+        if (examples.length < 2) {
+          const shortHash = hash.slice(0, 7);
+          const subject = git(`log --format=%s -1 ${hash}`);
+          examples.push(`${shortHash} ${subject}`);
+        }
+        break; // Count once per commit
+      }
+    }
+  }
+
+  return {
+    issues: hits,
+    detail: examples.length ? examples.map(e => `    ${dim(e)}`).join('\n') : '',
+  };
+}
+
+function checkEnvFiles(n) {
+  // Check if .env files are tracked in git
+  const tracked = git('ls-files').split('\n');
+  const envFiles = tracked.filter(f => {
+    const base = path.basename(f);
+    // .env.example, .env.sample, .env.template are fine
+    return /^\.env($|\.)/.test(base) && !/\.(example|sample|template)$/.test(base);
+  });
+  return {
+    issues: envFiles.length,
+    detail: envFiles.length ? envFiles.map(f => `    ${dim(f)}`).join('\n') : '',
+  };
+}
+
+function checkCommitConventions(n) {
+  const log = git(`log --oneline -${n} --no-merges --format=%s`);
+  if (!log) return { conventional: 0, total: 0, pct: 0 };
+
+  const subjects = log.split('\n').filter(Boolean);
+  const conventional = subjects.filter(s => /^(feat|fix|refactor|chore|docs|style|perf|test|ci|build|revert|sync|content|debug|security|spec)(\(.+\))?:/.test(s));
+
+  return {
+    conventional: conventional.length,
+    total: subjects.length,
+    pct: subjects.length > 0 ? Math.round(conventional.length / subjects.length * 100) : 0,
+  };
+}
+
+function checkFixRatio(n) {
+  const log = git(`log --oneline -${n} --no-merges --format=%s`);
+  if (!log) return { feats: 0, fixes: 0, ratio: 0, total: 0 };
+
+  const subjects = log.split('\n').filter(Boolean);
+  const feats = subjects.filter(s => /^feat(\(.+\))?:/.test(s)).length;
+  const fixes = subjects.filter(s => /^fix(\(.+\))?:/.test(s)).length;
+  const total = subjects.length;
+
+  return { feats, fixes, ratio: total > 0 ? Math.round(fixes / total * 100) : 0, total };
+}
+
+function checkFilesPerCommit(n) {
+  const log = git(`log --oneline -${n} --no-merges --format=%H`);
+  if (!log) return { avg: 0, max: 0 };
+
+  const hashes = log.split('\n').filter(Boolean);
+  const counts = hashes.map(h => {
+    const files = git(`diff --name-only ${h}~1 ${h} 2>/dev/null`);
+    return files ? files.split('\n').filter(Boolean).length : 0;
+  }).filter(c => c > 0);
+
+  if (counts.length === 0) return { avg: 0, max: 0 };
+
+  return {
+    avg: Math.round(counts.reduce((a, b) => a + b, 0) / counts.length * 10) / 10,
+    max: Math.max(...counts),
+  };
+}
+
+function checkGovernanceDocs() {
+  const cwd = process.cwd();
+  const docs = {
+    north_star: fs.existsSync(path.join(cwd, '.claude', 'docs', 'NORTH_STAR.md')) || fs.existsSync(path.join(cwd, '.claude', 'NORTH_STAR.md')),
+    backlog: fs.existsSync(path.join(cwd, '.claude', 'docs', 'BACKLOG.md')),
+    issues: fs.existsSync(path.join(cwd, '.claude', 'docs', 'ISSUES.md')),
+    adr: fs.existsSync(path.join(cwd, '.claude', 'docs', 'adr')),
+  };
+  const count = Object.values(docs).filter(Boolean).length;
+  return { count, total: 4, docs };
+}
+
+function computeScore(results) {
+  let score = 5; // Start at 5/10
+
+  // Localhost issues: -1 per issue, max -2
+  score -= Math.min(results.localhost.issues, 2);
+
+  // Env files tracked: -2 if any
+  if (results.envFiles.issues > 0) score -= 2;
+
+  // Conventional commits: +1 if >70%, +0.5 if >40%
+  if (results.conventions.pct >= 70) score += 1;
+  else if (results.conventions.pct >= 40) score += 0.5;
+
+  // Fix ratio: neutral if 30-50%, -0.5 if >60%
+  if (results.fixRatio.ratio > 60) score -= 0.5;
+
+  // Governance docs: +0.5 per doc present
+  score += results.governance.count * 0.5;
+
+  // Avg files per commit: -0.5 if >15 (giant commits)
+  if (results.filesPerCommit.avg > 15) score -= 0.5;
+
+  return Math.max(0, Math.min(10, Math.round(score * 2) / 2));
+}
+
+function run(args) {
+  const flags = parseFlags(args);
+
+  if (flags.help) {
+    console.log(`
+  syntropic audit — Analyse your git history for process issues
+
+  Usage:
+    syntropic audit [options]
+    npx syntropic audit              (no install needed)
+
+  Options:
+    --commits <n>   Number of recent commits to analyse (default: 20)
+
+  What it checks:
+    - Localhost/127.0.0.1 references committed to repo
+    - .env files tracked in git
+    - Commit message conventions
+    - Fix:feature ratio (iteration indicator)
+    - Average files per commit (scope discipline)
+    - Governance docs (North Star, Backlog, Issues, ADRs)
+
+  This is a local-only analysis. Nothing is sent anywhere.
+`);
+    return;
+  }
+
+  // Check we're in a git repo
+  const gitRoot = git('rev-parse --show-toplevel');
+  if (!gitRoot) {
+    console.error('\n  Not a git repository. Run this from a project with git history.\n');
+    process.exit(1);
+  }
+
+  const n = parseInt(flags.commits, 10) || DEFAULTS.commits;
+  const commitCount = git('rev-list --count HEAD');
+  const actualN = Math.min(n, parseInt(commitCount, 10) || n);
+
+  console.log(`\n  ${bold('syntropic audit')} — last ${actualN} commits\n`);
+
+  // Run all checks
+  const results = {
+    localhost: checkLocalhost(actualN),
+    envFiles: checkEnvFiles(actualN),
+    conventions: checkCommitConventions(actualN),
+    fixRatio: checkFixRatio(actualN),
+    filesPerCommit: checkFilesPerCommit(actualN),
+    governance: checkGovernanceDocs(),
+  };
+
+  const score = computeScore(results);
+
+  // Display results
+  const PAD = 24;
+
+  // EG1: Localhost
+  if (results.localhost.issues > 0) {
+    console.log(`  ${yellow('⚠')} ${'EG1  Pre-flight'.padEnd(PAD)} ${yellow(`${results.localhost.issues} commit${results.localhost.issues > 1 ? 's' : ''} contain localhost references`)}`);
+    if (results.localhost.detail) console.log(results.localhost.detail);
+  } else {
+    console.log(`  ${green('✓')} ${'EG1  Pre-flight'.padEnd(PAD)} ${green('No localhost references found')}`);
+  }
+
+  // EG10: Env files
+  if (results.envFiles.issues > 0) {
+    console.log(`  ${red('✗')} ${'EG10 Env hygiene'.padEnd(PAD)} ${red(`${results.envFiles.issues} .env file${results.envFiles.issues > 1 ? 's' : ''} tracked in git`)}`);
+    if (results.envFiles.detail) console.log(results.envFiles.detail);
+  } else {
+    console.log(`  ${green('✓')} ${'EG10 Env hygiene'.padEnd(PAD)} ${green('No .env files tracked')}`);
+  }
+
+  // Commit conventions
+  const convPct = results.conventions.pct;
+  const convIcon = convPct >= 70 ? green('✓') : convPct >= 40 ? yellow('⚠') : red('✗');
+  const convColour = convPct >= 70 ? green : convPct >= 40 ? yellow : red;
+  console.log(`  ${convIcon} ${'Commit discipline'.padEnd(PAD)} ${convColour(`${convPct}% conventional commits`)} ${dim(`(${results.conventions.conventional}/${results.conventions.total})`)}`);
+
+  // Fix ratio
+  const fixPct = results.fixRatio.ratio;
+  const fixIcon = fixPct <= 50 ? green('✓') : yellow('⚠');
+  const fixColour = fixPct <= 50 ? green : yellow;
+  console.log(`  ${fixIcon} ${'Fix ratio'.padEnd(PAD)} ${fixColour(`${fixPct}% of commits are fixes`)} ${dim(`(${results.fixRatio.fixes} fixes, ${results.fixRatio.feats} features)`)}`);
+
+  // Files per commit
+  const avgFiles = results.filesPerCommit.avg;
+  const filesIcon = avgFiles <= 10 ? green('✓') : avgFiles <= 15 ? yellow('⚠') : red('✗');
+  const filesColour = avgFiles <= 10 ? green : avgFiles <= 15 ? yellow : red;
+  console.log(`  ${filesIcon} ${'Scope discipline'.padEnd(PAD)} ${filesColour(`${avgFiles} avg files/commit`)} ${dim(`(max: ${results.filesPerCommit.max})`)}`);
+
+  // Governance docs
+  const govCount = results.governance.count;
+  const govIcon = govCount >= 3 ? green('✓') : govCount >= 1 ? yellow('⚠') : dim('○');
+  const govColour = govCount >= 3 ? green : govCount >= 1 ? yellow : dim;
+  const govNames = [];
+  if (results.governance.docs.north_star) govNames.push('North Star');
+  if (results.governance.docs.backlog) govNames.push('Backlog');
+  if (results.governance.docs.issues) govNames.push('Issues');
+  if (results.governance.docs.adr) govNames.push('ADRs');
+  console.log(`  ${govIcon} ${'Governance docs'.padEnd(PAD)} ${govColour(`${govCount}/4 present`)} ${dim(govNames.length ? `(${govNames.join(', ')})` : '(none)')}`);
+
+  // Score
+  console.log('');
+  const scoreColour = score >= 7 ? green : score >= 4 ? yellow : red;
+  console.log(`  ${bold('Score:')} ${scoreColour(`${score}/10`)}`);
+
+  // Recommendation
+  console.log('');
+  if (score >= 8) {
+    console.log(`  ${green('Strong development discipline.')} Syntropic can keep it that way.`);
+  } else if (score >= 5) {
+    console.log(`  ${yellow('Room for improvement.')} Common issues that a structured pipeline prevents.`);
+  } else {
+    console.log(`  ${red('Significant process gaps.')} A development methodology would catch these early.`);
+  }
+
+  console.log(`\n  ${dim('Run `syntropic init` to install the methodology and prevent these automatically.')}`);
+  console.log(`  ${dim('Learn more: https://www.syntropicworks.com')}\n`);
+}
+
+module.exports = run;