Merge PR #3322: correct Kiro steering inclusion contract

.kiro/README.md

@@ -158,14 +158,14 @@ Steering files provide always-on rules and context that shape how the agent work
 
 | File | Inclusion | Description |
 |------|-----------|-------------|
-| `coding-style.md` | auto | Core coding style rules: immutability, file organization, error handling, and code quality standards. Loaded in every conversation. |
-| `security.md` | auto | Security best practices including mandatory checks, secret management, and security response protocol. Loaded in every conversation. |
-| `testing.md` | auto | Testing requirements: 80% coverage minimum, TDD workflow, and test types (unit, integration, E2E). Loaded in every conversation. |
-| `development-workflow.md` | auto | Development process, PR workflow, and collaboration patterns. Loaded in every conversation. |
-| `git-workflow.md` | auto | Git commit conventions, branching strategies, and version control best practices. Loaded in every conversation. |
-| `patterns.md` | auto | Common design patterns and architectural principles. Loaded in every conversation. |
-| `performance.md` | auto | Performance optimization guidelines and profiling strategies. Loaded in every conversation. |
-| `lessons-learned.md` | auto | Project-specific patterns and learnings. Edit this file to capture your team's conventions. Loaded in every conversation. |
+| `coding-style.md` | always | Core coding style rules: immutability, file organization, error handling, and code quality standards. Loaded in every conversation. |
+| `security.md` | always | Security best practices including mandatory checks, secret management, and security response protocol. Loaded in every conversation. |
+| `testing.md` | always | Testing requirements: 80% coverage minimum, TDD workflow, and test types (unit, integration, E2E). Loaded in every conversation. |
+| `development-workflow.md` | always | Development process, PR workflow, and collaboration patterns. Loaded in every conversation. |
+| `git-workflow.md` | always | Git commit conventions, branching strategies, and version control best practices. Loaded in every conversation. |
+| `patterns.md` | always | Common design patterns and architectural principles. Loaded in every conversation. |
+| `performance.md` | always | Performance optimization guidelines and profiling strategies. Loaded in every conversation. |
+| `lessons-learned.md` | always | Project-specific patterns and learnings. Edit this file to capture your team's conventions. Loaded in every conversation. |
 | `typescript-patterns.md` | fileMatch: `*.ts,*.tsx` | TypeScript-specific patterns, type safety, and best practices. Loaded when editing TypeScript files. |
 | `python-patterns.md` | fileMatch: `*.py` | Python-specific patterns, type hints, and best practices. Loaded when editing Python files. |
 | `golang-patterns.md` | fileMatch: `*.go` | Go-specific patterns, concurrency, and best practices. Loaded when editing Go files. |
@@ -181,15 +181,17 @@ Steering files provide always-on rules and context that shape how the agent work
 | `review-mode.md` | manual | Code review context mode. Invoke with `#review-mode` for thorough reviews. |
 | `research-mode.md` | manual | Research context mode. Invoke with `#research-mode` for exploration and learning. |
 
