docs: add context-mode routing rules to CLAUDE.md

Add mandatory routing rules section for context-mode MCP plugin,
documenting blocked commands, redirected tools, tool selection
hierarchy, and output constraints.

.github/workflows/action-security.yml

@@ -6,11 +6,9 @@ on:
   push:
     paths:
       - '**/action.yml'
-      - '**/action.yaml'
   pull_request:
     paths:
       - '**/action.yml'
-      - '**/action.yaml'
   merge_group:
 
 concurrency:

.github/workflows/pr-lint.yml

@@ -8,19 +8,17 @@ on:
       - main
       - master
     paths-ignore:
-      - '**.md'
-      - 'docs/**'
+      - '**/*.md'
       - '.github/*.md'
-      - 'LICENSE'
+      - 'LICENSE.md'
   pull_request:
     branches:
       - main
       - master
     paths-ignore:
-      - '**.md'
-      - 'docs/**'
+      - '**/*.md'
       - '.github/*.md'
-      - 'LICENSE'
+      - 'LICENSE.md'
   merge_group:
 
 env:

.github/workflows/security-suite.yml

@@ -7,16 +7,12 @@ on:
     paths:
       - '**/package.json'
       - '**/package-lock.json'
-      - '**/yarn.lock'
-      - '**/pnpm-lock.yaml'
-      - '**/requirements.txt'
       - '**/Dockerfile'
       - '**/*.py'
       - '**/*.js'
       - '**/*.ts'
       - '**/*.yml'
       - '**/*.yaml'
-      - '.github/workflows/**'
 
 permissions: {}
 

.github/workflows/sync-labels.yml

@@ -8,7 +8,6 @@ on:
       - main
       - master
     paths:
-      - '.github/labels.yml'
       - '.github/workflows/sync-labels.yml'
       - 'sync-labels/action.yml'
       - 'sync-labels/labels.yml'

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
         types: [markdown, python, yaml]
         files: ^(docs/.*|README\.md|CONTRIBUTING\.md|CHANGELOG\.md|.*\.py|.*\.ya?ml)$
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.10.9
+    rev: 0.10.11
     hooks:
       - id: uv-lock
       - id: uv-sync
@@ -67,30 +67,35 @@ repos:
     rev: v3.12.0-2
     hooks:
       - id: shfmt
-        args: ['--apply-ignore']
+        args: ["--apply-ignore"]
         exclude: '^_tests/.*\.sh$'
 
   - repo: https://github.com/shellcheck-py/shellcheck-py
     rev: v0.11.0.1
     hooks:
       - id: shellcheck
-        args: ['-x']
+        args: ["-x"]
         exclude: '^_tests/.*\.sh$'
 
   - repo: https://github.com/rhysd/actionlint
     rev: v1.7.11
     hooks:
       - id: actionlint
-        args: ['-shellcheck=']
+        args: ["-shellcheck="]
 
   - repo: https://github.com/bridgecrewio/checkov.git
-    rev: '3.2.508'
+    rev: "3.2.510"
     hooks:
       - id: checkov
         args:
-          - '--quiet'
+          - "--quiet"
 
   - repo: https://github.com/gitleaks/gitleaks
     rev: v8.30.1
     hooks:
       - id: gitleaks
+
+  - repo: https://github.com/mpalmer/action-validator
+    rev: v0.8.0
+    hooks:
+      - id: action-validator

CLAUDE.md

@@ -168,3 +168,78 @@ Check: `make check-version-refs`
 ---
 
 All actions modular and externally usable. No exceptions to any rule.
