faf-mcp 2.3.1 → 3.0.0

package/dist/src/handlers/tools.js

@@ -206,9 +206,9 @@ class FafToolHandler {
             },
             {
                 name: 'faf_sync',
-                description: 'Sync a project.faf with CLAUDE.md so the two stay aligned. Returns what was written. Use this for the single CLAUDE.md target; use faf_bi_sync to fan out to AGENTS.md, .cursorrules, and GEMINI.md as well.',
+                description: 'Reconcile project.faf with what the repo manifests say now (package.json name, description, framework dependencies). Dry-run by default: reports the fields that would change. Pass apply:true to write them into project.faf. Does not touch CLAUDE.md — use faf_bi_sync for CLAUDE.md, AGENTS.md, .cursorrules and GEMINI.md.',
                 annotations: {
-                    title: 'Sync .faf to CLAUDE.md',
+                    title: 'Reconcile .faf with repo manifests',
                     readOnlyHint: false,
                     destructiveHint: false,
                     openWorldHint: false
@@ -216,6 +216,7 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
+                        apply: { type: 'boolean', description: 'Write the detected changes into project.faf (default: dry-run report only)' },
                         path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
                     },
                     additionalProperties: false
@@ -223,9 +224,9 @@ class FafToolHandler {
             },
             {
                 name: 'faf_bi_sync',
-                description: 'Bi-directionally sync a project.faf with CLAUDE.md and, with the format flags or all, also AGENTS.md, .cursorrules, and GEMINI.md. Returns the formats written and any conflicts. Use this to keep every AI tool context file aligned from the single .faf source.',
+                description: 'Write CLAUDE.md from project.faf (one direction: .faf → CLAUDE.md) and, with the format flags or all, also AGENTS.md, .cursorrules and GEMINI.md. Content outside the faf-managed block is preserved. Returns the files written. Use this to keep every AI tool\'s context file current from one source.',
                 annotations: {
-                    title: 'Bi-directional Sync',
+                    title: 'Sync .faf to CLAUDE.md and IDE formats',
                     readOnlyHint: false,
                     destructiveHint: false,
                     openWorldHint: false
@@ -233,9 +234,6 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        auto: { type: 'boolean', description: 'Enable automatic synchronization' },
-                        watch: { type: 'boolean', description: 'Start real-time file watching for changes' },
-                        force: { type: 'boolean', description: 'Force overwrite conflicting changes' },
                         agents: { type: 'boolean', description: 'Also sync to AGENTS.md (OpenAI/Codex format)' },
                         cursor: { type: 'boolean', description: 'Also sync to .cursorrules (Cursor IDE format)' },
                         gemini: { type: 'boolean', description: 'Also sync to GEMINI.md (Google Gemini format)' },
@@ -247,7 +245,7 @@ class FafToolHandler {
             },
             {
                 name: 'faf_clear',
-                description: 'Clear caches, temporary files, and reset FAF state for a fresh start',
+                description: 'Remove the ~/.faf-cli-cache directory left by older faf-mcp versions. This version persists nothing outside your project files.',
                 annotations: {
                     title: 'Clear .faf Data',
                     readOnlyHint: false,
@@ -257,17 +255,15 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        cache: { type: 'boolean', description: 'Clear trust cache only' },
-                        todos: { type: 'boolean', description: 'Clear todo lists only' },
-                        backups: { type: 'boolean', description: 'Clear backup files only' },
-                        all: { type: 'boolean', description: 'Clear everything (default)' }
+                        cache: { type: 'boolean', description: 'Remove ~/.faf-cli-cache (written by faf-mcp < 3.0)' },
+                        all: { type: 'boolean', description: 'Remove everything older versions persisted (default; today that is the cache)' }
                     },
                     additionalProperties: false
                 }
             },
             {
                 name: 'faf_debug',
-                description: 'Debug faf-mcp environment - show working directory, permissions, and FAF CLI status',
+                description: 'Debug faf-mcp environment - show working directory, write permissions, the bundled faf-cli version, and whether a project.faf is present',
                 annotations: {
                     title: 'Debug Info',
                     readOnlyHint: true,
@@ -486,8 +482,10 @@ class FafToolHandler {
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' },
-                        force: { type: 'boolean', description: 'Force overwrite existing files' }
+                        path: { type: 'string', description: 'Project path. Sets session context for subsequent calls.' }
+                        // `force` used to be declared here; handleFafAuto never read it.
+                        // faf_auto merges into an existing project.faf non-destructively
+                        // and there is no overwrite mode to switch on.
                     },
                     additionalProperties: false
                 }
@@ -868,7 +866,7 @@ class FafToolHandler {
         // Headline carries both `/100` AND `(%)` so multiple matchers stay happy.
         let output = `FAF SCORE: ${score}/100 (${score}%)  ${tierDisplay}\n` +
             `${progressBar} ${score}%\n` +
-            `${result.populated}/${result.total} slots populated` +
+            `${result.populated}/${result.active} slots populated` +
             (nextTierDisplay ? `  ·  next: ${nextTierDisplay}` : '  ·  top tier') +
             `\n\n` +
             `Scored by faf-cli — the same context your AI reads.`;
@@ -977,7 +975,7 @@ package_manager: ${projectData.package_manager}` : ''}
             return {
                 content: [{
                         type: 'text',
-                        text: `🚀 Claude FAF Initialization:\n\n✅ Created project.faf\n\n${pathConfirmation}${sourceExplanation}\n\n🍊 Vitamin Context activated!\n⚡ FAFFLESS AI ready!${chromeDetection.detected ? '\n\n🎯 Friday Feature: Chrome Extension detected!\n📈 Auto-filled 7 slots for 90%+ score!' : ''}${chromeDetection.corrected ? `\n📝 Auto-corrected: "${args?.description}" → "${chromeDetection.corrected}"` : ''}\n\n🏁 Next steps:\n  • Run faf_score for AI-readiness score\n  • Run faf_sync to create CLAUDE.md\n  • Run faf_enhance to improve context`
+                        text: `🚀 Claude FAF Initialization:\n\n✅ Created project.faf\n\n${pathConfirmation}${sourceExplanation}\n\n🍊 Vitamin Context activated!\n⚡ FAFFLESS AI ready!${chromeDetection.detected ? '\n\n🎯 Friday Feature: Chrome Extension detected!\n📈 Auto-filled 7 slots for 90%+ score!' : ''}${chromeDetection.corrected ? `\n📝 Auto-corrected: "${args?.description}" → "${chromeDetection.corrected}"` : ''}\n\n🏁 Next steps:\n  • Run faf_score for AI-readiness score\n  • Run faf_bi_sync to create CLAUDE.md\n  • Run faf_go to fill the gaps`
                     }]
             };
         }
@@ -991,25 +989,65 @@ package_manager: ${projectData.package_manager}` : ''}
             };
         }
     }