-Steering files with `auto` inclusion are loaded automatically. No action needed — they apply as soon as you install them.
+Steering files with `always` inclusion are loaded automatically. No action needed — they apply as soon as you install them.
+
+> **Upgrading an existing install:** the installer never overwrites steering files that already exist in your project. If you installed before these files switched to `always`, change `inclusion: auto` to `inclusion: always` in the frontmatter of `coding-style.md`, `security.md`, `testing.md`, `development-workflow.md`, `git-workflow.md`, `patterns.md`, `performance.md`, and `lessons-learned.md` in your `.kiro/steering/` directory.
 
 To create your own, add a markdown file to `.kiro/steering/` with YAML frontmatter:
 
 ```yaml
 ---
-inclusion: auto        # auto | fileMatch | manual
-name: my-steering      # required if inclusion is auto
-description: Brief explanation of what this steering file contains
+inclusion: always         # always | auto | fileMatch | manual
+name: my-steering         # required if inclusion is auto
+description: Brief explanation of what this steering file contains # required if inclusion is auto
 fileMatchPattern: "*.ts"  # required if inclusion is fileMatch
 ---
 
@@ -325,14 +327,14 @@ Shell scripts used by hooks to perform quality checks and formatting.
 │   ├── ... and 26 more           # (testing, deployment, docker, etc.)
 │   └── (each skill has a SKILL.md with YAML frontmatter)
 ├── steering/                     # 22 steering files
-│   ├── coding-style.md           # Auto-loaded coding style rules
-│   ├── security.md               # Auto-loaded security rules
-│   ├── testing.md                # Auto-loaded testing rules
-│   ├── development-workflow.md   # Auto-loaded dev workflow
-│   ├── git-workflow.md           # Auto-loaded git workflow
-│   ├── patterns.md               # Auto-loaded design patterns
-│   ├── performance.md            # Auto-loaded performance rules
-│   ├── lessons-learned.md        # Auto-loaded project patterns
+│   ├── coding-style.md           # Always-loaded coding style rules
+│   ├── security.md               # Always-loaded security rules
+│   ├── testing.md                # Always-loaded testing rules
+│   ├── development-workflow.md   # Always-loaded dev workflow
+│   ├── git-workflow.md           # Always-loaded git workflow
+│   ├── patterns.md               # Always-loaded design patterns
+│   ├── performance.md            # Always-loaded performance rules
+│   ├── lessons-learned.md        # Always-loaded project patterns
 │   ├── typescript-patterns.md    # Loaded for .ts/.tsx files
 │   ├── typescript-security.md    # Loaded for .ts/.tsx files
 │   ├── python-patterns.md        # Loaded for .py files
@@ -395,7 +397,7 @@ All files are yours to modify after installation. The installer never overwrites
 5. **Run quality gate**: Trigger the `quality-gate` hook before committing
 6. **Verify comprehensively**: Use the `verification-loop` skill before creating PRs
 
-The auto-loaded steering files (coding-style, security, testing) ensure consistent standards throughout your session.
+The always-loaded steering files (coding-style, security, testing) ensure consistent standards throughout your session.
 
 ## Usage Examples
 
@@ -466,7 +468,7 @@ kiro-cli --agent code-reviewer
 > /agent swap security-reviewer
 > "Analyze the API endpoints for security vulnerabilities"
 
-# 4. The security.md steering file is auto-loaded, ensuring:
+# 4. The security.md steering file is always-loaded, ensuring:
 # - No hardcoded secrets
 # - Proper error handling
 # - Secure crypto usage
@@ -486,7 +488,7 @@ kiro-cli --agent python-reviewer
 > "Review the type hints and error handling"
 > /python-patterns  # Invoke Python-specific patterns skill
 
-# Language-specific steering files are auto-loaded:
+# Language-specific steering files are loaded automatically on file match:
 # - golang-patterns.md loads when editing .go files
 # - python-patterns.md loads when editing .py files
 # - typescript-patterns.md loads when editing .ts/.tsx files

.kiro/docs/longform-guide.md

@@ -41,9 +41,10 @@ Skills provide structured guidance for complex, multi-step processes.
 
 ### 3. Steering Files as Persistent Context
 
-Steering files inject rules and patterns into every conversation:
+Steering files inject rules and patterns into conversations:
 
-- **Auto-inclusion**: Always-on rules (coding style, security, testing)
+- **Always-inclusion**: Always-on rules (coding style, security, testing)
+- **Auto-inclusion**: Files are automatically included when your request matches the description.
 - **File-match**: Conditional rules based on file type (TypeScript patterns for .ts files)
 - **Manual**: Context modes you invoke explicitly (dev-mode, review-mode)
 
@@ -146,7 +147,7 @@ The `lessons-learned.md` steering file acts as your project's evolving knowledge
 
 ```markdown
 ---
-inclusion: auto
+inclusion: always
 description: Project-specific patterns and decisions
 ---
 
@@ -236,9 +237,9 @@ If an agent's output isn't quite right, provide specific feedback and let it ite
 
 Don't try to describe a complex workflow in a single prompt. Use skills that encode best practices.
 
-### 8. Combine Auto and Manual Steering
+### 8. Combine Steering Inclusion Modes
 