+
+## context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+### BLOCKED commands — do NOT attempt these
+
+#### curl / wget — BLOCKED
+
+Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
+Instead use:
+
+- `ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+#### Inline HTTP — BLOCKED
+
+Any Bash command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` is intercepted and replaced with an error message. Do NOT retry with Bash.
+Instead use:
+
+- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+#### WebFetch — BLOCKED
+
+WebFetch calls are denied entirely. The URL is extracted and you are told to use `ctx_fetch_and_index` instead.
+Instead use:
+
+- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+
+### REDIRECTED tools — use sandbox equivalents
+
+#### Bash (>20 lines output)
+
+Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+
+- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+#### Read (for analysis)
+
+If you are reading a file to **Edit** it → Read is correct (Edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `ctx_execute_file(path, language, code)` instead. Only your printed summary enters context. The raw file content stays in the sandbox.
+
+#### Grep (large results)
+
+Grep results can flood context. Use `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox. Only your printed summary enters context.
+
+### Tool selection hierarchy
+
+1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `ctx_execute(language, code)` | `ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+### Subagent routing
+
+When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt.
+Bash-type subagents are upgraded to general-purpose so they have access to MCP tools.
+You do NOT need to manually instruct subagents about context-mode.
+
+### Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+
+### ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |

Makefile

@@ -1,7 +1,7 @@
 # Makefile for GitHub Actions repository
 # Provides organized task management with parallel execution capabilities
 
-.PHONY: help all docs update-catalog lint format check clean install-tools test test-unit test-integration test-coverage generate-tests generate-tests-dry test-generate-tests docker-build docker-push docker-test docker-login docker-all release release-dry release-prep release-tag release-undo update-version-refs bump-major-version check-version-refs
+.PHONY: help all docs update-catalog lint format check clean install-tools test test-unit test-integration test-coverage generate-tests generate-tests-dry test-generate-tests docker-build docker-push docker-test docker-login docker-all release release-dry release-prep release-tag release-undo update-version-refs bump-major-version check-version-refs lint-actions
 .DEFAULT_GOAL := help
 
 # Colors for output
@@ -98,7 +98,7 @@ update-validators-dry: ## Preview validation rules changes (dry run)
 format: format-markdown format-yaml-json format-python ## Format all files
 	@echo "$(GREEN)✅ All files formatted$(RESET)"
 
-lint: lint-markdown lint-yaml lint-shell lint-python ## Run all linters
+lint: lint-markdown lint-yaml lint-shell lint-python lint-actions ## Run all linters
 	@echo "$(GREEN)✅ All linting completed$(RESET)"
 
 check: check-tools check-syntax check-local-refs ## Quick syntax and tool availability checks
@@ -322,6 +322,19 @@ lint-python: ## Lint Python files with ruff and pyright
 		echo "$(GREEN)✅ Python linting and type checking passed$(RESET)"; \
 	fi
 
+lint-actions: ## Validate GitHub Actions workflows and action.yml files
+	@echo "$(BLUE)🔍 Validating GitHub Actions...$(RESET)"
+	@if command -v pre-commit >/dev/null 2>&1; then \
+		if PRE_COMMIT_USE_UV=1 pre-commit run action-validator --all-files; then \
+			echo "$(GREEN)✅ Actions validation passed$(RESET)"; \
+		else \
+			echo "$(RED)❌ Actions validation failed$(RESET)" | tee -a $(LOG_FILE); \
+			exit 1; \
+		fi; \
+	else \
+		echo "$(YELLOW)⚠️ pre-commit not found, skipping action-validator$(RESET)"; \
+	fi
+
 # Check targets
 check-tools: ## Check if required tools are available
 	@echo "$(BLUE)🔧 Checking required tools...$(RESET)"

ansible-lint-fix/action.yml

@@ -45,7 +45,7 @@ runs:
   steps:
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'ansible-lint-fix'
         token: ${{ inputs.token }}

codeql-analysis/action.yml

@@ -107,7 +107,7 @@ runs:
   using: composite
   steps:
     - name: Validate inputs
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: codeql-analysis
         language: ${{ inputs.language }}

csharp-publish/action.yml

@@ -55,7 +55,7 @@ runs:
 
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'csharp-publish'
         token: ${{ inputs.token }}

docker-build/action.yml

@@ -147,7 +147,7 @@ runs:
 
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'docker-build'
         image-name: ${{ inputs.image-name }}

pr-lint/action.yml

@@ -40,7 +40,7 @@ runs:
   steps:
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: pr-lint
         token: ${{ inputs.token }}

pre-commit/action.yml

@@ -49,7 +49,7 @@ runs:
 
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'pre-commit'
         token: ${{ inputs.token }}

python-lint-fix/action.yml

@@ -64,7 +64,7 @@ runs:
   steps:
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'python-lint-fix'
         token: ${{ inputs.token }}

security-scan/action.yml

@@ -65,7 +65,7 @@ runs:
   steps:
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: security-scan
         gitleaks-license: ${{ inputs.gitleaks-license }}

stale/action.yml

@@ -43,7 +43,7 @@ runs:
 
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'stale'
         token: ${{ inputs.token || github.token }}

terraform-lint-fix/action.yml

@@ -78,7 +78,7 @@ runs:
 
     - name: Validate Inputs
       id: validate
-      uses: ivuorinen/actions/validate-inputs@f98ae7cd7d0feb1f9d6b01de0addbb11414cfc73
+      uses: ivuorinen/actions/validate-inputs@5cc7373a22402ee8985376bc713f00e09b5b2edb
       with:
         action-type: 'terraform-lint-fix'
         token: ${{ inputs.token || github.token }}