fileMatch inclusion mode does not work for global steering (~/.kiro/steering/)

[msayed-treezor]

Before opening, please confirm:

• I have searched for duplicate or closed issues

Operating System

macOS 26.5.1 (Apple M1)

Kiro Version

0.12.263

Bug Description

The fileMatch inclusion mode in steering files does not trigger when the steering file is located in ~/.kiro/steering/ (global scope). The steering file is never loaded into context, even when a file matching the pattern is actively open and read by the agent.

This creates an undocumented limitation:

Inclusion Mode	Global (~/.kiro/steering/)	Workspace (.kiro/steering/)
always	✅ Works	✅ Works
manual	✅ Works	✅ Works
auto	✅ Works	✅ Works
fileMatch	❌ Does not trigger	✅ Works

The official documentation (https://kiro.dev/docs/steering/) describes fileMatch as a valid inclusion mode without specifying it is workspace-only. This is misleading for users who want conditional loading in their global steering.

Related: #884 (fileMatch also broken in Spec mode for workspace steering).

Steps to Reproduce

1. Create a global steering file ~/.kiro/steering/99-test-filematch.md with this content:

    ---
    inclusion: fileMatch
    fileMatchPattern: "**/*.php"
    ---
    
    # TEST FILEMATCH GLOBAL
    
    If you see this message, say exactly: "FILEMATCH GLOBAL WORKS"
   

2. Open any .php file in the editor (e.g., app/Http/Controller/ExecuteController.php)

3. Start a new conversation (to reload steering fresh)

4. Ask the agent: "Which steering files are active for this interaction? Do you see one containing 'TEST FILEMATCH GLOBAL'?"

5. Observe: only always-mode global steering files appear in the "Including Steering Documents" list. The fileMatch steering is never loaded.

Expected Behavior

The steering file 99-test-filematch.md should be loaded into context when a .php file is open and read by the agent, since the fileMatchPattern: "**/*.php" matches the active file.

The fileMatch inclusion mode should work identically whether the steering file is in ~/.kiro/steering/ (global) or .kiro/steering/ (workspace). If this is intentionally unsupported, it should be documented explicitly.

Conversation ID

No response

Additional Context

Logical root cause hypothesis: fileMatch likely resolves the glob pattern relative to the workspace root. Global steering files have no single workspace root to resolve against, so the pattern matching fails silently.

Related issues:

• File path match steering inclusion doesn't seem to work in Spec mode #884 — fileMatch also broken in Spec mode for workspace steering

Suggested fix:

• Option A: Resolve fileMatchPattern against the currently active workspace root, even for global steering files
• Option B: Document explicitly that fileMatch is workspace-only (not supported in ~/.kiro/steering/)
• Option C: Emit a warning in the IDE when a global steering file uses fileMatch (since it silently never triggers)

Workaround: Use inclusion: auto with a descriptive name and description field instead of fileMatch for global steering files that need conditional loading.

[github-actions]

🤖 Potential Duplicate Detected

This issue appears to be similar to:

• #9117: Global steering files from ~/.kiro/steering/ not loaded into agent context (85% similar)
• #8977: fileMatch steering should match across workspace roots in multi-root workspaces (85% similar)

What happens next?

• ⏰ This issue will be automatically closed in 3 days
• 🏷️ If this is not a duplicate, you can prevent automatic closure by adding a comment or reacting with 👎 to this message.
• 💬 Comment on the original issue if you have additional information

Why is this marked as duplicate?
Both issues report problems with global steering files from ~/.kiro/steering/ not being loaded into agent context. The new issue specifically focuses on fileMatch inclusion mode not working globally, while #9117 appears to be about global steering files not loading in general - these are very likely the same underlying problem.

[msayed-treezor]

This is not a duplicate of either issue:

• Global steering files from ~/.kiro/steering/ not loaded into agent context #9117 reports global steering with inclusion: always not loading at all. In my case, always mode works perfectly from ~/.kiro/steering/ (7 global always-steering files load correctly). Only fileMatch silently fails.

• fileMatch steering should match across workspace roots in multi-root workspaces #8977 is a feature request about fileMatch not matching files across multiple workspace roots in a multi-root workspace. My issue is different: fileMatch doesn't trigger at all when the steering file is in ~/.kiro/steering/ (global), even in a single-root workspace with a matching .php file open and read. The author of fileMatch steering should match across workspace roots in multi-root workspaces #8977 confirms their fileMatch works within their workspace root — mine doesn't work at all from global scope.

Summary: These are three distinct problems:

• Global steering files from ~/.kiro/steering/ not loaded into agent context #9117: always broken globally (general loading failure)
• fileMatch steering should match across workspace roots in multi-root workspaces #8977: fileMatch broken cross-root (multi-root scope issue)
• fileMatch inclusion mode does not work for global steering (~/.kiro/steering/) #9176 (mine): fileMatch broken from global steering entirely (glob resolution fails without workspace root)

[github-actions]

Thank you for your feedback! 🙏

The duplicate label has been removed and this issue has been sent back for maintainer review.

A maintainer will review this issue shortly.

[AnilMaktala]

Thanks for the detailed report and root-cause hypothesis. The global steering and fileMatch systems have received several improvements since 0.12.263 — including fixes to multi-root fileMatch resolution and global hooks loading.

Could you retest on the latest version (IDE 1.0.242) and let us know whether fileMatch from ~/.kiro/steering/ now triggers correctly when a matching file is open?

To update: download from kiro.dev.

[github-actions]

This issue has been automatically closed due to inactivity. It has been 7 days since we requested additional information.

If you still need help with this issue, please feel free to reopen it or create a new issue with the requested details.