-Use auto-inclusion for universal rules, file-match for language-specific patterns, and manual for context switching.
+Use always-inclusion for universal rules, auto-inclusion for context-heavy guidance that should only load when relevant, file-match for language-specific patterns, and manual for context switching.
 
 ## Common Pitfalls
 

.kiro/docs/security-guide.md

@@ -49,7 +49,7 @@ AI agents are powerful development tools, but they introduce unique security con
 **Why**: It's easier to maintain security from the start than to retrofit it later.
 
 **Practice**:
-- Enable auto-inclusion security steering files
+- Enable always-inclusion security steering files
 - Use TDD workflow with security test cases
 - Include security requirements in planning phase
 - Document security decisions in lessons-learned
@@ -81,7 +81,7 @@ Plan a user authentication feature with these security requirements:
 **Risk**: May introduce vulnerabilities like SQL injection, XSS, or insecure deserialization.
 
 **Mitigation**:
-- Enable security steering files (auto-loaded)
+- Enable security steering files (always-loaded)
 - Use git-push-review hook to catch issues before commit
 - Run security-reviewer agent after implementation
 - Include security test cases in TDD workflow
@@ -203,7 +203,7 @@ Plan a user authentication feature with these security requirements:
 **Key Rules to Include**:
 ```markdown
 ---
-inclusion: auto
+inclusion: always
 description: Security best practices and vulnerability prevention
 ---
 
@@ -434,7 +434,7 @@ For production:
 
 ### Before Starting Development
 
-- [ ] Security steering files enabled (auto-inclusion)
+- [ ] Security steering files enabled (always-inclusion)
 - [ ] Security-focused hooks enabled (git-push-review, console-log-check)
 - [ ] MCP servers reviewed and configured securely
 - [ ] Secrets management strategy in place

.kiro/docs/shortform-guide.md

@@ -78,7 +78,7 @@ Type `/` in chat and select from the menu, or use:
 
 ## Steering Files
 
-### Auto-Loaded (Always Active)
+### Always-Loaded (Always Active)
 
 - `coding-style.md` - Code organization and naming
 - `development-workflow.md` - Dev process and PR workflow
@@ -267,9 +267,10 @@ cat .kiro/skills/skill-name/SKILL.md
 
 ### Steering File Not Loading
 
-1. Check frontmatter: `inclusion: auto` or `fileMatch` or `manual`
+1. Check frontmatter: `inclusion: always` or `auto` or `fileMatch` or `manual`
 2. For fileMatch, verify pattern: `fileMatchPattern: "*.ts,*.tsx"`
-3. For manual, invoke with: `#filename`
+3. For auto, verify `name` and `description` are set and the description matches your request
+4. For manual, invoke with: `#filename`
 
 ### Script Not Executing
 
@@ -326,7 +327,7 @@ Instructions for the agent...
 1. Create `.kiro/steering/my-rules.md`:
 ```markdown
 ---
-inclusion: auto
+inclusion: always
 description: My custom rules
 ---
 
@@ -335,7 +336,7 @@ description: My custom rules
 Rules and patterns...
 ```
 
-2. Auto-loaded in every conversation
+2. Always-loaded in every conversation
 
 ### Add Your Own Hook
 

.kiro/install.sh

@@ -138,6 +138,6 @@ echo "Next steps:"
 echo "  1. Open your project in Kiro"
 echo "  2. Agents: Automatic in IDE, /agent swap in CLI"
 echo "  3. Skills: Available via / menu in chat"
-echo "  4. Steering files with 'auto' inclusion load automatically"
+echo "  4. Steering files with 'always' inclusion load automatically"
 echo "  5. Toggle hooks in the Agent Hooks panel"
 echo "  6. Copy desired MCP servers from .kiro/settings/mcp.json.example to .kiro/settings/mcp.json"

.kiro/steering/coding-style.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: coding-style
 description: Core coding style rules including immutability, file organization, error handling, and code quality standards.
 ---

.kiro/steering/development-workflow.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: development-workflow
 description: Development workflow guidelines for planning, TDD, code review, and commit pipeline
 ---