+    /**
+     * v3.0: was `this.engineAdapter.callEngine('trust')` — no bundled 'trust'
+     * branch exists in engine-adapter.ts, so this fell straight through to
+     * the ambient-PATH shell-out fallback (`which faf`, then execAsync).
+     * faf-cli itself has no `trust` subcommand at all — on any host where an
+     * unrelated `faf`-named binary sits first on PATH (verified live on this
+     * machine: Rust "FAFb"), this either hard-errors on an "unrecognized
+     * subcommand" or, worse, silently "succeeds" with that tool's own output.
+     * Rewired onto the bundled faf-cli bridge — bundled faf-cli only, never
+     * ambient PATH — composing `validateFaf` (structural integrity) +
+     * `scoreFafYaml` (trust metrics) directly, matching the tool's own
+     * description ("structural integrity and field consistency... trust
+     * metrics"). No CLI subcommand to shell out to even exists for this.
+     */
     async handleFafTrust(_args) {
-        const result = await this.engineAdapter.callEngine('trust');
-        if (!result.success) {
+        const cwd = this.getProjectPath();
+        const { findFafFile: findFaf, readFaf, readFafRaw, validateFaf, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+        const fafPath = findFaf(cwd);
+        if (!fafPath) {
             return {
                 content: [{
                         type: 'text',
-                        text: `🔒 Claude FAF Trust Validation:\n\nFailed to check trust: ${result.error}`
+                        text: `🔒 Claude FAF Trust Validation:\n\n❌ No .faf found in ${cwd}\n💡 Run faf_init to create one — then faf_trust reports real trust metrics.`
+                    }]
+            };
+        }
+        let raw;
+        let data;
+        try {
+            raw = readFafRaw(fafPath);
+            data = readFaf(fafPath);
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🔒 Claude FAF Trust Validation:\n\n❌ Could not read ${fafPath}: ${error?.message ?? String(error)}`
                     }],
                 isError: true
             };
         }
-        const output = typeof result.data === 'string'
-            ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
+        const validation = validateFaf(data);
+        let output = validation.valid
+            ? `✅ Structurally sound — no malformed, missing, or contradictory fields found.`
+            : `❌ ${validation.errors.length} issue${validation.errors.length === 1 ? '' : 's'} found:\n` +
+                validation.errors.map((e) => `   • ${e}`).join('\n');
+        try {
+            const score = scoreFafYaml(raw);
+            output += `\n\n📊 ${score.score}/100 (${score.populated}/${score.active} slots populated) — ${score.tier.name}`;
+        }
+        catch {
+            // Score is a bonus signal here; a validation-only result is still honest.
+        }
         return {
             content: [{
                     type: 'text',
                     text: `🔒 Claude FAF Trust Validation:\n\n${output}`
-                }]
+                }],
+            isError: !validation.valid
         };
     }
     async handleFafSync(args) {
@@ -1017,7 +1055,9 @@ package_manager: ${projectData.package_manager}` : ''}
         if (args?.path) {
             this.getProjectPath(args.path);
         }
-        const result = await this.engineAdapter.callEngine('sync');
+        // `apply` maps to the bundled sync command's --auto; without it the
+        // command only reports what would change.
+        const result = await this.engineAdapter.callEngine('sync', args?.apply ? ['--auto'] : []);
         if (!result.success) {
             return {
                 content: [{
@@ -1042,15 +1082,23 @@ package_manager: ${projectData.package_manager}` : ''}
         if (args?.path) {
             this.getProjectPath(args.path);
         }
+        // auto / watch / force used to be declared here too; none of them was
+        // ever read by syncBiDirectional, so the schema no longer promises them.
         const biSyncArgs = [];
-        if (args?.auto) {
-            biSyncArgs.push('--auto');
+        // v3.0 fix: the tool's own schema advertises agents/cursor/gemini/all,
+        // but they were never forwarded to engine-adapter's bi-sync dispatch —
+        // faf_bi_sync silently ignored them and only ever wrote CLAUDE.md.
+        if (args?.agents) {
+            biSyncArgs.push('--agents');
         }
-        if (args?.watch) {
-            biSyncArgs.push('--watch');
+        if (args?.cursor) {
+            biSyncArgs.push('--cursor');
         }
-        if (args?.force) {
-            biSyncArgs.push('--force');
+        if (args?.gemini) {
+            biSyncArgs.push('--gemini');
+        }
+        if (args?.all) {
+            biSyncArgs.push('--all');
         }
         const result = await this.engineAdapter.callEngine('bi-sync', biSyncArgs);
         if (!result.success) {
@@ -1072,37 +1120,46 @@ package_manager: ${projectData.package_manager}` : ''}
                 }]
         };
     }
+    /**
+     * v3.0: was `this.engineAdapter.callEngine('clear', clearArgs)` — no
+     * bundled 'clear' branch exists in engine-adapter.ts, so this fell
+     * straight through to the ambient-PATH shell-out fallback. Worse: even
+     * when a real faf-cli WAS first on PATH, its actual `clear` subcommand
+     * only clears `faf-git-*` temp directories from the OS tmpdir (see
+     * ~/FAF/cli/src/commands/clear.ts) — entirely unrelated to this tool's
+     * own cache/todos/backups semantics. There was never a correct backing
+     * implementation for this tool's contract, on any PATH.
+     *
+     * Rewired as a genuinely local operation — no CLI dependency, bundled or
+     * ambient, at all. `cache` clears the one real cache path this codebase
+     * writes (~/.faf-cli-cache, faf-core/utils/technical-credit.ts). The
+     * schema used to advertise `todos` and `backups` as well; no persisted todo
+     * list or backup-file store exists anywhere in faf-mcp, so those flags are
+     * gone rather than answered with a made-up "cleared".
+     */
     async handleFafClear(args) {
-        const clearArgs = [];
-        if (args?.cache) {
-            clearArgs.push('--cache');
-        }
-        if (args?.todos) {
-            clearArgs.push('--todos');
-        }
-        if (args?.backups) {
-            clearArgs.push('--backups');
-        }
-        if (args?.all || (!args?.cache && !args?.todos && !args?.backups)) {
-            clearArgs.push('--all');
-        }
-        const result = await this.engineAdapter.callEngine('clear', clearArgs);
-        if (!result.success) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `🧹 Claude FAF Clear:\n\nFailed to clear: ${result.error}`
-                    }],
-                isError: true
-            };
+        const wantCache = !!args?.cache;
+        const wantAll = !!args?.all || !wantCache;
+        const lines = [];
+        if (wantCache || wantAll) {
+            // HOME/USERPROFILE first (Node's own os.homedir() precedence; Bun's ignores a
+            // runtime override) so a test can redirect the home dir instead of
+            // deleting from the developer's real one.
+            const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+            const cacheDir = pathModule.join(home, '.faf-cli-cache');
+            const creditCache = pathModule.join(cacheDir, 'technical-credit.json');
+            if (fs.existsSync(creditCache)) {
+                fs.rmSync(creditCache, { force: true });
+                lines.push(`✅ cache: cleared ${creditCache}`);
+            }
+            else {
+                lines.push('✅ cache: nothing to clear');
+            }
         }
