@hyperdrive.bot/gut 0.1.15 → 0.2.0

package/README.md

@@ -9,8 +9,36 @@ Git Unified Tooling - Enhanced git with workspace intelligence for entity-based
 
 <!-- toc -->
 * [Usage](#usage)
+* [Untracked Entities](#untracked-entities)
 * [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 +46,7 @@ $ npm install -g @hyperdrive.bot/gut
 $ gut COMMAND
 running command...
 $ gut (--version)
-@hyperdrive.bot/gut/0.1.15-alpha.0 linux-x64 node-v22.22.2
+@hyperdrive.bot/gut/0.1.16 linux-x64 node-v22.22.2
 $ gut --help [COMMAND]
 USAGE
   $ gut COMMAND
@@ -35,6 +63,7 @@ USAGE
 * [`gut auth status`](#gut-auth-status)
 * [`gut back`](#gut-back)
 * [`gut checkout BRANCH`](#gut-checkout-branch)
+* [`gut claude init`](#gut-claude-init)
 * [`gut commit`](#gut-commit)
 * [`gut context`](#gut-context)
 * [`gut contexts`](#gut-contexts)
@@ -265,6 +294,29 @@ EXAMPLES
   $ gut checkout -b PRD-123 --from main
 ```
 
+## `gut claude init`
+
+Scaffold Claude Code configuration for gut
+
+```
+USAGE
+  $ gut claude init [--dry-run] [-f]
+
+FLAGS
+  -f, --force    Overwrite existing gut section and command files
+      --dry-run  Preview changes without writing files
+
+DESCRIPTION
+  Scaffold Claude Code configuration for gut
+
+EXAMPLES
+  $ gut claude init
+
+  $ gut claude init --dry-run
+
+  $ gut claude init --force
+```
+
 ## `gut commit`
 
 Commit changes in focused repositories

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/claude/init.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base-command.js';
+export default class ClaudeInit extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    protected get requiresInit(): boolean;
+    run(): Promise<void>;
+}

package/dist/commands/claude/init.js

@@ -0,0 +1,120 @@
+import { Flags } from '@oclif/core';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { BaseCommand } from '../../base-command.js';
+const GUT_START = '<!-- gut:start -->';
+const GUT_END = '<!-- gut:end -->';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const templateDir = join(__dirname, '..', '..', '..', 'templates', 'claude-init');
+export default class ClaudeInit extends BaseCommand {
+    static description = 'Scaffold Claude Code configuration for gut';
+    static examples = [
+        '<%= config.bin %> claude init',
+        '<%= config.bin %> claude init --dry-run',
+        '<%= config.bin %> claude init --force',
+    ];
+    static flags = {
+        'dry-run': Flags.boolean({ description: 'Preview changes without writing files' }),
+        force: Flags.boolean({ char: 'f', description: 'Overwrite existing gut section and command files' }),
+    };
+    get requiresInit() {
+        return false;
+    }
+    async run() {
+        const { flags } = await this.parse(ClaudeInit);
+        const dryRun = flags['dry-run'];
+        const force = flags.force;
+        // Validate template directory
+        if (!existsSync(templateDir)) {
+            this.error('Template directory not found at: ' + templateDir);
+        }
+        const results = [];
+        // --- CLAUDE.md handler ---
+        const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
+        const templateContent = readFileSync(join(templateDir, 'claude-md-section.md'), 'utf-8');
+        if (!existsSync(claudeMdPath)) {
+            // No CLAUDE.md — create new file
+            if (dryRun) {
+                results.push({ action: 'created', file: 'CLAUDE.md' });
+            }
+            else {
+                writeFileSync(claudeMdPath, templateContent);
+                results.push({ action: 'created', file: 'CLAUDE.md' });
+            }
+        }
+        else {
+            const existing = readFileSync(claudeMdPath, 'utf-8');
+            if (existing.includes(GUT_START)) {
+                if (force) {
+                    // Remove existing gut section and re-append
+                    const cleaned = existing.replace(new RegExp(GUT_START + '[\\s\\S]*?' + GUT_END, 'g'), '').trimEnd();
+                    if (!dryRun) {
+                        writeFileSync(claudeMdPath, cleaned + '\n\n' + templateContent);
+                    }
+                    results.push({ action: 'modified', file: 'CLAUDE.md' });
+                }
+                else {
+                    this.log('gut section already exists (use --force to overwrite)');
+                    results.push({ action: 'skipped', file: 'CLAUDE.md' });
+                }
+            }
+            else {
+                // Append gut section
+                if (!dryRun) {
+                    writeFileSync(claudeMdPath, existing + '\n\n' + templateContent);
+                }
+                results.push({ action: 'modified', file: 'CLAUDE.md' });
+            }
+        }
+        // --- .claude/commands/ handler ---
+        const commandsDir = join(process.cwd(), '.claude', 'commands');
+        const commandFiles = ['gut-status.md', 'gut-affected.md'];
+        if (!existsSync(commandsDir)) {
+            if (dryRun) {
+                this.log('.claude/commands/ → create directory');
+            }
+            else {
+                mkdirSync(commandsDir, { recursive: true });
+            }
+        }
+        for (const filename of commandFiles) {
+            const source = join(templateDir, 'commands', filename);
+            const target = join(commandsDir, filename);
+            if (existsSync(target) && !force) {
+                this.log(`${filename} → already exists (use --force to overwrite)`);
+                results.push({ action: 'skipped', file: `.claude/commands/${filename}` });
+            }
+            else {
+                if (!dryRun) {
+                    // Ensure directory exists (in case only some files existed)
+                    mkdirSync(commandsDir, { recursive: true });
+                    copyFileSync(source, target);
+                }
+                results.push({ action: 'created', file: `.claude/commands/${filename}` });
+            }
+        }
+        // --- Summary ---
+        const heading = dryRun ? 'gut claude init (dry run)' : 'gut claude init';
+        this.log('');
+        this.log(chalk.bold(heading));
+        this.log('');
+        for (const { action, file } of results) {
+            const label = action === 'created'
+                ? chalk.green(action)
+                : action === 'modified'
+                    ? chalk.yellow(action)
+                    : chalk.dim(action);
+            this.log(`  ${file} → ${label}`);
+        }
+        this.log('');
+        if (dryRun) {
+            this.log('No files were modified. Remove --dry-run to apply.');
+        }
+        else {
+            this.log('Run /gut-status in Claude Code to verify');
+        }
+    }
+}

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;