@magic-ingredients/tiny-brain-local 0.20.1 → 0.21.1

package/dist/services/analyse-service.js

@@ -4,12 +4,12 @@
  * Handles repository tech stack analysis.
  * Focused solely on analysis - no context file management.
  */
-import { analyseRepository, formatTechStackChanges, detectTechStackChanges, ConfigService, RepoConfigService, LibraryClient, TechContextService, AgentsMdService, } from '@magic-ingredients/tiny-brain-core';
+import { analyseRepository, formatTechStackChanges, detectTechStackChanges, ConfigService, ConfigSetupService, RepoConfigService, LibraryClient, TechContextService, AgentsMdService, RecommendationService, } from '@magic-ingredients/tiny-brain-core';
 import { RepoService } from './repo-service.js';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { existsSync } from 'fs';
-import { mkdir, copyFile, readFile, readdir, chmod, stat, writeFile } from 'fs/promises';
+import { readFile, readdir, writeFile } from 'fs/promises';
 import { getPackageVersion } from '../utils/package-version.js';
 /**
  * Service for managing repository analysis
@@ -21,12 +21,14 @@ export class AnalyseService {
     libraryClient;
     configService;
     techContextService;
+    recommendationService;
     constructor(context) {
         this.context = context;
         this.configService = new ConfigService(context);
         this.repoService = new RepoService(context);
         this.libraryClient = new LibraryClient();
         this.techContextService = new TechContextService(process.cwd());
+        this.recommendationService = new RecommendationService(process.cwd());
     }
     /**
      * Perform repository analysis with unified behavior for initialized/uninitialized repos
@@ -38,15 +40,14 @@ export class AnalyseService {
         this.context.logger.info(`Repository analysis complete: ${currentAnalysis.languages.join(', ')}`);
         // Register repository in dashboard
         await this.registerRepository();
-        // Initialize documentation directories based on config
-        const prdInitialized = await this.initializePrdDirectory();
-        const adrInitialized = await this.initializeAdrDirectory();
-        const qualityInitialized = await this.initializeQualityDirectory();
-        const fixesInitialized = await this.initializeFixesDirectory();
-        // Initialize git hooks for TDD workflow
-        const gitHooksInstalled = await this.initializeGitHooks();
-        // Inject skill permissions into .claude/settings.json
-        const skillPermissionsAdded = await this.injectSkillPermissions();
+        // Perform config setup (directories, hooks, permissions, CLAUDE.md)
+        const configSetupResult = await this.performConfigSetup();
+        const prdInitialized = configSetupResult?.prdInitialized ?? false;
+        const adrInitialized = configSetupResult?.adrInitialized ?? false;
+        const qualityInitialized = configSetupResult?.qualityInitialized ?? false;
+        const fixesInitialized = configSetupResult?.fixesInitialized ?? false;
+        const gitHooksInstalled = configSetupResult?.gitHooksInstalled ?? false;
+        const skillPermissionsAdded = configSetupResult?.skillPermissionsAdded ?? [];
         // Check if stack has changed using hash-based comparison
         const analysisInput = {
             languages: currentAnalysis.languages,
@@ -80,6 +81,11 @@ export class AnalyseService {
         if (!dryRun) {
             writtenTechContexts = await this.fetchAndWriteTechContexts(currentAnalysis);
         }
+        // Fetch and write recommendations from TBR
+        let recommendations = [];
+        if (!dryRun) {
+            recommendations = await this.fetchAndWriteRecommendations(currentAnalysis);
+        }
         // Get enableAgenticCoding preference and sync tech agents
         // When enabled, copies tech contexts from .tiny-brain/tech/ to .claude/agents/
         const enableAgentic = await this.configService.isAgenticCodingEnabled();
@@ -92,10 +98,6 @@ export class AnalyseService {
         if (!dryRun && manageAgentsMd) {
             agentsMdStatus = await this.generateAgentsMd(currentAnalysis);
         }
-        // Write workflow sections to CLAUDE.md based on config flags (SDD, TDD)
-        if (!dryRun) {
-            await this.repoService.writeWorkflowSections({ contextPath });
-        }
         // Check context block version (for backwards compatibility during migration)
         const currentVersion = getPackageVersion();
         const existingContent = await this.repoService.readRepoBlockFromContextFile(contextPath);
@@ -120,6 +122,7 @@ export class AnalyseService {
                 skillPermissionsAdded: skillPermissionsAdded.length > 0 ? skillPermissionsAdded : undefined,
                 writtenTechContexts,
                 agentsMdStatus,
+                recommendations,
             };
         }
         if (!stackChanged) {
@@ -141,6 +144,7 @@ export class AnalyseService {
                 skillPermissionsAdded: skillPermissionsAdded.length > 0 ? skillPermissionsAdded : undefined,
                 writtenTechContexts,
                 agentsMdStatus,
+                recommendations,
             };
         }
         // Changes detected - compute diff for display purposes
@@ -180,6 +184,7 @@ export class AnalyseService {
             skillPermissionsAdded: skillPermissionsAdded.length > 0 ? skillPermissionsAdded : undefined,
             writtenTechContexts,
             agentsMdStatus,
+            recommendations,
         };
     }
     /**
@@ -319,239 +324,52 @@ export class AnalyseService {
         }
     }
     /**
-     * Initialize PRD directory structure for SDD workflow
-     * @returns true if directory was created
-     */
-    async initializePrdDirectory() {
-        try {
-            const enableSDD = await this.configService.isSDDEnabled();
-            if (!enableSDD) {
-                this.context.logger.debug('SDD disabled, skipping PRD directory initialization');
-                return false;
-            }
-            const repoRoot = process.cwd();
-            const prdDir = join(repoRoot, 'docs', 'prd');
-            if (existsSync(prdDir)) {
-                return false; // Already exists
-            }
-            await mkdir(prdDir, { recursive: true });
-            this.context.logger.info('✅ Created docs/prd/ directory');
-            return true;
-        }
-        catch (error) {
-            this.context.logger.warn(`Failed to initialize PRD directory: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            return false;
-        }
-    }
-    /**
-     * Initialize ADR directory structure
-     * @returns true if directory was created
+     * Perform config setup using core ConfigSetupService.
+     * Delegates directory initialization, git hooks, skill permissions, and CLAUDE.md
+     * context block writing to the shared service.
      */
-    async initializeAdrDirectory() {
+    async performConfigSetup() {
         try {
-            const enableADR = await this.configService.isADREnabled();
-            if (!enableADR) {
-                this.context.logger.debug('ADR disabled, skipping ADR directory initialization');
-                return false;
-            }
-            const repoRoot = process.cwd();
-            const adrDir = join(repoRoot, 'docs', 'adr');
-            if (existsSync(adrDir)) {
-                return false; // Already exists
-            }
-            await mkdir(adrDir, { recursive: true });
-            this.context.logger.info('✅ Created docs/adr/ directory');
-            return true;
-        }
-        catch (error) {
-            this.context.logger.warn(`Failed to initialize ADR directory: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            return false;
-        }
-    }
-    /**
-     * Initialize Quality directory structure
-     * @returns true if directory was created
-     */
-    async initializeQualityDirectory() {
-        try {
-            const enableQuality = await this.configService.isQualityEnabled();
-            if (!enableQuality) {
-                this.context.logger.debug('Quality disabled, skipping Quality directory initialization');
-                return false;
-            }
-            const repoRoot = process.cwd();
-            const qualityDir = join(repoRoot, 'docs', 'quality');
-            if (existsSync(qualityDir)) {
-                return false; // Already exists
-            }
-            await mkdir(qualityDir, { recursive: true });
-            this.context.logger.info('✅ Created docs/quality/ directory');
-            return true;
-        }
-        catch (error) {
-            this.context.logger.warn(`Failed to initialize Quality directory: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            return false;
-        }
-    }
-    /**
-     * Initialize fixes tracking directory
-     * @returns true if directory was created
-     */
-    async initializeFixesDirectory() {
-        try {
-            const enableSDD = await this.configService.isSDDEnabled();
-            if (!enableSDD) {
-                this.context.logger.debug('SDD disabled, skipping fixes directory initialization');
-                return false;
-            }
-            const repoRoot = process.cwd();
-            const fixesDir = join(repoRoot, '.tiny-brain', 'fixes');
-            if (existsSync(fixesDir)) {
-                return false; // Already exists
-            }
-            await mkdir(fixesDir, { recursive: true });
-            this.context.logger.info('✅ Created .tiny-brain/fixes/ directory');
-            return true;
+            const hooksSourceDir = this.resolveHooksDir();
+            const version = getPackageVersion();
+            const configSetup = new ConfigSetupService({
+                repoPath: process.cwd(),
+                version,
+                hooksSourceDir,
+                logger: {
+                    info: (msg) => this.context.logger.info(msg),
+                    debug: (msg) => this.context.logger.debug(msg),
+                    warn: (msg) => this.context.logger.warn(msg),
+                },
+            });
+            return await configSetup.performSetup();
         }
         catch (error) {
-            this.context.logger.warn(`Failed to initialize fixes directory: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            return false;
+            this.context.logger.warn(`Config setup failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return undefined;
         }
     }
     /**
-     * Initialize git hooks for TDD workflow
-     * Copies hook templates to .git/hooks/ if not already present
-     * @returns true if any hooks were installed
+     * Resolve hooks template directory from the core package.
+     * Tries the core package's templates first (monorepo layout), then falls back
+     * to the MCP package's own templates for backward compatibility.
      */
-    async initializeGitHooks() {
+    resolveHooksDir() {
         try {
-            const repoRoot = process.cwd();
-            const gitHooksDir = join(repoRoot, '.git', 'hooks');
-            // Check if .git directory exists (is this a git repo?)
-            if (!existsSync(join(repoRoot, '.git'))) {
-                this.context.logger.debug('Not a git repository, skipping git hooks initialization');
-                return false;
-            }
-            // Find the source hook templates in the installed package
             const __filename = fileURLToPath(import.meta.url);
             const __dirname = dirname(__filename);
-            const srcHooksDir = join(__dirname, '..', '..', 'templates', 'hooks');
-            // Verify source hooks directory exists
-            if (!existsSync(srcHooksDir)) {
-                this.context.logger.debug(`Hook templates not found at ${srcHooksDir}, skipping`);
-                return false;
-            }
-            // Ensure .git/hooks directory exists
-            await mkdir(gitHooksDir, { recursive: true });
-            // List of hooks to install
-            const hooks = ['commit-msg', 'post-commit', 'pre-commit'];
-            let anyInstalled = false;
-            for (const hookName of hooks) {
-                const srcHook = join(srcHooksDir, hookName);
-                const destHook = join(gitHooksDir, hookName);
-                // Skip if source doesn't exist
-                if (!existsSync(srcHook)) {
-                    continue;
-                }
-                // Skip if hook already exists (don't overwrite user customizations)
-                if (existsSync(destHook)) {
-                    // Check if it's our hook by looking for our signature comment
-                    try {
-                        const existingContent = await readFile(destHook, 'utf-8');
-                        if (!existingContent.includes('Installed by: tiny-brain')) {
-                            this.context.logger.debug(`Skipping ${hookName} - custom hook already exists`);
-                            continue;
-                        }
-                        // Our hook already installed, check if source is newer
-                        const srcStat = await stat(srcHook);
-                        const destStat = await stat(destHook);
-                        if (srcStat.mtime <= destStat.mtime) {
-                            continue; // Already up to date
-                        }
-                    }
-                    catch {
-                        continue; // Can't read, skip
-                    }
-                }
-                // Copy hook
-                await copyFile(srcHook, destHook);
-                // Make executable (755)
-                await chmod(destHook, 0o755);
-                anyInstalled = true;
-                this.context.logger.info(`✅ Installed git hook: ${hookName}`);
-            }
-            if (anyInstalled) {
-                this.context.logger.info('Git hooks initialized in .git/hooks/');
-            }
-            return anyInstalled;
-        }
-        catch (error) {
-            this.context.logger.warn(`Failed to initialize git hooks: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            return false;
-        }
-    }
-    /**
-     * Inject skill permissions into .claude/settings.json
-     * These permissions allow skills to read/write to specific directories without prompts
-     * @returns Array of permissions that were added (empty if none added)
-     */
-    async injectSkillPermissions() {
-        const SKILL_PERMISSIONS = [
-            'Write(.tiny-brain/**)',
-            'Write(docs/prd/**)',
-            'Write(docs/adr/**)',
-            'Write(docs/quality/**)',
-            'Read(.tiny-brain/**)',
-            'Read(docs/prd/**)',
-            'Read(docs/adr/**)',
-            'Read(docs/quality/**)',
-            'Read(.claude/skills/**/templates/**)',
-        ];
-        try {
-            const repoRoot = process.cwd();
-            const settingsDir = join(repoRoot, '.claude');
-            const settingsPath = join(settingsDir, 'settings.json');
-            // Ensure .claude directory exists
-            await mkdir(settingsDir, { recursive: true });
-            // Read existing settings or start with empty object
-            let settings = {};
-            if (existsSync(settingsPath)) {
-                try {
-                    const content = await readFile(settingsPath, 'utf-8');
-                    settings = JSON.parse(content);
-                }
-                catch {
-                    this.context.logger.warn('Failed to parse existing settings.json, will create new one');
-                    settings = {};
-                }
-            }
-            // Ensure permissions.allow array exists
-            if (!settings.permissions) {
-                settings.permissions = {};
-            }
-            const permissions = settings.permissions;
-            if (!Array.isArray(permissions.allow)) {
-                permissions.allow = [];
-            }
-            const allowList = permissions.allow;
-            // Add missing permissions
-            const addedPermissions = [];
-            for (const perm of SKILL_PERMISSIONS) {
-                if (!allowList.includes(perm)) {
-                    allowList.push(perm);
-                    addedPermissions.push(perm);
-                }
-            }
-            // Only write if we added new permissions
-            if (addedPermissions.length > 0) {
-                await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-                this.context.logger.info(`Added ${addedPermissions.length} skill permissions to .claude/settings.json`);
-            }
-            return addedPermissions;
+            // First try: core package's templates (via monorepo workspace link)
+            const coreHooksDir = join(__dirname, '..', '..', '..', 'tiny-brain-core', 'templates', 'hooks');
+            if (existsSync(coreHooksDir))
+                return coreHooksDir;
+            // Second try: the MCP package's own templates (backward compatibility)
+            const mcpHooksDir = join(__dirname, '..', '..', 'templates', 'hooks');
+            if (existsSync(mcpHooksDir))
+                return mcpHooksDir;
+            return undefined;
         }
-        catch (error) {
-            this.context.logger.warn(`Failed to inject skill permissions: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            return [];
+        catch {
+            return undefined;
         }
     }
     /**
@@ -585,6 +403,30 @@ export class AnalyseService {
             return [];
         }
     }
+    /**
+     * Fetch recommendations from TBR and write them via RecommendationService
+     */
+    async fetchAndWriteRecommendations(analysis) {
+        try {
+            const localContext = this.context;
+            if (!localContext.authToken?.token) {
+                this.context.logger.debug('No auth token available for recommendations API call');
+                return [];
+            }
+            const response = await this.libraryClient.getRecommendations(analysis, localContext.authToken.token);
+            if (!response?.recommendations || response.recommendations.length === 0) {
+                this.context.logger.debug('No recommendations returned from TBR');
+                return [];
+            }
+            await this.recommendationService.writeRecommendations(response.recommendations, response.fetchedAt);
+            this.context.logger.info(`Fetched ${response.recommendations.length} recommendation(s) from TBR`);
+            return response.recommendations;
+        }
+        catch (error) {
+            this.context.logger.warn(`Failed to fetch recommendations from TBR: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return [];
+        }
+    }
     /**
      * Format analysis output for display
      */
@@ -704,6 +546,27 @@ export class AnalyseService {
                     : 'Up to date';
             lines.push(`\nAGENTS.md: ${statusLabel}`);
         }
+        // Recommendations section (shown when recommendations exist)
+        if (result.recommendations && result.recommendations.length > 0) {
+            lines.push('\n🎯 Recommendations:');
+            const groupLabels = { skill: 'Skills', agent: 'Agents', hook: 'Hooks' };
+            const grouped = new Map();
+            for (const rec of result.recommendations) {
+                const existing = grouped.get(rec.type) ?? [];
+                grouped.set(rec.type, [...existing, rec]);
+            }
+            for (const [type, label] of Object.entries(groupLabels)) {
+                const recs = grouped.get(type);
+                if (recs && recs.length > 0) {
+                    lines.push(`\n  ${label}:`);
+                    for (const rec of recs) {
+                        lines.push(`    • ${rec.name} — ${rec.description}`);
+                        lines.push(`      Reason: ${rec.reason}`);
+                    }
+                }
+            }
+            lines.push('\n  Use `recommendations operation=accept` to install');
+        }
         return lines.join('\n');
     }
     /**

package/dist/services/repo-service.d.ts

@@ -8,6 +8,7 @@
 import type { RequestContext } from '../types/request-context.js';
 export interface WriteWorkflowSectionsOptions {
     contextPath?: string;
+    isMonorepo?: boolean;
 }
 /**
  * Service for repository context operations
@@ -75,6 +76,10 @@ export declare class RepoService {
      * Format the Progress Tracking Auto-Commit Configuration section
      */
     private formatProgressTrackingSection;
+    /**
+     * Format the Worktree Merge Workflow section
+     */
+    private formatWorktreeMergeSection;
     /**
      * Format the Operational Tracking Directory section
      */

package/dist/services/repo-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-service.d.ts","sourceRoot":"","sources":["../../src/services/repo-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAIlE,MAAM,WAAW,4BAA4B;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IAMV,OAAO,CAAC,OAAO;IAL3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAA2B;IACnE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAyB;IAE/D,OAAO,CAAC,aAAa,CAAgB;gBAEjB,OAAO,EAAE,cAAc;IAS3C;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACG,4BAA4B,CAChC,eAAe,GAAE,MAAoB,GACpC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmCzB;;;;OAIG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOvD;;OAEG;IACH,cAAc,IAAI,OAAO;IAUzB;;;OAGG;IACG,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC;IAcjD;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAa5B;;;;;;;;OAQG;IACG,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,IAAI,CAAC;IA6FtF;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA6GlC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAoChC;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAwErC;;OAEG;IACH,OAAO,CAAC,gCAAgC;CAyCzC"}
+{"version":3,"file":"repo-service.d.ts","sourceRoot":"","sources":["../../src/services/repo-service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAIlE,MAAM,WAAW,4BAA4B;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IAMV,OAAO,CAAC,OAAO;IAL3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAA2B;IACnE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAyB;IAE/D,OAAO,CAAC,aAAa,CAAgB;gBAEjB,OAAO,EAAE,cAAc;IAS3C;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACG,4BAA4B,CAChC,eAAe,GAAE,MAAoB,GACpC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAmCzB;;;;OAIG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOvD;;OAEG;IACH,cAAc,IAAI,OAAO;IAUzB;;;OAGG;IACG,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC;IAcjD;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAa5B;;;;;;;;OAQG;IACG,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkGtF;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IA6BhC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAgGlC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA4ChC;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAiErC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA6BlC;;OAEG;IACH,OAAO,CAAC,gCAAgC;CAyCzC"}

package/dist/services/repo-service.js

@@ -155,7 +155,7 @@ export class RepoService {
         // Build the workflow sections content
         let workflowContent = '';
         // Repository Context (always when workflow sections are enabled)
-        workflowContent += this.formatRepoContextSection(enableAgentic);
+        workflowContent += this.formatRepoContextSection(enableAgentic, options.isMonorepo);
         // Commit Message Format (when SDD enabled)
         if (enableSDD) {
             workflowContent += this.formatCommitMessageSection();
@@ -168,6 +168,10 @@ export class RepoService {
         if (enableSDD) {
             workflowContent += this.formatProgressTrackingSection();
         }
+        // Worktree Merge Workflow (when SDD enabled)
+        if (enableSDD) {
+            workflowContent += this.formatWorktreeMergeSection();
+        }
         // Operational Tracking Directory (when SDD enabled)
         if (enableSDD) {
             workflowContent += this.formatOperationalTrackingSection();
@@ -226,13 +230,15 @@ export class RepoService {
      * Format the Repository Context section
      * When agentic coding is enabled, includes a mandatory agent delegation section
      */
-    formatRepoContextSection(enableAgenticCoding) {
-        let content = `## Repository Context
-
-Before starting work, read \`AGENTS.md\` for comprehensive project context (tech stack, commands, structure).
-Also read \`.tiny-brain/analysis.json\` for detailed detection data and test patterns.
-
-`;
+    formatRepoContextSection(enableAgenticCoding, isMonorepo) {
+        let content = `## Repository Context\n\n`;
+        if (isMonorepo) {
+            content += `Before starting work, read the root \`AGENTS.md\` for comprehensive project context (tech stack, commands, structure).\nWhen working in a specific package, also read that package's \`AGENTS.md\` for package-specific details.\n`;
+        }
+        else {
+            content += `Before starting work, read \`AGENTS.md\` for comprehensive project context (tech stack, commands, structure).\n`;
+        }
+        content += `Also read \`.tiny-brain/analysis.json\` for detailed detection data and test patterns.\n\n`;
         if (enableAgenticCoding) {
             content += `## Agent Delegation (MANDATORY)
 
@@ -297,19 +303,6 @@ Description of changes...
 
 **WARNING:** The commit-msg hook will reject commits missing required headers.
 
-### Updating Markdown After Commits
-
-**For PRD tasks:**
-1. Open the feature file: \`docs/prd/{prd-id}/features/{feature-id}.md\`
-2. Update the task with status and commitSha:
-   \`\`\`markdown
-   ### 1. Task description
-   status: completed
-   commitSha: abc1234
-   \`\`\`
-3. Run: \`npx tiny-brain sync-file docs/prd/{prd-id}/features/{feature-id}.md\`
-4. If ALL tasks in the feature are complete, update the PRD status
-
 ### Fix Status Workflow
 
 Fix documents have three statuses: \`documented\` → \`in_progress\` → \`resolved\`
@@ -317,7 +310,7 @@ Fix documents have three statuses: \`documented\` → \`in_progress\` → \`reso
 **When starting work on a fix:**
 1. Open the fix file: \`.tiny-brain/fixes/{fix-id}.md\`
 2. Update frontmatter: \`status: in_progress\`
-3. Run: \`npx tiny-brain sync-file .tiny-brain/fixes/{fix-id}.md\`
+3. Run: \`npx tiny-brain sync-progress .tiny-brain/fixes/{fix-id}.md\`
 
 **After each commit:**
 1. Update the completed task(s) in the markdown:
@@ -333,7 +326,7 @@ Fix documents have three statuses: \`documented\` → \`in_progress\` → \`reso
    status: superseded
    commitSha: null
    \`\`\`
-4. Run: \`npx tiny-brain sync-file .tiny-brain/fixes/{fix-id}.md\`
+4. Run: \`npx tiny-brain sync-progress .tiny-brain/fixes/{fix-id}.md\`
 
 **When all tasks are complete:**
 1. **ONLY set \`status: resolved\`** when ALL tasks are accounted for:
@@ -354,9 +347,9 @@ Fix documents have three statuses: \`documented\` → \`in_progress\` → \`reso
          - path/to/file1.ts
          - path/to/file2.ts
      \`\`\`
-3. Run: \`npx tiny-brain sync-file .tiny-brain/fixes/{fix-id}.md\`
+3. Run: \`npx tiny-brain sync-progress .tiny-brain/fixes/{fix-id}.md\`
 
-**Note:** The markdown file is the source of truth. The \`sync-file\` command updates \`progress.json\` from the markdown.
+**Note:** The markdown file is the source of truth. The \`sync-progress\` command updates \`progress.json\` from the markdown.
 
 `;
     }
@@ -371,30 +364,38 @@ IMPORTANT: This repository follows strict Test-Driven Development (TDD) with a 3
 **Red → Green → Refactor Cycle:**
 
 1. **Red Phase** (\`test:\` or \`test(scope):\` commits):
+   - **CRITICAL — you MUST run before writing tests:**
+     \`npx tiny-brain update-phase --phase red --event start --task '...' [--fix ID | --prd ID --feature ID]\`
    - Write failing tests first
    - Tests SHOULD fail (that's the point!)
    - Use: \`git commit -m "test: ..."\` or \`git commit -m "test(api): ..."\`
    - Git hook automatically runs typecheck + lint but SKIPS tests
    - Tracked in: \`testCommitSha\` field
+   - **After commit:** post-commit hook automatically transitions to \`green:start\`
 
 2. **Green Phase** (\`feat:\` or \`feat(scope):\` commits):
+   - Phase started automatically by post-commit hook after \`test:\` commit (no manual step needed)
    - Implement minimum code to make tests pass
    - Use: \`git commit -m "feat: ..."\` or \`git commit -m "feat(auth): ..."\`
    - Git hook automatically runs full checks (typecheck + lint + test)
    - Tracked in: \`commitSha\` field
    - **Marks task as COMPLETED**
+   - **After commit:** adversarial review hook sets \`adversarial:start\` and outputs review instructions
 
 3. **Refactor Phase** (\`refactor:\` or \`refactor(scope):\` commits - optional):
+   - Triggered by adversarial review suggestions
    - Improve code quality without changing behavior
    - Use: \`git commit -m "refactor: ..."\` or \`git commit -m "refactor(plan): ..."\`
    - Git hook automatically runs full checks (typecheck + lint + test)
-   - Tracked in: \`refactorCommitSha\` field
+   - **After commit:** post-commit hook automatically transitions \`adversarial-refactor:complete\`
+
+4. **Progress Commit** (end of cycle):
+   - After the full RED→GREEN→REFACTOR cycle is complete
+   - Run: \`npx tiny-brain commit-progress\`
+
+**What you must do manually:** Only \`update-phase --phase red --event start\` before writing tests. Everything else is automated by hooks.
 
-**Why This Matters:**
-- Git hooks automatically detect commit type and run appropriate checks
-- Separate commit tracking enables Feature 9 (TDD phase tracking in dashboard)
-- Provides audit trail of development process
-- Only \`feat:\` or \`feat(scope):\` commits mark tasks as completed
+**What you must NOT do:** Do not manually call \`update-phase\` for green:start, adversarial:start, or adversarial-refactor:complete — the hooks handle these.
 
 `;
     }
@@ -410,18 +411,11 @@ By default, tiny-brain uses **manual mode** for progress.json commits. This mean
 
 When you complete a task with a \`feat:\` or \`test:\` commit:
 1. The post-commit hook updates progress.json automatically
-2. You'll see a friendly message with instructions:
+2. You'll see a friendly message with instructions
+3. Commit the progress.json changes by running:
+   \`\`\`bash
+   npx tiny-brain commit-progress
    \`\`\`
-   📝 Progress tracking updated!
-
-      To commit progress.json changes, run:
-      git add .tiny-brain/progress/*.json
-      git commit -m "chore: update progress tracking"
-
-      💡 Tip: Enable auto-commit to skip this step:
-      npx tiny-brain config preferences set autoCommitProgress true
-   \`\`\`
-3. Commit the progress.json changes when you're ready
 
 ### Enabling Auto-Commit
 
@@ -470,6 +464,37 @@ Settings follow this precedence (highest to lowest):
 
 This allows you to set a global preference but override it per repository as needed.
 
+`;
+    }
+    /**
+     * Format the Worktree Merge Workflow section
+     */
+    formatWorktreeMergeSection() {
+        return `## Worktree Merge Workflow
+
+When merging a worktree branch back into the main branch, \`progress.json\` files may conflict because both branches tracked different task completions. The \`post-merge\` git hook handles this automatically.
+
+### How It Works
+
+1. After a merge, the hook detects if any \`.tiny-brain/progress/*.json\` or \`.tiny-brain/fixes/progress.json\` files changed
+2. If so, it re-runs \`npx tiny-brain sync-progress\` on all markdown sources to regenerate progress.json
+3. The regenerated files are staged and committed as \`chore: re-sync progress after merge\`
+
+### Handling Merge Conflicts in progress.json
+
+If you encounter a merge conflict in progress.json:
+1. Accept either version (it doesn't matter which)
+2. Complete the merge
+3. The post-merge hook will regenerate progress.json from the markdown sources automatically
+
+### Manual Re-sync
+
+If the hook doesn't run or you need to re-sync manually:
+\`\`\`bash
+npx tiny-brain sync-progress docs/prd/*/features/*.md
+npx tiny-brain sync-progress .tiny-brain/fixes/*.md
+\`\`\`
+
 `;
     }
     /**

package/dist/storage/local-filesystem-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-filesystem-adapter.d.ts","sourceRoot":"","sources":["../../src/storage/local-filesystem-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAOnF;;GAEG;AACH,qBAAa,6BAA8B,YAAW,wBAAwB;IAC5E,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,UAAU,CAAU;IACrB,WAAW,EAAE,MAAM,CAAC;gBAEf,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE;IAMvD,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAYV,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAanB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvF,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAqCxE,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBjD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAajE,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe5E,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5E,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAalE,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5D,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAiB/B,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDhG,iBAAiB,IAAI;QACnB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;QACzB,WAAW,CAAC,EAAE,OAAO,oCAAoC,EAAE,iBAAiB,CAAC;QAC7E,iBAAiB,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IAQD;;OAEG;YACW,qBAAqB;IAWnC;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB"}
+{"version":3,"file":"local-filesystem-adapter.d.ts","sourceRoot":"","sources":["../../src/storage/local-filesystem-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAC;AAOnF;;GAEG;AACH,qBAAa,6BAA8B,YAAW,wBAAwB;IAC5E,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,UAAU,CAAU;IACrB,WAAW,EAAE,MAAM,CAAC;gBAEf,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE;IAMvD,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAYV,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAanB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvF,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAqCxE,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBjD,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAajE,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW5E,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5E,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAalE,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5D,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAiB/B,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDhG,iBAAiB,IAAI;QACnB,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;QACzB,WAAW,CAAC,EAAE,OAAO,oCAAoC,EAAE,iBAAiB,CAAC;QAC7E,iBAAiB,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IAQD;;OAEG;YACW,qBAAqB;IAWnC;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB"}