-        const output = typeof result.data === 'string'
-            ? result.data
-            : result.data?.output || JSON.stringify(result.data, null, 2);
         return {
             content: [{
                     type: 'text',
-                    text: `🧹 Claude FAF Clear:\n\n${output}`
+                    text: `🧹 Claude FAF Clear:\n\n${lines.join('\n')}`
                 }]
         };
     }
@@ -1180,18 +1237,15 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
         try {
             const fs = await import('fs');
             const path = await import('path');
-            const { exec } = await import('child_process');
-            const { promisify } = await import('util');
-            const _execAsync = promisify(exec);
             const cwd = this.engineAdapter.getWorkingDirectory();
             const debugInfo = {
                 workingDirectory: cwd,
                 canWrite: false,
-                fafCliPath: null,
-                fafVersion: null,
+                // Every tool runs on the faf-cli bundled in node_modules — report
+                // that, not whatever `which faf` happens to find on PATH.
+                fafVersion: (0, faf_cli_bridge_js_1.bundledFafCliVersion)(),
                 permissions: {},
                 enginePath: this.engineAdapter.getEnginePath(),
-                pathEnv: process.env.PATH?.split(':') || []
             };
             // Check write permissions
             try {
@@ -1203,21 +1257,6 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
             catch (error) {
                 debugInfo.permissions.writeError = error instanceof Error ? error.message : String(error);
             }
-            // Check FAF CLI availability using championship auto-detection
-            try {
-                const cliInfo = this.engineAdapter.getCliInfo();
-                if (cliInfo.detected && cliInfo.path) {
-                    debugInfo.fafCliPath = cliInfo.path;
-                    debugInfo.fafVersion = cliInfo.version || null;
-                }
-                else {
-                    debugInfo.fafCliPath = null;
-                    debugInfo.fafVersion = null;
-                }
-            }
-            catch (error) {
-                debugInfo.permissions.fafError = error instanceof Error ? error.message : String(error);
-            }
             // Check for existing FAF file (v1.2.0: project.faf, *.faf, or .faf)
             const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
             const hasFaf = fafResult !== null;
@@ -1226,15 +1265,12 @@ REMEMBER: Always use ".faf" with the dot - it's a FORMAT!
 📂 Working Directory: ${debugInfo.workingDirectory}
 ✏️ Write Permissions: ${debugInfo.canWrite ? '✅ Yes' : '❌ No'}
 ${debugInfo.permissions.writeError ? `   Error: ${debugInfo.permissions.writeError}\n` : ''}🤖 FAF Engine Path: ${debugInfo.enginePath}
-🏎️ FAF CLI Path: ${debugInfo.fafCliPath || '❌ Not found'}
-📋 FAF Version: ${debugInfo.fafVersion || 'Unknown'}
-${debugInfo.permissions.fafError ? `   FAF Error: ${debugInfo.permissions.fafError}\n` : ''}📄 FAF File: ${hasFaf ? `✅ ${fafResult.filename} exists` : '❌ Not found (run faf_init)'}
-🛤️ System PATH: ${debugInfo.pathEnv.slice(0, 3).join(', ')}${debugInfo.pathEnv.length > 3 ? '...' : ''}
+📋 faf-cli (bundled): ${debugInfo.fafVersion ? `v${debugInfo.fafVersion}` : '❌ not found in node_modules — reinstall faf-mcp'}
+📄 FAF File: ${hasFaf ? `✅ ${fafResult.filename} exists` : '❌ Not found (run faf_init)'}
 
 💡 Quick Start:
-   1. If FAF CLI not found: npm install -g faf-cli
-   2. If .faf file missing: use faf_init tool
-   3. For optimization: use faf_enhance tool with model="claude"
+   1. If .faf file missing: use faf_init or faf_auto
+   2. To check AI-readiness: use faf_score
 `;
             return {
                 content: [{
@@ -1780,7 +1816,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             // they're SOURCED by Turbo-Cat (faf-cli's separate STACK_INTERVIEW if ever
             // needed), never asked of a human. (Decision: single-source the 8-Q 6Ws
             // Interview, wolfejam 2026-06-10 — language is not on the human side.)
-            const { SIX_WS_INTERVIEW } = await faf_cli_bridge_js_1.fafCli;
+            const { SIX_WS_INTERVIEW, isPlaceholder, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
             const QUESTION_REGISTRY = Object.fromEntries(SIX_WS_INTERVIEW.map((q) => [q.path, q]));
             // Priority order for questions
             const priorityOrder = [
@@ -1825,16 +1861,18 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                 }
                 current[parts[parts.length - 1]] = value;
             };
-            // Check if value is empty/placeholder
-            const isEmpty = (value) => {
-                return value === undefined ||
-                    value === null ||
-                    value === '' ||
-                    value === 'Unknown' ||
-                    value === 'TBD' ||
-                    value === 'None' ||
-                    (typeof value === 'string' && value.toLowerCase().includes('placeholder'));
-            };
+            // Empty = what the scorer calls empty. faf-cli's isPlaceholder is the one
+            // rule the kernel scores by; a local list ('TBD', 'Unknown', ...) drifted
+            // from it in both directions and made faf_go's numbers disagree with
+            // faf_score on the same file. slotignored is inactive, never asked.
+            const isEmpty = (value) => isPlaceholder(value) && value !== 'slotignored';
+            // One score function, period: the real scorer on the real bytes.
+            const scoreOf = (raw) => scoreFafYaml(raw).score;
+            const tierLabel = (score) => score >= 100 ? '✪ Trophy — 100% AI-Readiness' :
+                score >= 99 ? '★ Gold' :
+                    score >= 95 ? '◆ Silver' :
+                        score >= 85 ? '◇ Bronze — production ready' :
+                            score >= 70 ? '● Green — solid foundation' : '📈 Keep going!';
             // PHASE 2: Apply answers if provided
             if (args?.answers && typeof args.answers === 'object') {
                 const answers = args.answers;
@@ -1845,15 +1883,10 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                         appliedCount++;
                     }
                 }
-                // Write updated file
+                // Write updated file, then score the bytes that were written.
                 fs.writeFileSync(fafResult.path, yaml.stringify(fafData), 'utf-8');
-                // Calculate new score (simple count-based)
-                const totalFields = Object.keys(QUESTION_REGISTRY).length;
-                const filledFields = Object.keys(QUESTION_REGISTRY).filter(field => !isEmpty(getNestedValue(fafData, field))).length;
-                const newScore = Math.round((filledFields / totalFields) * 100);
-                const celebration = newScore >= 100 ? '🏆 GOLD CODE ACHIEVED!' :
-                    newScore >= 85 ? '🥇 Championship grade!' :
-                        newScore >= 70 ? '🥈 Great progress!' : '📈 Keep going!';
+                const newScore = scoreOf(fs.readFileSync(fafResult.path, 'utf-8'));
+                const celebration = tierLabel(newScore);
                 return {
                     content: [{
                             type: 'text',
@@ -1864,12 +1897,10 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
             // PHASE 1: Analyze and return questions — the canonical 6Ws (SIX_WS_INTERVIEW),
             // scoped to slots that are empty AND active (slotignored is never asked).
             const missingFields = SIX_WS_INTERVIEW
-                .filter((q) => { const v = getNestedValue(fafData, q.path); return v !== 'slotignored' && isEmpty(v); })
+                .filter((q) => isEmpty(getNestedValue(fafData, q.path)))
                 .map((q) => q.path);
-            // Calculate current score
-            const totalFields = Object.keys(QUESTION_REGISTRY).length;
-            const filledFields = totalFields - missingFields.length;
-            const currentScore = Math.round((filledFields / totalFields) * 100);
+            // Current score — the same number faf_score reports for this file.
+            const currentScore = scoreOf(fafContent);
             // Already at 100%?
             if (currentScore >= 100) {
                 return {
@@ -1892,7 +1923,7 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
                             text: JSON.stringify({
                                 score: currentScore,
                                 message: `Score is ${currentScore}%. All fields filled but content may need enhancement.`,
-                                suggestion: 'Use faf_enhance to improve content quality.',
+                                suggestion: 'Use faf_go or faf_human_add to improve content quality.',
                                 context: 'faf_go'
                             }, null, 2)
                         }]
@@ -1945,120 +1976,52 @@ All work: \`faf init\`, \`faf init new\`, \`faf init --new\`, \`faf init -new\`
     /**
      * faf_auto - ONE COMMAND TO RULE THEM ALL
      * Zero to Championship in one command
-     * Runs: init + formats + sync + bi-sync + score
+     *
+     * v3.0: composes faf-cli's own `faf auto` chain — `updateExistingFaf` on an
+     * existing file, `assembleFreshFaf` on a new one, `writeFaf` for the bytes,
+     * `renderClaudeMd`/`writeClaudeMd` for CLAUDE.md — plus the same
+     * `scoreFafYaml` faf_score reads. Previously this handler ran a bespoke
+     * bootstrap template plus a local `calculateSimpleScore` pseudo-scorer,
+     * which could (and did) report a different score than faf_score for the
+     * identical file in the same server run. NEVER reimplement detection or
+     * scoring here — compose faf-cli, exactly like faf_score/faf_formats do.
      */
     async handleFafAuto(args) {
         const startTime = Date.now();
         const cwd = this.getProjectPath(args?.path);
-        const yaml = await import('yaml');
         const path = await import('path');
         try {
             const steps = [];
-            let currentScore = 0;
-            // Step 1: Check/Create .faf file
-            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            const { findFafFile: findFaf, readFaf, readFafRaw, scoreFafYaml, assembleFreshFaf, updateExistingFaf, writeFaf, renderClaudeMd, writeClaudeMd, } = await faf_cli_bridge_js_1.fafCli;
+            // Step 1: locate any existing .faf and its real "before" score.
+            const existingPath = findFaf(cwd);
+            const beforeScore = existingPath ? scoreFafYaml(readFafRaw(existingPath)).score : 0;
+            steps.push(existingPath ? `✅ Found ${path.basename(existingPath)}` : '✅ Will create project.faf');
+            // Step 2: exactly what faf-cli's own `faf auto` does — an existing file
+            // is updated with updateExistingFaf (existing values win; interrogated →
+            // detected → Turbo-Cat → Relentless fill the empties), a new one is
+            // assembled with assembleFreshFaf — and written with faf-cli's writer,
+            // so the bytes match `faf auto` (no runtime `_meta` block, same layout).
             let fafPath;
-            if (!fafResult) {
-                // Create .faf file
-                const projectName = path.basename(cwd);
-                fafPath = path.join(cwd, 'project.faf');
-                const initFafContent = `# FAF - Foundational AI Context
-project: ${projectName}
-type: auto-detected
-context: I⚡🍊
-generated: ${new Date().toISOString()}
-version: ${version_1.VERSION}
-
-# Quick Context
-working_directory: ${cwd}
-initialized_by: faf-mcp-auto
-vitamin_context: true
-faffless: true
-`;
-                fs.writeFileSync(fafPath, initFafContent);
-                steps.push('✅ Created project.faf');
-            }
-            else {
-                fafPath = fafResult.path;
-                steps.push(`✅ Found ${fafResult.filename}`);
-            }
-            // Get initial score
-            const fafContent = fs.readFileSync(fafPath, 'utf-8');
-            const fafData = yaml.parse(fafContent) || {};
-            currentScore = this.calculateSimpleScore(fafData);
-            // Step 2: Run TURBO-CAT format discovery — composed from faf-cli's engine.
-            const formatsResult = await (0, turbocat_bridge_js_1.composedTurboCat)(cwd);
-            if (formatsResult && formatsResult.discoveredFormats.length > 0) {
-                // Apply slot fills to .faf. turboCatSlots routes them into the correct
-                // .faf sections; fill the stack section (main_language lives under
-                // project, which is a string here) — clean keys, no noise.
-                const slots = await (0, turbocat_bridge_js_1.composedTurboCatSlots)(cwd);
-                if (!fafData.stack)
-                    fafData.stack = {};
-                for (const [key, value] of Object.entries(slots?.stack ?? {})) {
-                    if (!fafData.stack[key] || fafData.stack[key] === 'None') {
-                        fafData.stack[key] = value;
-                    }
-                }
-                if (formatsResult.stackSignature) {
-                    fafData.stack_signature = formatsResult.stackSignature;
-                }
-                fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
-                steps.push(`✅ TURBO-CAT discovered ${formatsResult.discoveredFormats.length} formats`);
+            if (existingPath) {
+                fafPath = existingPath;
+                writeFaf(fafPath, updateExistingFaf(cwd, readFaf(existingPath)));
+                steps.push('✅ Merged fresh facts into existing project.faf (existing values preserved)');
             }
             else {
-                steps.push('⚠️ No additional formats detected');
-            }
-            // Step 3: Extract human context from README
-            const readmePath = path.join(cwd, 'README.md');
-            if (fs.existsSync(readmePath)) {
-                const readmeContent = fs.readFileSync(readmePath, 'utf-8');
-                const extracted = this.extractSixWsFromReadme(readmeContent);
-                if (!fafData.human_context)
-                    fafData.human_context = {};
-                let extractedCount = 0;
-                for (const [field, value] of Object.entries(extracted)) {
-                    if (value && !fafData.human_context[field]) {
-                        fafData.human_context[field] = value;
-                        extractedCount++;
-                    }
-                }
-                if (extractedCount > 0) {
-                    fs.writeFileSync(fafPath, yaml.stringify(fafData), 'utf-8');
-                    steps.push(`✅ Extracted ${extractedCount} human context fields from README`);
-                }
-            }
-            // Step 4: Create/Update CLAUDE.md (bi-sync)
-            const claudePath = path.join(cwd, 'CLAUDE.md');
-            if (!fs.existsSync(claudePath)) {
-                const claudeContent = `# 🏎️ CLAUDE.md - AI Telemetry Link
-
-## Project: ${fafData.project || path.basename(cwd)}
-**Championship-Grade Project DNA Foundation**
-
-### 🎯 Project Mission
-${fafData.human_context?.why || fafData.project?.goal || 'AI-ready project context'}
-
-### 🏗️ Architecture Overview
-${fafData.stack_signature || 'Auto-detected stack'}
-
----
-
-**STATUS: BI-SYNC ACTIVE 🔗**
-*Last Sync: ${new Date().toISOString()}*
-*Sync Engine: FAF Auto*
-`;
-                fs.writeFileSync(claudePath, claudeContent);
-                steps.push('✅ Created CLAUDE.md');
-            }
-            else {
-                steps.push('✅ CLAUDE.md already exists');
+                fafPath = path.join(cwd, 'project.faf');
+                writeFaf(fafPath, assembleFreshFaf(cwd));
+                steps.push('✅ Created project.faf');
             }
-            // Step 5: Calculate final score
-            const updatedContent = fs.readFileSync(fafPath, 'utf-8');
-            const updatedData = yaml.parse(updatedContent) || {};
-            const newScore = this.calculateSimpleScore(updatedData);
-            const scoreDelta = newScore - currentScore;
+            // Step 3: CLAUDE.md — faf-cli's render of the file just written (the
+            // same bytes `faf sync` writes), injected non-destructively.
+            const claudeExisted = fs.existsSync(path.join(cwd, 'CLAUDE.md'));
+            writeClaudeMd(cwd, renderClaudeMd(readFaf(fafPath)));
+            steps.push(claudeExisted ? '✅ Updated CLAUDE.md (faf-managed block)' : '✅ Created CLAUDE.md');
+            // Step 4: final score — same real scorer faf_score reads, on the file
+            // just written. By construction this can never disagree with faf_score.
+            const newScore = scoreFafYaml(readFafRaw(fafPath)).score;
+            const scoreDelta = newScore - beforeScore;
             // Calculate elapsed time
             const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
             // Format output
@@ -2068,7 +2031,7 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             output += steps.join('\n') + '\n\n';
             output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
             output += `⏱️ Completed in ${elapsed}s\n`;
-            output += `📊 Before: ${currentScore}% | After: ${newScore}% ${deltaDisplay}\n`;
+            output += `📊 Before: ${beforeScore}% | After: ${newScore}% ${deltaDisplay}\n`;
             output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`;
             if (newScore >= 99) {
                 output += `🏆 CHAMPIONSHIP ACHIEVED! Your AI has complete context.\n`;
@@ -2082,7 +2045,7 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             else {
                 output += `🚀 Good start! Run faf_go for guided improvement.\n`;
             }
-            output += `\n💡 Next: faf_score --details | faf_go | faf_enhance`;
+            output += `\n💡 Next: faf_score | faf_go | faf_bi_sync`;
             return { content: [{ type: 'text', text: output }] };
         }
         catch (error) {
@@ -2113,11 +2076,10 @@ ${fafData.stack_signature || 'Auto-detected stack'}
                             }]
                     };
                 }
