@hyperdrive.bot/gut 0.1.16 → 0.2.1

package/README.md

@@ -8,9 +8,39 @@ Git Unified Tooling - Enhanced git with workspace intelligence for entity-based
 [![Downloads/week](https://img.shields.io/npm/dw/@devsquad/gut.svg)](https://npmjs.org/package/@devsquad/gut)
 
 <!-- toc -->
+* [Untracked Entities](#untracked-entities)
+* [Commit all changes in focused entities only (default — unchanged)](#commit-all-changes-in-focused-entities-only-default--unchanged)
+* [Also commit in super-repo root + any unregistered nested repos](#also-commit-in-super-repo-root--any-unregistered-nested-repos)
 * [Usage](#usage)
 * [Commands](#commands)
 <!-- tocstop -->
+
+# Untracked Entities
+
+`gut status --all` surfaces dirty state for **any** `.git` repo inside the workspace tree, whether or not it's registered as an entity in `.gut/config.json`. This includes:
+
+- **The super-repo root itself** (the git repo containing `.gut/`)
+- **Nested repos** that exist on disk but have not been run through `gut entity add`
+
+Discovery is always-on for reading (`gut status --all`). For writing, it's opt-in via a flag on `gut commit`:
+
+```sh
+# Commit all changes in focused entities only (default — unchanged)
+gut commit -a -m "ship feature"
+
+# Also commit in super-repo root + any unregistered nested repos
+gut commit -a -u -m "ship feature and sync workspace"
+```
+
+Safety guards on the `-u` path:
+
+- **Refuses to commit on** `main`, `master`, `live`, `prod`, `production`
+- **Skips** repos in an in-progress merge, rebase, or cherry-pick
+- **Skips** repos with detached `HEAD`
+- **Stages untracked files** (equivalent of `git add -A`) when `-a` is present, so newly-created files land in the commit
+
+Escape hatch: set `GUT_SKIP_DISCOVERY=1` to disable the walk entirely.
+
 # Usage
 <!-- usage -->
 ```sh-session
@@ -18,7 +48,7 @@ $ npm install -g @hyperdrive.bot/gut
 $ gut COMMAND
 running command...
 $ gut (--version)
-@hyperdrive.bot/gut/0.1.16-alpha.0 linux-x64 node-v22.22.2
+@hyperdrive.bot/gut/0.2.1-alpha.0 linux-x64 node-v22.22.2
 $ gut --help [COMMAND]
 USAGE
   $ gut COMMAND
@@ -295,12 +325,14 @@ Commit changes in focused repositories
 
 ```
 USAGE
-  $ gut commit [-a] [--amend] [-m <value>]
+  $ gut commit [-a] [--amend] [-u] [-m <value>]
 
 FLAGS
-  -a, --all              Stage all changes before committing
-  -m, --message=<value>  Commit message
-      --amend            Amend the previous commit
+  -a, --all                Stage all changes before committing
+  -m, --message=<value>    Commit message
+  -u, --include-untracked  Also commit in discovered .git repos not registered as entities (e.g. super-repo root, nested
+                           repos). Fails closed on main/master/live/prod.
+      --amend              Amend the previous commit
 
 DESCRIPTION
   Commit changes in focused repositories
@@ -310,6 +342,8 @@ EXAMPLES
 
   $ gut commit --message "Add feature"
 
+  $ gut commit -a -u -m "Ship WIP across workspace"
+
   $ gut commit
 ```
 

package/dist/base-command.d.ts

@@ -1,6 +1,7 @@
 import { Command } from '@oclif/core';
 import { Entity, EntityType } from './models/entity.model.js';
 import { ConfigService } from './services/config.service.js';
+import { DiscoveryService } from './services/discovery.service.js';
 import { EntityService } from './services/entity.service.js';
 import { FocusService } from './services/focus.service.js';
 import { GitService } from './services/git.service.js';
@@ -8,6 +9,7 @@ import { TicketService } from './services/ticket.service.js';
 import { WorktreeService } from './services/worktree.service.js';
 export declare abstract class BaseCommand extends Command {
     protected configService: ConfigService;
+    protected discoveryService: DiscoveryService;
     protected entityService: EntityService;
     protected focusService: FocusService;
     protected gitService: GitService;

package/dist/base-command.js

@@ -1,5 +1,6 @@
 import { Command } from '@oclif/core';
 import { ConfigService } from './services/config.service.js';
+import { DiscoveryService } from './services/discovery.service.js';
 import { EntityService } from './services/entity.service.js';
 import { FocusService } from './services/focus.service.js';
 import { GitService } from './services/git.service.js';
@@ -19,6 +20,7 @@ const ENTITY_TYPE_EMOJI = {
 const DEFAULT_ENTITY_EMOJI = '📁';
 export class BaseCommand extends Command {
     configService;
+    discoveryService;
     entityService;
     focusService;
     gitService;
@@ -46,6 +48,7 @@ export class BaseCommand extends Command {
         // Initialize services
         this.configService = new ConfigService();
         this.entityService = new EntityService(this.configService);
+        this.discoveryService = new DiscoveryService(this.configService, this.entityService);
         this.focusService = new FocusService(this.configService);
         this.gitService = new GitService();
         this.ticketService = new TicketService(this.configService);

package/dist/commands/commit.d.ts

@@ -5,7 +5,11 @@ export default class Commit extends BaseCommand {
     static flags: {
         all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         amend: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'include-untracked': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         message: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private commitUntrackedRepo;
+    private filterDirty;
+    private hasInProgressMergeOrRebase;
 }

package/dist/commands/commit.js

@@ -1,13 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import ora from 'ora';
 import { BaseCommand } from '../base-command.js';
+const PROTECTED_BRANCHES = new Set(['live', 'main', 'master', 'prod', 'production']);
 export default class Commit extends BaseCommand {
     static description = 'Commit changes in focused repositories';
     static examples = [
         '<%= config.bin %> <%= command.id %> -m "Fix bug"',
         '<%= config.bin %> <%= command.id %> --message "Add feature"',
+        '<%= config.bin %> <%= command.id %> -a -u -m "Ship WIP across workspace"',
         '<%= config.bin %> <%= command.id %>', // Interactive mode
     ];
     static flags = {
@@ -20,6 +24,12 @@ export default class Commit extends BaseCommand {
             default: false,
             description: 'Amend the previous commit',
         }),
+        'include-untracked': Flags.boolean({
+            char: 'u',
+            default: false,
+            description: 'Also commit in discovered .git repos not registered as entities '
+                + '(e.g. super-repo root, nested repos). Fails closed on main/master/live/prod.',
+        }),
         message: Flags.string({
             char: 'm',
             description: 'Commit message',
@@ -29,8 +39,8 @@ export default class Commit extends BaseCommand {
     async run() {
         const { flags } = await this.parse(Commit);
         const focusedEntities = await this.focusService.getFocusedEntities();
-        if (focusedEntities.length === 0) {
-            this.error('No entities are focused. Use "gut focus <entity>" first.');
+        if (focusedEntities.length === 0 && !flags['include-untracked']) {
+            this.error('No entities are focused. Use "gut focus <entity>" first, or pass -u to commit untracked repos.');
         }
         let { message } = flags;
         // Interactive prompt for commit message if not provided
@@ -59,8 +69,9 @@ export default class Commit extends BaseCommand {
         for (const entity of focusedEntities) {
             const spinner = ora(`Committing in ${chalk.cyan(entity.name)}`).start();
             try {
+                const entityPath = this.entityService.resolveEntityPath(entity);
                 // Check if there are changes to commit
-                const status = await this.gitService.getStatus(entity.path);
+                const status = await this.gitService.getStatus(entityPath);
                 const hasChanges = status.changes.length > 0 || status.untracked.length > 0;
                 if (!hasChanges && !flags.amend) {
                     spinner.info(chalk.yellow(`${entity.name}: No changes to commit`));
@@ -74,8 +85,8 @@ export default class Commit extends BaseCommand {
                 };
                 // Amend without changing message, or commit with new message
                 await (!message && flags.amend
-                    ? this.gitService.exec(['commit', '--amend', '--no-edit'], { cwd: entity.path })
-                    : this.gitService.commit(entity.path, message || '', options));
+                    ? this.gitService.exec(['commit', '--amend', '--no-edit'], { cwd: entityPath })
+                    : this.gitService.commit(entityPath, message || '', options));
                 spinner.succeed(chalk.green(`✓ ${entity.name}: Committed successfully`));
                 results.success.push(entity.name);
             }
@@ -85,6 +96,16 @@ export default class Commit extends BaseCommand {
                 results.failed.push({ error: errorMessage, repo: entity.name });
             }
         }
+        // Discovered-untracked-repos loop (opt-in via -u / --include-untracked)
+        const untrackedResults = [];
+        if (flags['include-untracked']) {
+            this.log(chalk.bold('\n🔎 Committing in discovered untracked repos\n'));
+            const discovered = await this.discoveryService.discoverUntracked();
+            for (const repo of discovered) {
+                const result = await this.commitUntrackedRepo(repo, message || '', flags);
+                untrackedResults.push(result);
+            }
+        }
         // Summary
         this.log(chalk.bold('\n📊 Commit Summary'));
         this.log(chalk.dim('─'.repeat(50)));
@@ -100,8 +121,126 @@ export default class Commit extends BaseCommand {
                 this.log(chalk.red(`  - ${failure.repo}: ${failure.error}`));
             }
         }
-        if (results.success.length > 0) {
+        if (flags['include-untracked']) {
+            const committed = untrackedResults.filter(r => r.committed);
+            const skipped = untrackedResults.filter(r => !r.committed);
+            if (committed.length > 0) {
+                this.log(chalk.green(`✓ Untracked committed: ${committed.length} repos`));
+                for (const r of committed) {
+                    this.log(chalk.green(`  - ${r.relativePath}: ${r.sha?.slice(0, 10)} on ${r.branch}`));
+                }
+            }
+            if (skipped.length > 0) {
+                this.log(chalk.yellow(`○ Untracked skipped: ${skipped.length} repos`));
+                for (const r of skipped) {
+                    this.log(chalk.yellow(`  - ${r.relativePath}: ${r.reason}`));
+                }
+            }
+        }
+        else if (results.success.length > 0 || results.noChanges.length > 0) {
+            // Nudge if there's workspace-root or nested dirt waiting to be committed.
+            const anyUntracked = await this.discoveryService.discoverUntracked();
+            const dirty = await this.filterDirty(anyUntracked);
+            if (dirty.length > 0) {
+                this.log('');
+                this.log(chalk.dim(`💡 ${dirty.length} untracked ${dirty.length === 1 ? 'repo has' : 'repos have'} `
+                    + `uncommitted changes (super-repo root or nested). Pass ${chalk.cyan('-u')} to include them.`));
+            }
+        }
+        if (results.success.length > 0 || untrackedResults.some(r => r.committed)) {
             this.log(chalk.dim('\nTip: Use "gut push" to push commits to remote'));
         }
+        // Hint to register any newly-committed untracked repo
+        const newlyCommitted = untrackedResults.filter(r => r.committed && !r.path.endsWith(this.configService.getWorkspaceRoot()));
+        if (newlyCommitted.length > 0) {
+            this.log('');
+            this.log(chalk.dim(`💡 Committed on ${newlyCommitted.length} untracked ${newlyCommitted.length === 1 ? 'repo' : 'repos'}. `
+                + 'Consider registering with `gut entity add <name> <type> <path>` to track long-term.'));
+        }
+    }
+    async commitUntrackedRepo(repo, message, flags) {
+        const spinner = ora(`Committing in ${chalk.cyan(repo.relativePath)}`).start();
+        const base = {
+            branch: '',
+            committed: false,
+            path: repo.path,
+            relativePath: repo.relativePath,
+        };
+        try {
+            // Guard: in-progress merge/rebase
+            if (this.hasInProgressMergeOrRebase(repo.path)) {
+                spinner.warn(chalk.yellow(`${repo.relativePath}: in-progress merge/rebase — skipped`));
+                return { ...base, reason: 'merge or rebase in progress' };
+            }
+            const status = await this.gitService.getStatus(repo.path);
+            base.branch = status.branch;
+            // Guard: detached HEAD
+            if (!status.branch || status.branch === 'HEAD') {
+                spinner.warn(chalk.yellow(`${repo.relativePath}: detached HEAD — skipped`));
+                return { ...base, reason: 'detached HEAD' };
+            }
+            // Guard: protected branch
+            if (PROTECTED_BRANCHES.has(status.branch)) {
+                spinner.warn(chalk.yellow(`${repo.relativePath}: refusing to commit on ${status.branch}`));
+                return { ...base, reason: `protected branch: ${status.branch}` };
+            }
+            const hasChanges = status.changes.length > 0 || status.untracked.length > 0;
+            if (!hasChanges && !flags.amend) {
+                spinner.info(chalk.dim(`${repo.relativePath}: no changes`));
+                return { ...base, reason: 'no changes' };
+            }
+            // In untracked-repo mode, -a means "stage everything including new files"
+            // (bmad-workflow / Pirlo writes new files). Plain `git commit -a` only
+            // stages modified tracked files and would miss the new code.
+            if (flags.all && !flags.amend) {
+                await this.gitService.exec(['add', '-A'], { cwd: repo.path });
+            }
+            const options = { all: false, amend: flags.amend };
+            await (!message && flags.amend
+                ? this.gitService.exec(['commit', '--amend', '--no-edit'], { cwd: repo.path })
+                : this.gitService.commit(repo.path, message, options));
+            const sha = (await this.gitService.exec(['rev-parse', 'HEAD'], { cwd: repo.path })).trim();
+            spinner.succeed(chalk.green(`✓ ${repo.relativePath}: committed ${sha.slice(0, 10)} on ${status.branch}`));
+            return { ...base, committed: true, sha };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            spinner.fail(chalk.red(`✗ ${repo.relativePath}: ${errorMessage}`));
+            return { ...base, reason: errorMessage };
+        }
+    }
+    async filterDirty(repos) {
+        const dirty = [];
+        for (const repo of repos) {
+            try {
+                const status = await this.gitService.getStatus(repo.path);
+                if (status.hasChanges)
+                    dirty.push(repo);
+            }
+            catch {
+                // Ignore unreadable repos in the hint path.
+            }
+        }
+        return dirty;
+    }
+    hasInProgressMergeOrRebase(repoPath) {
+        const gitDir = path.join(repoPath, '.git');
+        let resolvedGitDir = gitDir;
+        try {
+            // Handle .git files (worktrees / submodules) — `gitdir: <path>` format
+            const stat = fs.statSync(gitDir);
+            if (stat.isFile()) {
+                const content = fs.readFileSync(gitDir, 'utf8').trim();
+                const match = /^gitdir:\s*(.+)$/m.exec(content);
+                if (match) {
+                    resolvedGitDir = path.isAbsolute(match[1]) ? match[1] : path.resolve(repoPath, match[1]);
+                }
+            }
+        }
+        catch {
+            return false;
+        }
+        const markers = ['MERGE_HEAD', 'rebase-merge', 'rebase-apply', 'CHERRY_PICK_HEAD'];
+        return markers.some(marker => fs.existsSync(path.join(resolvedGitDir, marker)));
     }
 }

package/dist/commands/status.d.ts

@@ -8,6 +8,8 @@ export default class Status extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    private displayDiscoveredRepo;
     private displayEnhancedStatus;
     private displayEntityStatus;
+    private safeGetStatus;
 }

package/dist/commands/status.js

@@ -1,6 +1,7 @@
 import { Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { BaseCommand } from '../base-command.js';
+const SKIP_DISCOVERY_ENV = 'GUT_SKIP_DISCOVERY';
 export default class Status extends BaseCommand {
     static description = 'Show git status for focused entities';
     static examples = [
@@ -27,13 +28,8 @@ export default class Status extends BaseCommand {
         const entities = flags.all
             ? this.entityService.getAllEntities()
             : await this.focusService.getFocusedEntities();
-        if (entities.length === 0) {
-            if (flags.all) {
-                this.error('No entities configured');
-            }
-            else {
-                this.error('No entities focused. Use "gut focus <entity>" first.');
-            }
+        if (entities.length === 0 && !flags.all) {
+            this.error('No entities focused. Use "gut focus <entity>" first.');
         }
         // Collect status for each entity
         const statuses = [];
@@ -82,15 +78,47 @@ export default class Status extends BaseCommand {
                 });
             }
         }
+        // Discover untracked repos (super-repo root + unregistered nested repos).
+        // Only meaningful when --all is set; focus-scoped status stays focus-scoped.
+        const untracked = [];
+        if (flags.all && process.env[SKIP_DISCOVERY_ENV] !== '1') {
+            const discovered = await this.discoveryService.discoverUntracked();
+            for (const repo of discovered) {
+                const statusResult = await this.safeGetStatus(repo.path);
+                untracked.push({ ...repo, ...statusResult });
+            }
+        }
         // Output results
         if (flags.json) {
-            this.log(JSON.stringify(statuses, null, 2));
+            this.log(JSON.stringify({ statuses, untracked }, null, 2));
             return;
         }
         // Enhanced workspace-style display
-        await this.displayEnhancedStatus(statuses, flags.verbose);
+        await this.displayEnhancedStatus(statuses, untracked, flags.verbose);
+    }
+    displayDiscoveredRepo(repo, verbose) {
+        const label = repo.isWorkspaceRoot ? '. (super-repo root)' : repo.relativePath;
+        const branch = repo.branch || '(empty)';
+        const changesText = repo.changes.length > 0 ? `${repo.changes.length} changes` : '';
+        const untrackedText = repo.untracked.length > 0 ? `${repo.untracked.length} untracked` : '';
+        const statusText = [changesText, untrackedText].filter(Boolean).join(', ') || 'clean';
+        this.log(`  📁 ${label} — branch: ${chalk.cyan(branch)} — ${statusText}`);
+        if (verbose) {
+            for (const change of repo.changes.slice(0, 3)) {
+                this.log(`      ${change}`);
+            }
+            if (repo.changes.length > 3) {
+                this.log(`      ... and ${repo.changes.length - 3} more`);
+            }
+            for (const file of repo.untracked.slice(0, 2)) {
+                this.log(`      ?? ${file}`);
+            }
+            if (repo.untracked.length > 2) {
+                this.log(`      ... and ${repo.untracked.length - 2} more`);
+            }
+        }
     }
-    async displayEnhancedStatus(statuses, verbose) {
+    async displayEnhancedStatus(statuses, untracked, verbose) {
         const currentFocus = await this.focusService.getCurrentFocus();
         // Header with workspace context
         this.log(chalk.bold('\n=== DevSquad Workspace Status ==='));
@@ -142,27 +170,49 @@ export default class Status extends BaseCommand {
                 this.log('');
             }
         }
+        // Untracked entities section (discovered .git repos not in .gut/config.json)
+        const dirtyUntracked = untracked.filter(u => u.hasChanges);
+        const hasUntrackedToShow = dirtyUntracked.length > 0 || (verbose && untracked.length > 0);
+        if (hasUntrackedToShow) {
+            this.log(chalk.bold(chalk.yellow('⚠ UNTRACKED ENTITIES:')));
+            const toShow = verbose ? untracked : dirtyUntracked;
+            for (const repo of toShow) {
+                this.displayDiscoveredRepo(repo, verbose);
+            }
+            this.log(chalk.dim('  💡 Run `gut entity add <name> <type> <path>` to track, or pass'));
+            this.log(chalk.dim('     `gut commit --include-untracked` to commit in place.'));
+            this.log('');
+        }
         // Enhanced summary
         const dirtyRepos = statuses.filter(s => s.hasChanges).length;
         const totalRepos = statuses.filter(s => !s.error).length;
         const readyToCommit = statuses.filter(s => s.hasChanges).map(s => s.entity);
         this.log(chalk.bold('=== Summary ==='));
-        if (dirtyRepos === 0) {
+        if (dirtyRepos === 0 && dirtyUntracked.length === 0) {
             this.log(`✨ All ${totalRepos} repositories are clean`);
         }
         else {
-            this.log(`✨ ${dirtyRepos} ${dirtyRepos === 1 ? 'repo' : 'repos'} with changes`);
-            if (readyToCommit.length > 0) {
-                this.log(`🚀 Ready to commit across: ${chalk.cyan(readyToCommit.join(', '))}`);
+            if (dirtyRepos > 0) {
+                this.log(`✨ ${dirtyRepos} ${dirtyRepos === 1 ? 'repo' : 'repos'} with changes`);
+                if (readyToCommit.length > 0) {
+                    this.log(`🚀 Ready to commit across: ${chalk.cyan(readyToCommit.join(', '))}`);
+                }
+            }
+            if (dirtyUntracked.length > 0) {
+                this.log(`⚠ ${dirtyUntracked.length} untracked ${dirtyUntracked.length === 1 ? 'repo' : 'repos'} with changes `
+                    + `(pass ${chalk.cyan('-u')} to gut commit)`);
             }
         }
         // Suggested actions
-        if (dirtyRepos > 0) {
+        if (dirtyRepos > 0 || dirtyUntracked.length > 0) {
             this.log('');
             this.log(chalk.dim('Suggested actions:'));
-            this.log(chalk.dim('• gut add .          # Stage all changes'));
-            this.log(chalk.dim('• gut commit -m "..."  # Commit across repos'));
-            this.log(chalk.dim('• gut push           # Push to remotes'));
+            this.log(chalk.dim('• gut add .                      # Stage all changes'));
+            this.log(chalk.dim('• gut commit -m "..."              # Commit across focused entities'));
+            if (dirtyUntracked.length > 0) {
+                this.log(chalk.dim('• gut commit -a -u -m "..."        # Also commit untracked repos'));
+            }
+            this.log(chalk.dim('• gut push                         # Push to remotes'));
         }
     }
     displayEntityStatus(status, verbose) {
@@ -190,4 +240,28 @@ export default class Status extends BaseCommand {
             }
         }
     }
+    async safeGetStatus(repoPath) {
+        try {
+            const status = await this.gitService.getStatus(repoPath);
+            return {
+                ahead: status.ahead,
+                behind: status.behind,
+                branch: status.branch,
+                changes: status.changes,
+                hasChanges: status.hasChanges,
+                untracked: status.untracked,
+            };
+        }
+        catch (error) {
+            return {
+                ahead: 0,
+                behind: 0,
+                branch: '',
+                changes: [],
+                error: error instanceof Error ? error.message : String(error),
+                hasChanges: false,
+                untracked: [],
+            };
+        }
+    }
 }

package/dist/models/entity.model.d.ts

@@ -232,6 +232,13 @@ export interface RepoStatus {
     path: string;
     untracked: string[];
 }
+export interface DiscoveredRepo {
+    entityName?: string;
+    isRegistered: boolean;
+    isWorkspaceRoot: boolean;
+    path: string;
+    relativePath: string;
+}
 export interface WorktreeEntityRecord {
     branch: string;
     entityName: string;

package/dist/services/discovery.service.d.ts

@@ -0,0 +1,14 @@
+import { DiscoveredRepo } from '../models/entity.model.js';
+import { ConfigService } from './config.service.js';
+import { EntityService } from './entity.service.js';
+export declare class DiscoveryService {
+    private configService;
+    private entityService;
+    constructor(configService: ConfigService, entityService: EntityService);
+    discover(maxDepth?: number): Promise<DiscoveredRepo[]>;
+    discoverUntracked(maxDepth?: number): Promise<DiscoveredRepo[]>;
+    private buildRegisteredPathIndex;
+    private hasGitEntry;
+    private relativize;
+    private shouldSkipDir;
+}

package/dist/services/discovery.service.js

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const DEFAULT_MAX_DEPTH = 5;
+const IGNORE_DIRS = new Set([
+    '.cache',
+    '.next',
+    '.serverless',
+    '.specstory',
+    '.turbo',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'out',
+]);
+const IGNORE_DIR_PATTERNS = [
+    /^\.serverless-/,
+    /^\.composer-stage-/,
+];
+export class DiscoveryService {
+    configService;
+    entityService;
+    constructor(configService, entityService) {
+        this.configService = configService;
+        this.entityService = entityService;
+    }
+    async discover(maxDepth = DEFAULT_MAX_DEPTH) {
+        const workspaceRoot = this.configService.getWorkspaceRoot();
+        const registeredPaths = this.buildRegisteredPathIndex();
+        const results = [];
+        const queue = [{ absPath: workspaceRoot, depth: 0 }];
+        while (queue.length > 0) {
+            const { absPath, depth } = queue.shift();
+            const isWorkspaceRoot = absPath === workspaceRoot;
+            if (this.hasGitEntry(absPath)) {
+                const relativePath = this.relativize(workspaceRoot, absPath);
+                const registered = registeredPaths.get(path.resolve(absPath));
+                results.push({
+                    entityName: registered,
+                    isRegistered: Boolean(registered),
+                    isWorkspaceRoot,
+                    path: absPath,
+                    relativePath,
+                });
+                // A nested repo's subtree is its own concern — stop descending.
+                // Exception: the workspace root. The super-repo itself owns submodules
+                // and nested untracked repos; we must descend past it to find them.
+                if (!isWorkspaceRoot)
+                    continue;
+            }
+            if (depth >= maxDepth) {
+                continue;
+            }
+            let children;
+            try {
+                children = fs.readdirSync(absPath);
+            }
+            catch {
+                continue;
+            }
+            for (const child of children) {
+                if (this.shouldSkipDir(child))
+                    continue;
+                const childPath = path.join(absPath, child);
+                let stat;
+                try {
+                    stat = fs.lstatSync(childPath);
+                }
+                catch {
+                    continue;
+                }
+                // Skip symlinks to avoid loops and leaking outside the workspace.
+                if (stat.isSymbolicLink())
+                    continue;
+                if (!stat.isDirectory())
+                    continue;
+                queue.push({ absPath: childPath, depth: depth + 1 });
+            }
+        }
+        return results;
+    }
+    async discoverUntracked(maxDepth = DEFAULT_MAX_DEPTH) {
+        const all = await this.discover(maxDepth);
+        return all.filter(repo => !repo.isRegistered);
+    }
+    buildRegisteredPathIndex() {
+        const index = new Map();
+        for (const entity of this.entityService.getAllEntities()) {
+            const absolute = path.resolve(this.entityService.resolveEntityPath(entity));
+            index.set(absolute, entity.name);
+        }
+        return index;
+    }
+    hasGitEntry(dirPath) {
+        // .git can be a directory (normal repo) or a file (submodule / worktree).
+        const gitPath = path.join(dirPath, '.git');
+        try {
+            return fs.existsSync(gitPath);
+        }
+        catch {
+            return false;
+        }
+    }
+    relativize(workspaceRoot, absPath) {
+        if (absPath === workspaceRoot)
+            return '.';
+        const rel = path.relative(workspaceRoot, absPath);
+        return rel === '' ? '.' : rel;
+    }
+    shouldSkipDir(name) {
+        if (IGNORE_DIRS.has(name))
+            return true;
+        return IGNORE_DIR_PATTERNS.some(pattern => pattern.test(name));
+    }
+}

package/dist/services/discovery.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/discovery.service.test.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigService } from './config.service.js';
+import { DiscoveryService } from './discovery.service.js';
+import { EntityService } from './entity.service.js';
+function mkdir(p) {
+    fs.mkdirSync(p, { recursive: true });
+}
+function mkGitDir(p) {
+    mkdir(p);
+    mkdir(path.join(p, '.git'));
+}
+function mkGitFile(p, content = 'gitdir: ../.git/worktrees/x\n') {
+    mkdir(p);
+    fs.writeFileSync(path.join(p, '.git'), content);
+}
+describe('DiscoveryService', () => {
+    let workspaceRoot;
+    let configService;
+    let entityService;
+    let discoveryService;
+    beforeEach(() => {
+        workspaceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'gut-discovery-'));
+        mkdir(path.join(workspaceRoot, '.gut'));
+        fs.writeFileSync(path.join(workspaceRoot, '.gut', 'config.json'), JSON.stringify({ entities: [], initialized: true, workspace: workspaceRoot }));
+        mkGitDir(workspaceRoot);
+        configService = new ConfigService(workspaceRoot);
+        entityService = new EntityService(configService);
+        discoveryService = new DiscoveryService(configService, entityService);
+    });
+    afterEach(() => {
+        fs.rmSync(workspaceRoot, { force: true, recursive: true });
+    });
+    describe('discover()', () => {
+        it('always returns the workspace root as a discovered repo', async () => {
+            const result = await discoveryService.discover();
+            const workspaceRootHit = result.find(r => r.isWorkspaceRoot);
+            expect(workspaceRootHit).toBeDefined();
+            expect(workspaceRootHit.relativePath).toBe('.');
+            expect(workspaceRootHit.path).toBe(workspaceRoot);
+            expect(workspaceRootHit.isRegistered).toBe(false);
+        });
+        it('finds nested .git dirs as directories', async () => {
+            mkGitDir(path.join(workspaceRoot, 'packages', 'cli', 'foo'));
+            const result = await discoveryService.discover();
+            const foo = result.find(r => r.relativePath === path.join('packages', 'cli', 'foo'));
+            expect(foo).toBeDefined();
+            expect(foo.isRegistered).toBe(false);
+        });
+        it('treats .git files (worktree/submodule) as repo markers', async () => {
+            mkGitFile(path.join(workspaceRoot, 'packages', 'cli', 'worktree'));
+            const result = await discoveryService.discover();
+            const hit = result.find(r => r.relativePath === path.join('packages', 'cli', 'worktree'));
+            expect(hit).toBeDefined();
+        });
+        it('does not descend into a repo subtree once a .git is found', async () => {
+            // A repo at packages/cli/foo, and a nested .git inside its subdir should NOT be found.
+            mkGitDir(path.join(workspaceRoot, 'packages', 'cli', 'foo'));
+            mkGitDir(path.join(workspaceRoot, 'packages', 'cli', 'foo', 'vendored', 'nested'));
+            const result = await discoveryService.discover();
+            const nested = result.find(r => r.relativePath === path.join('packages', 'cli', 'foo', 'vendored', 'nested'));
+            expect(nested).toBeUndefined();
+        });
+        it('ignores node_modules/**, dist/**, build/**, .serverless/**, .serverless-*/', async () => {
+            mkGitDir(path.join(workspaceRoot, 'node_modules', 'pkg'));
+            mkGitDir(path.join(workspaceRoot, 'dist', 'hidden'));
+            mkGitDir(path.join(workspaceRoot, 'build', 'hidden'));
+            mkGitDir(path.join(workspaceRoot, '.serverless', 'hidden'));
+            mkGitDir(path.join(workspaceRoot, '.serverless-contacts', 'hidden'));
+            mkGitDir(path.join(workspaceRoot, '.composer-stage-1', 'hidden'));
+            const result = await discoveryService.discover();
+            expect(result.filter(r => !r.isWorkspaceRoot)).toHaveLength(0);
+        });
+        it('respects maxDepth — deeper repos are not found', async () => {
+            // Repo at depth 6: packages/a/b/c/d/e/.git
+            const deepPath = path.join(workspaceRoot, 'packages', 'a', 'b', 'c', 'd', 'e');
+            mkGitDir(deepPath);
+            const resultShallow = await discoveryService.discover(5);
+            expect(resultShallow.find(r => r.relativePath.endsWith('e'))).toBeUndefined();
+            const resultDeep = await discoveryService.discover(10);
+            expect(resultDeep.find(r => r.relativePath.endsWith('e'))).toBeDefined();
+        });
+        it('marks registered entities with isRegistered + entityName', async () => {
+            const entityDir = path.join(workspaceRoot, 'packages', 'cli', 'foo');
+            mkGitDir(entityDir);
+            fs.writeFileSync(path.join(workspaceRoot, '.gut', 'config.json'), JSON.stringify({
+                entities: [{ name: 'foo', path: 'packages/cli/foo', type: 'tool' }],
+                initialized: true,
+                workspace: workspaceRoot,
+            }));
+            // Rebuild services so the new config is picked up.
+            configService = new ConfigService(workspaceRoot);
+            entityService = new EntityService(configService);
+            discoveryService = new DiscoveryService(configService, entityService);
+            const result = await discoveryService.discover();
+            const foo = result.find(r => r.relativePath === path.join('packages', 'cli', 'foo'));
+            expect(foo).toBeDefined();
+            expect(foo.isRegistered).toBe(true);
+            expect(foo.entityName).toBe('foo');
+        });
+        it('skips symlinks to avoid loops and leaking outside workspace', async () => {
+            // Create an external "other" repo and symlink it inside the workspace.
+            const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'gut-outside-'));
+            try {
+                mkGitDir(outside);
+                fs.symlinkSync(outside, path.join(workspaceRoot, 'linked'), 'dir');
+                const result = await discoveryService.discover();
+                expect(result.find(r => r.relativePath === 'linked')).toBeUndefined();
+            }
+            finally {
+                fs.rmSync(outside, { force: true, recursive: true });
+            }
+        });
+    });
+    describe('discoverUntracked()', () => {
+        it('returns only repos not covered by a registered entity', async () => {
+            mkGitDir(path.join(workspaceRoot, 'packages', 'cli', 'registered'));
+            mkGitDir(path.join(workspaceRoot, 'packages', 'cli', 'untracked'));
+            fs.writeFileSync(path.join(workspaceRoot, '.gut', 'config.json'), JSON.stringify({
+                entities: [{ name: 'registered', path: 'packages/cli/registered', type: 'tool' }],
+                initialized: true,
+                workspace: workspaceRoot,
+            }));
+            configService = new ConfigService(workspaceRoot);
+            entityService = new EntityService(configService);
+            discoveryService = new DiscoveryService(configService, entityService);
+            const result = await discoveryService.discoverUntracked();
+            const relPaths = result.map(r => r.relativePath).sort();
+            expect(relPaths).toEqual(['.', path.join('packages', 'cli', 'untracked')].sort());
+        });
+        it('super-repo root is always untracked (never in the entity list)', async () => {
+            const result = await discoveryService.discoverUntracked();
+            const root = result.find(r => r.isWorkspaceRoot);
+            expect(root).toBeDefined();
+            expect(root.isRegistered).toBe(false);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperdrive.bot/gut",
-  "version": "0.1.16",
+  "version": "0.2.1",
   "description": "Git Unified Tooling - Enhanced git with workspace intelligence for entity-based organization",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",