.kiro/steering/git-workflow.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: git-workflow
 description: Git workflow guidelines for conventional commits and pull request process
 ---

.kiro/steering/lessons-learned.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: lessons-learned
 description: Project-specific patterns, preferences, and lessons learned over time (user-editable)
 ---

.kiro/steering/patterns.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: patterns
 description: Common design patterns including repository pattern, API response format, and skeleton project approach
 ---

.kiro/steering/performance.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: performance
 description: Performance optimization guidelines including model selection strategy, context window management, and build troubleshooting
 ---

.kiro/steering/security.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: security
 description: Security best practices including mandatory checks, secret management, and security response protocol.
 ---

.kiro/steering/testing.md

@@ -1,5 +1,5 @@
 ---
-inclusion: auto
+inclusion: always
 name: testing
 description: Testing requirements including 80% coverage, TDD workflow, and test types.
 ---

tests/docs/kiro-steering-inclusion.test.js

@@ -0,0 +1,106 @@
+/**
+ * Regression coverage for Kiro steering file inclusion modes.
+ *
+ * Kiro only loads a steering file in every conversation with `inclusion: always`;
+ * `auto` loads it only when the request matches its description.
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const KIRO_DIR = path.join(__dirname, '..', '..', '.kiro');
+const STEERING_DIR = path.join(KIRO_DIR, 'steering');
+const README = path.join(KIRO_DIR, 'README.md');
+
+const ALWAYS_ON = [
+  'coding-style.md',
+  'security.md',
+  'testing.md',
+  'development-workflow.md',
+  'git-workflow.md',
+  'patterns.md',
+  'performance.md',
+  'lessons-learned.md',
+];
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    return true;
+  } catch (error) {
+    console.log(`  ✗ ${name}`);
+    console.log(`    Error: ${error.message}`);
+    return false;
+  }
+}
+
+function readFrontmatter(file) {
+  const content = fs.readFileSync(path.join(STEERING_DIR, file), 'utf8');
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  assert.ok(match, `${file} should start with YAML frontmatter`);
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^(\w+):\s*(.*)$/);
+    if (field) fields[field[1]] = field[2].trim();
+  }
+  return fields;
+}
+
+function readReadmeInclusions() {
+  const readme = fs.readFileSync(README, 'utf8');
+  const inclusions = {};
+  for (const row of readme.matchAll(/^\| `([\w-]+\.md)` \| (always|auto|manual|fileMatch)\b/gm)) {
+    inclusions[row[1]] = row[2];
+  }
+  return inclusions;
+}
+
+function runTests() {
+  console.log('\n=== Testing Kiro steering inclusion modes ===\n');
+
+  let passed = 0;
+  let failed = 0;
+
+  const steeringFiles = fs.readdirSync(STEERING_DIR).filter(file => file.endsWith('.md'));
+
+  if (test('core steering files use always inclusion', () => {
+    for (const file of ALWAYS_ON) {
+      assert.strictEqual(
+        readFrontmatter(file).inclusion,
+        'always',
+        `${file} should use inclusion: always so it loads in every conversation`
+      );
+    }
+  })) passed++; else failed++;
+
+  if (test('README steering table matches each file frontmatter', () => {
+    const documented = readReadmeInclusions();
+    for (const file of steeringFiles) {
+      assert.ok(documented[file], `${file} should be listed in the .kiro/README.md steering table`);
+      assert.strictEqual(
+        readFrontmatter(file).inclusion,
+        documented[file],
+        `${file} frontmatter inclusion should match the README table`
+      );
+    }
+  })) passed++; else failed++;
+
+  if (test('steering files declare the fields their inclusion mode requires', () => {
+    for (const file of steeringFiles) {
+      const fields = readFrontmatter(file);
+      if (fields.inclusion === 'auto') {
+        assert.ok(fields.name && fields.description, `${file} uses auto inclusion and needs name and description`);
+      }
+      if (fields.inclusion === 'fileMatch') {
+        assert.ok(fields.fileMatchPattern, `${file} uses fileMatch inclusion and needs fileMatchPattern`);
+      }
+    }
+  })) passed++; else failed++;
+
+  console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();