syntropic 0.8.1 → 0.9.1

package/README.md

@@ -1,127 +1,127 @@
 # 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:
+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.
 
-| Tool | File Generated |
-|------|---------------|
-| Claude Code | `CLAUDE.md` |
-| Cursor | `.cursorrules` |
-| Windsurf | `.windsurfrules` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| OpenAI Codex | `AGENTS.md` |
+## What You Get
 
-## How It Works
+**Evergreen Rules** — battle-tested development rules fetched fresh at every cycle:
 
-**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.
+| 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 |
 
-Your LLM does all the compute. Syntropic serves the methodology but runs zero inference. Your data stays on your machine.
+**Governance Docs** — project management templates your AI assistant reads before every cycle:
 
-## What You Get
+```
+.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
+```
 
-**Evergreen Rules (EG1-EG13)** — fetched at runtime from the PRISM network:
+**Pipeline Agents** — research, dev, plan, qa, devops, security — fetched from the PRISM network so they're always up to date.
 
-- **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
+**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs).
 
-**Generic Agents** (Claude Code, Codex) — dev, qa, research, plan, devops, security — served from the PRISM network, never cached to disk
+## Track Record
 
-**Health Check** — daily GitHub Action with auto-remediation (npm audit fix PRs)
+Built in production on a real product (27 AI agents, 8-lens analyser, CLI, 7 free tools) over 10 weeks:
 
-**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.
+- **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
 
-## Commands
+## Trust & Privacy
 
-```bash
-# Scaffold a new project
-npx syntropic init my-project
+**Everything is local.** Your `.claude/` directory — rules, agents, governance docs — lives in your repo. It's yours.
 
-# Select specific tools
-npx syntropic init my-project --tools claude,cursor
+**Telemetry is metadata only.** PRISM learns from anonymous structural metadata about development cycles — never from your code, file contents, or project details. This metadata is what drives methodology improvements: which cycle weights work best for which project shapes, where pipelines break down, what patterns lead to first-pass success.
 
-# Customise project URLs (optional — sensible defaults applied)
-npx syntropic init my-project --name "My App" --domain myapp.com --test-url /staging --prod-url /
+**What's collected:** cycle weight, phases run, success/failure, tool used, OS, framework detected, file count bucket (1-5 / 6-20 / 21+), governance doc presence.
+**Never collected:** file contents, file names, code, diffs, commit messages, project names, identity, API keys.
 
-# Add a tool to an existing project
-npx syntropic add cursor
-npx syntropic add windsurf copilot
+**Why it matters.** The PRISM network grows exponentially with contributors. Every anonymous report adds signal — which cycle weights work for which project shapes, where pipelines break down, what patterns lead to first-pass success. More contributors = better data = smarter rules for everyone.
 
-# Run a local health check (EG1 pre-flight)
-npx syntropic health
+**Contributors get more.** When telemetry is enabled, your PRISM sync fetches live network benchmarks — real success rates, iteration counts, and pattern intelligence computed from aggregate data across all contributors. When telemetry is disabled, you still get the full EG rules and agents, but benchmarks are static baselines only. No account needed — your identity is a double-hashed device fingerprint ([pseudonymisation details](https://zenodo.org/records/17894441)).
 
-# Manage anonymous telemetry (opt-out, default on)
-npx syntropic telemetry status
-npx syntropic telemetry disable
-npx syntropic telemetry enable
+| | Community (telemetry off) | Contributor (telemetry on) |
+|---|---|---|
+| EG rules | Full | Full |
+| Pipeline agents | Full | Full |
+| Governance docs | Full | Full |
+| Benchmarks | Static baselines | **Live network data** |
+| Pattern intelligence | Frozen snapshot | **Updated from aggregate reports** |
+| Network benefit | None | **Your reports improve rules for everyone** |
 
-# Submit a PRISM cycle report (CLI handles hashing + signing)
-npx syntropic report --weight lightweight --phases research,plan,dev,qa,test --success true --iterations 1
-```
+Default: on. Opt out anytime:
 
-## 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.
-
-## The Methodology
+```bash
+syntropic telemetry disable
+```
 
-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.
+**Clean exit.** Remove everything syntropic added (preserves your governance docs):
 