-                // .faf exists but no DNA - create initial DNA
-                const yaml = await import('yaml');
-                const fafContent = fs.readFileSync(fafResult.path, 'utf-8');
-                const fafData = yaml.parse(fafContent) || {};
-                const currentScore = this.calculateSimpleScore(fafData);
+                // .faf exists but no DNA - create initial DNA. Real scorer — same
+                // one faf_score reads — never a local pseudo-score (v3.0 fix).
+                const { readFafRaw, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+                const currentScore = scoreFafYaml(readFafRaw(fafResult.path)).score;
                 const dna = {
                     birthCertificate: {
                         born: new Date().toISOString(),
@@ -2149,8 +2111,24 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             const dna = JSON.parse(dnaContent);
             // Build journey string
             const birthScore = dna.birthCertificate?.birthDNA || 0;
-            const currentScore = dna.current?.score || 0;
+            let currentScore = dna.current?.score || 0;
             const milestones = dna.milestones || [];
+            dna.milestones = milestones;
+            // "Current" is the live score of the file on disk, not whatever was
+            // stored last time. Nothing else records growth into .faf-dna, so this
+            // is where the journey gets its next point.
+            const fafResult = await (0, faf_file_finder_js_1.findFafFile)(cwd);
+            if (fafResult) {
+                const { readFafRaw, scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+                const live = scoreFafYaml(readFafRaw(fafResult.path)).score;
+                if (live !== currentScore) {
+                    const now = new Date().toISOString();
+                    dna.current = { ...(dna.current ?? {}), score: live, lastSync: now };
+                    milestones.push({ type: 'sync', score: live, date: now, version: dna.current.version ?? 'v1.0.0' });
+                    fs.writeFileSync(dnaPath, JSON.stringify(dna, null, 2));
+                    currentScore = live;
+                }
+            }
             // Find key milestones
             const _birth = milestones.find((m) => m.type === 'birth');
             const peak = milestones.find((m) => m.type === 'peak');
@@ -2192,7 +2170,7 @@ ${fafData.stack_signature || 'Auto-detected stack'}
             }
             output += `\n🧬 MILESTONES\n`;
             const milestoneIcons = {
-                birth: '🐣', first_save: '💾', doubled: '2️⃣',
+                birth: '🐣', first_save: '💾', doubled: '2️⃣', sync: '🔄',
                 championship: '🏆', elite: '⭐', peak: '🏔️', perfect: '💎'
             };
             for (const m of milestones) {
@@ -2271,33 +2249,6 @@ ${fafData.stack_signature || 'Auto-detected stack'}
         }
     }
     /**
-     * Internal helper: Calculate simple score from .faf data
-     */
-    calculateSimpleScore(fafData) {
-        let score = 0;
-        const maxScore = 100;
-        // Project section (30 points)
-        if (fafData.project)
-            score += 15;
-        if (fafData.project?.goal || fafData.description)
-            score += 15;
-        // Human context (30 points)
-        const humanContext = fafData.human_context || {};
-        const wFields = ['who', 'what', 'why', 'where', 'when', 'how'];
-        const filledW = wFields.filter(f => humanContext[f] && humanContext[f] !== 'null').length;
-        score += Math.round((filledW / wFields.length) * 30);
-        // Stack section (20 points)
-        const stack = fafData.stack || {};
-        const stackFields = ['frontend', 'backend', 'database', 'hosting', 'build'];
-        const filledStack = stackFields.filter(f => stack[f] && stack[f] !== 'None').length;
-        score += Math.round((filledStack / stackFields.length) * 20);
-        // Files exist bonus (20 points)
-        if (fafData.initialized_by || fafData.generated)
-            score += 10;
-        if (fafData.stack_signature)
-            score += 10;
-        return Math.min(score, maxScore);
-    }
     /**
      * faf_quick - Lightning-fast .faf creation
      * One-liner format: "name, description, language, framework, hosting"
@@ -2357,7 +2308,7 @@ Example: "my-app, e-commerce platform"`
 
 ⚠️ project.faf already exists at: ${fafPath}
 
-Use force: true to overwrite, or use faf_enhance to modify.`
+Use force: true to overwrite, or use faf_go / faf_human_add to modify.`
                         }]
                 };
             }
@@ -2394,7 +2345,6 @@ Use force: true to overwrite, or use faf_enhance to modify.`
             output += `✅ Created: ${fafPath}\n\n`;
             output += `Next steps:\n`;
             output += `  • faf_score - Check AI-readiness\n`;
-            output += `  • faf_enhance - Improve context\n`;
             output += `  • faf_go - Guided interview to 100%`;
             return { content: [{ type: 'text', text: output }] };
         }
@@ -2502,7 +2452,7 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                             results.push({
                                 status: 'warning',
                                 message: `Missing important fields: ${missingFields.join(', ')}`,
-                                fix: 'Run: faf_enhance or faf_go to add missing info'
+                                fix: 'Run: faf_go to add missing info'
                             });
                         }
                         else {
@@ -2511,26 +2461,31 @@ Use force: true to overwrite, or use faf_enhance to modify.`
                                 message: '.faf structure is valid'
                             });
                         }
-                        // Check 4: Score
-                        const score = this.calculateSimpleScore(fafData);
+                        // Check 4: Score — real scorer (same one faf_score reads), never
+                        // a local pseudo-score (v3.0 fix). Slot breakdown included so
+                        // faf_doctor's "score could be better" fix advice is actionable.
+                        const { scoreFafYaml } = await faf_cli_bridge_js_1.fafCli;
+                        const scoreResult = scoreFafYaml(content);
+                        const score = scoreResult.score;
+                        const slotSummary = `${scoreResult.populated}/${scoreResult.active} slots populated`;
                         if (score < 30) {
                             results.push({
                                 status: 'error',
-                                message: `Score too low: ${score}%`,
-                                fix: 'Run: faf_enhance or faf_go to improve context'
+                                message: `Score too low: ${score}% (${slotSummary})`,
+                                fix: 'Run: faf_go to improve context'
                             });
                         }
                         else if (score < 70) {
                             results.push({
                                 status: 'warning',
-                                message: `Score could be better: ${score}%`,
+                                message: `Score could be better: ${score}% (${slotSummary})`,
                                 fix: 'Target 70%+ for championship AI context'
                             });
                         }
                         else {
                             results.push({
                                 status: 'ok',
-                                message: `Great score: ${score}%`
+                                message: `Great score: ${score}% (${slotSummary})`
                             });
                         }
                     }