-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](https://www.syntropicworks.com/api/v1/prism/config) 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;

package/commands/init.js

@@ -186,6 +186,51 @@ function detectTools(targetDir) {
   return detected;
 }
 
+function scaffoldDocs(targetDir, projectName) {
+  const docsDir = path.join(targetDir, '.claude', 'docs');
+  const adrDir = path.join(docsDir, 'adr');
+  const docsTemplateDir = path.join(TEMPLATES_DIR, 'docs');
+
+  // Skip if docs dir already exists with content
+  if (fs.existsSync(docsDir)) {
+    const existing = fs.readdirSync(docsDir).filter(f => !f.startsWith('.'));
+    if (existing.length > 0) {
+      console.log(`  skip  .claude/docs/ (already exists with ${existing.length} items)`);
+      return;
+    }
+  }
+
+  if (!fs.existsSync(docsTemplateDir)) return;
+
+  fs.mkdirSync(adrDir, { recursive: true });
+
+  const today = new Date().toISOString().slice(0, 10);
+  const replacements = {
+    '\\{\\{PROJECT_NAME\\}\\}': projectName,
+    '\\{\\{CREATED_DATE\\}\\}': today,
+  };
+
+  // Copy doc templates, renaming .template to .md
+  const docFiles = [
+    { src: 'NORTH_STAR.template', dest: path.join(docsDir, 'NORTH_STAR.md') },
+    { src: 'BACKLOG.template', dest: path.join(docsDir, 'BACKLOG.md') },
+    { src: 'ISSUES.template', dest: path.join(docsDir, 'ISSUES.md') },
+    { src: path.join('adr', '000-TEMPLATE.template'), dest: path.join(adrDir, '000-TEMPLATE.md') },
+  ];
+
+  for (const { src, dest } of docFiles) {
+    const srcPath = path.join(docsTemplateDir, src);
+    if (!fs.existsSync(srcPath)) continue;
+
+    let content = fs.readFileSync(srcPath, 'utf8');
+    for (const [key, value] of Object.entries(replacements)) {
+      content = content.replace(new RegExp(key, 'g'), () => value);
+    }
+    fs.writeFileSync(dest, content, 'utf8');
+    console.log(`  create  ${path.relative(process.cwd(), dest)}`);
+  }
+}
+
 async function run(args) {
   console.log('\n  syntropic init — Philosophy-as-code development pipeline\n');
 
@@ -261,6 +306,9 @@ async function run(args) {
     actions[tool] = writeOrAppend(fullTpl, appendTpl, destPath, replacements);
   }
 
+  // Scaffold governance docs (.claude/docs/)
+  scaffoldDocs(targetDir, projectName);
+
   // Make health check executable
   const healthScript = path.join(targetDir, 'scripts', 'health-check.js');
   if (fs.existsSync(healthScript)) {
@@ -288,6 +336,7 @@ async function run(args) {
 
   What was created:
 ${toolFiles}
+    .claude/docs/                       Project governance docs (North Star, Backlog, Issues, ADRs)
     .github/workflows/                  Daily health check with auto-remediation
     scripts/health-check.js             Local health check script${hookLine}
 
@@ -299,23 +348,26 @@ ${toolFiles}
     agents, and learning data are always up to date — zero local files to
     maintain. All compute runs on your machine.
 
-  Next steps:
-    1. Review your instruction file and add project-specific context
-    2. Start building! Your AI will follow the EG7 pipeline automatically
+  Your governance docs:
+    .claude/docs/NORTH_STAR.md    Define your vision, goals, and principles
+    .claude/docs/BACKLOG.md       Prioritise and track your work
+    .claude/docs/ISSUES.md        Log bugs and track iterations
+    .claude/docs/adr/             Record architectural decisions
 
-  Telemetry:
-    Syntropic collects pseudonymised usage patterns to improve the methodology
-    for everyone. All identifiers are double-hashed before transmission — no
-    device ID, code, file names, or personal data is ever stored server-side.
-    Run \`syntropic telemetry disable\` to opt out at any time.
+    These are YOUR docs — they stay even if you remove syntropic.
+    Your AI reads them before every cycle and updates them after.
 
-  The methodology is your superpower. Ship and iterate.
+  Next steps:
+    1. Fill in your North Star — vision, mission, and goals
+    2. Review your instruction file and add project-specific context
+    3. Start building! Your AI follows the EG7 pipeline automatically
 
-  Coming soon: \`syntropic analyse\` — assess market opportunity,
-  validate assumptions, and get a strategic way forward, all from
-  your CLI. Your LLM, your compute, powered by 8 philosophy lenses.
+  Trust & privacy:
+    Everything in .claude/ is local and yours. PRISM telemetry is
+    pseudonymised (double-hashed) and opt-out: \`syntropic telemetry disable\`.
+    Remove everything: \`syntropic remove\` (preserves your docs).
 
-  Try the web version now: syntropicworks.com/analyser
+  Run \`syntropic audit\` to see what this methodology catches on your existing code.
 
   Learn more: https://www.syntropicworks.com
 `);