release: workflow + main-scope agent fixes (v8.20.91)

.icc/README.md

@@ -0,0 +1,20 @@
+# ICC Config Variants
+
+Two ready-made configs are provided so you can swap behaviors without editing defaults:
+
+- `config.relaxed.json`: mirrors the currently deployed settings (non-strict main scope; IAC-only infra protection; agents blocked from Task/SlashCommand/Skill).
+- `config.strict-main-scope.json`: coordination-only main scope, agent delegation encouraged, MCP enabled; broad main-scope tool blacklist to force delegation while keeping agents free to work.
+
+Usage:
+
+1) To apply one, copy it to your user install:
+
+   ```bash
+   cp .icc/config.relaxed.json ~/.claude/icc.config.json
+   # or
+   cp .icc/config.strict-main-scope.json ~/.claude/icc.config.json
+   ```
+
+2) Restart Claude Code or rerun `make install` so hooks pick up the change.
+
+Project defaults remain unchanged; these files are opt-in convenience presets.

.icc/config.relaxed.json

@@ -0,0 +1,17 @@
+{
+  "enforcement": {
+    "strict_main_scope": false,
+    "infrastructure_protection": {
+      "enabled": true,
+      "enforce_iac_only": true
+    },
+    "tool_blacklist": {
+      "main_scope_only": [],
+      "agents_only": ["Task", "SlashCommand", "Skill"]
+    }
+  },
+  "subagents": {
+    "auto_delegation": false,
+    "max_concurrent": 0
+  }
+}

.icc/config.strict-main-scope.json

@@ -0,0 +1,54 @@
+{
+  "tools": {
+    "sequential_thinking": true,
+    "mcp_tools_enabled": true
+  },
+  "enforcement": {
+    "strict_main_scope": true,
+    "strict_main_scope_message": "Main scope is coordination-only. Use Task tool to delegate work to agents.",
+    "infrastructure_protection": {
+      "enabled": true,
+      "enforce_iac_only": true
+    },
+    "tool_blacklist": {
+      "universal": [
+        "rm -rf /",
+        "dd if=/dev/zero of=/dev/sda",
+        "mkfs",
+        "fdisk /dev/sda",
+        "> /dev/sda",
+        "format c:"
+      ],
+      "main_scope_only": [
+        "Write",
+        "Edit",
+        "MultiEdit",
+        "NotebookEdit",
+        "Bash",
+        "ApplyPatch",
+        "GitCommit",
+        "GitPush",
+        "NpmInstall",
+        "PipInstall",
+        "Terraform",
+        "Ansible",
+        "AnsiblePlaybook",
+        "Kubectl",
+        "Docker"
+      ],
+      "agents_only": [],
+      "infrastructure": [
+        "kubectl",
+        "helm",
+        "terraform",
+        "ansible-playbook",
+        "docker",
+        "docker-compose"
+      ]
+    }
+  },
+  "subagents": {
+    "auto_delegation": true,
+    "max_concurrent": 2
+  }
+}

CHANGELOG.md

@@ -6,29 +6,73 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [8.20.84] - 2025-11-16
+## [8.20.91] - 2025-11-19
 
 ### Added
-- Reintroduced contextual logic to `memory-first-reminder.js`, targeting prompts about credentials, configuration, AgentTasks, and deployments while logging stats to `~/.claude/stats/memory-usage.json`.
-- New PreToolUse integration test (`test-project-scope-enforcement.js`) ensures stdin parsing and permission decisions stay aligned with enforcement expectations.
+- Optional workflow enforcement hook (`workflow-enforcement.js`) that ensures the configured Task → Plan → Review → Execute → Review → Document sequence runs in order for both Main Scope and agents.
+- Config support: `workflow.enforcement` block in `icc.config.default.json` plus a ready-to-use `icc.config.workflow-reviewed.json` preset.
+- Integration tests for the workflow state machine (uses per-test config/state directories).
+
+### Testing
+- `bash tests/run-tests.sh`
+
+## [8.20.90] - 2025-11-19
+
+### Added
+- `enforcement.main_scope_has_agent_privileges` flag treats the Main Scope as if it were an agent (all agent-only allowances, including bypassing strict main-scope enforcement). `icc.config.main-scope-dev.json` enables this so Main Scope can run Dev/Ops work directly, while other presets keep it off.
+
+### Changed
+- Marker detection is centralized: hooks now call `lib/marker-detection` for context so config changes (or env override `ICC_MAIN_SCOPE_AGENT`) propagate consistently.
+- Summary/documentation enforcement and PM constraints both rely on the shared helper, so treating the Main Scope as an agent automatically relaxes their PM-only restrictions.
+
+### Testing
+- `bash tests/run-tests.sh`
+
+## [8.20.89] - 2025-11-19
+
+### Added
+- New `sample-configs/icc.config.main-scope-dev.json` preset for Linux/macOS systems: guardrails remain enabled while Main Scope can run curated `git`/`gh` commands without spawning agents.
+- Sample config docs now list every preset and explain how to install via `make install CONFIG_FILE=...`.
+- Context injection now always surfaces project best practices and explicit memory-before/after guidance (without requiring `/icc-search-memory`).
+- ALL-CAPS filename enforcement retains execution-pattern guidance while auto-suggesting lowercase/kebab alternatives.
+
+### Changed
+- All sample configs now force best-practices/constraints output and keep memory integration plus git branch protection enabled.
+- Main-scope coordination whitelist can be extended via `enforcement.main_scope_allowed_bash_commands` so presets can safely allow additional `gh`/`git` commands.
+- README highlights the available presets for quick reference.
+- Context-injection now instructs the Main Scope to start every response with the rendered constraints + best-practice block so users see the guardrails continuously.
 
 ### Fixed
-- All PreToolUse hooks now read `CLAUDE_TOOL_INPUT` so they receive the same payloads as UserPromptSubmit hooks; helper/unit tests enforce the new precedence.
-- Project scope enforcement blocks edits outside the active project (except `~/.claude/CLAUDE.md`) and surfaces proper deny responses, addressing the prior silent allow behavior.
+- Documentation writes via Bash heredoc to docs*/documentation directories are no longer blocked by infra protection, even if the text contains infrastructure keywords.
 
 ### Testing
 - `bash tests/run-tests.sh`
 
----
+## [8.20.88] - 2025-11-17
 
-## [8.20.85] - 2025-11-16
+### Added
+- Two opt-in ICC presets under `.icc/`: `config.relaxed.json` (legacy behavior) and `config.strict-main-scope.json` (coordination-only main scope). Included `.icc/README.md` with quick swap instructions.
+
+### Fixed
+- Main-scope enforcement allowlist now includes default `docs/` and `documentation/` directories even when config paths are unset, preventing false blocks in projects like GovStack.
+- Added unit coverage for docs/documentation allowlist handling.
+
+### Testing
+- `bash tests/run-tests.sh`
+
+## [8.20.87] - 2025-11-17
+
+### Added
+- Context injection now surfaces MCP availability hints for PM/Main Scope when `mcp_integrations` entries are enabled, encouraging use of GitHub/GitLab/Jira MCP tools when installed.
+- Reintroduced contextual logic to `memory-first-reminder.js`, targeting prompts about credentials, configuration, AgentTasks, and deployments while logging stats to `~/.claude/stats/memory-usage.json`.
+- New PreToolUse integration test (`test-project-scope-enforcement.js`) ensures stdin parsing and permission decisions stay aligned with enforcement expectations.
 
 ### Changed
-- Transcript retention now archives older session JSONL files and trims the active session only when necessary, preventing multi-gigabyte loads that crashed Claude on Linux.
-- Per-project transcript quota lowered to 10 MB (configurable via `CLAUDE_PROJECT_TRANSCRIPTS_MAX_BYTES`).
+- Main Scope enforcement honors `tools.mcp_tools_enabled`; MCP tools are allowed only when explicitly enabled, making the toggle effective.
 
 ### Fixed
-- Memory stats logging writes compact JSON and adds rotation so hooks no longer blow the V8 heap when telemetry grows too large.
+- All PreToolUse hooks now read `CLAUDE_TOOL_INPUT` so they receive the same payloads as UserPromptSubmit hooks; helper/unit tests enforce the new precedence.
+- Project scope enforcement blocks edits outside the active project (except `~/.claude/CLAUDE.md`) and surfaces proper deny responses, addressing the prior silent allow behavior.
 
 ### Testing
 - `bash tests/run-tests.sh`
@@ -54,6 +98,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [8.20.85] - 2025-11-16
+
+### Changed
+- Transcript retention now archives older session JSONL files and trims the active session only when necessary, preventing multi-gigabyte loads that crashed Claude on Linux.
+- Per-project transcript quota lowered to 10 MB (configurable via `CLAUDE_PROJECT_TRANSCRIPTS_MAX_BYTES`).
+
+### Fixed
+- Memory stats logging writes compact JSON and adds rotation so hooks no longer blow the V8 heap when telemetry grows too large.
+
+### Testing
+- `bash tests/run-tests.sh`
+
+---
+
 ## [8.20.78] - 2025-11-14
 
 ### Fixed

Makefile

@@ -21,19 +21,26 @@ else
     ENV_FILE_ABS :=
 endif
 
+ifdef CONFIG_FILE
+    CONFIG_FILE_ABS := $(shell realpath $(CONFIG_FILE) 2>/dev/null || echo $(CONFIG_FILE))
+else
+    CONFIG_FILE_ABS :=
+endif
+
 # Default shows help
 help:
 	@echo "Intelligent Claude Code - Installation"
 	@echo ""
 	@echo "Usage:"
-	@echo "  make install   [HOST=ip] [USER=user] [TARGET_PATH=/path] [MCP_CONFIG=/path/to/mcps.json] [ENV_FILE=/path/to/.env] [KEY=~/.ssh/id_rsa | PASS=password]"
+	@echo "  make install   [HOST=ip] [USER=user] [TARGET_PATH=/path] [CONFIG_FILE=sample-configs/icc.config.sub-agent.json] [MCP_CONFIG=/path/to/mcps.json] [ENV_FILE=/path/to/.env] [KEY=~/.ssh/id_rsa | PASS=password]"
 	@echo "  make uninstall [HOST=ip] [USER=user] [TARGET_PATH=/path] [KEY=~/.ssh/id_rsa | PASS=password] [FORCE=true]"
 	@echo "  make test                        # Run installation tests"
 	@echo ""
 	@echo "Parameters:"
 	@echo "  HOST - Remote host IP (omit for local installation)"
 	@echo "  USER - Remote username (required for remote installation)"
 	@echo "  TARGET_PATH - Target path (omit for user scope ~/.claude/)"  
+	@echo "  CONFIG_FILE - Path to icc.config JSON to deploy (default icc.config.default.json)"
 	@echo "  MCP_CONFIG - Path to MCP servers configuration JSON file"
 	@echo "  ENV_FILE - Path to .env file with environment variables"
 	@echo "  KEY  - SSH key for remote (default: ~/.ssh/id_rsa)"
@@ -102,9 +109,10 @@ install:
 			-i localhost, \
 			-c local \
 			-e "ansible_shell_type=sh" \
-			-e "target_path=$(TARGET_PATH)" \
-			-e "mcp_config_file=$(MCP_CONFIG_ABS)" \
-			-e "env_file=$(ENV_FILE_ABS)"; \
+            -e "target_path=$(TARGET_PATH)" \
+            -e "mcp_config_file=$(MCP_CONFIG_ABS)" \
+            -e "env_file=$(ENV_FILE_ABS)" \
+            -e "config_file=$(CONFIG_FILE_ABS)"; \
 	else \
 		if [ -z "$(USER)" ]; then \
 			echo "ERROR: USER parameter required for remote installation!"; \
@@ -118,18 +126,20 @@ install:
 			$(ANSIBLE_PLAYBOOK) ansible/install.yml \
 				-i "$(USER)@$(HOST)," \
 				-k -e "ansible_ssh_pass=$(PASS)" \
-				-e "target_path=$(TARGET_PATH)" \
-				-e "mcp_config_file=$(MCP_CONFIG_ABS)" \
-				-e "env_file=$(ENV_FILE_ABS)"; \
+                -e "target_path=$(TARGET_PATH)" \
+                -e "mcp_config_file=$(MCP_CONFIG_ABS)" \
+                -e "env_file=$(ENV_FILE_ABS)" \
+                -e "config_file=$(CONFIG_FILE_ABS)"; \
 		else \
 			echo "Using SSH key authentication..."; \
 			ANSIBLE_STDOUT_CALLBACK=actionable \
 			$(ANSIBLE_PLAYBOOK) ansible/install.yml \
 				-i "$(USER)@$(HOST)," \
 				-e "ansible_ssh_private_key_file=$(KEY)" \
-				-e "target_path=$(TARGET_PATH)" \
-				-e "mcp_config_file=$(MCP_CONFIG_ABS)" \
-				-e "env_file=$(ENV_FILE_ABS)"; \
+                -e "target_path=$(TARGET_PATH)" \
+                -e "mcp_config_file=$(MCP_CONFIG_ABS)" \
+                -e "env_file=$(ENV_FILE_ABS)" \
+                -e "config_file=$(CONFIG_FILE_ABS)"; \
 		fi \
 	fi
 
@@ -259,4 +269,4 @@ test-integration: ## Run integration tests only
 		echo "No integration tests found yet"; \
 	fi
 
-.PHONY: test-hooks test-unit test-integration
+.PHONY: test-hooks test-unit test-integration

README.md

@@ -1,79 +1,53 @@
 # Intelligent Claude Code
 
-Transform Claude Code into a 14+ agent virtual development team with autonomous AgentTask execution.
+Turn Claude Code into a multi-agent “virtual dev team” with AgentTasks, memory-first flows, and guardrails.
 
-## Quick Start
+## Quick start
 
 ```bash
-# Install
 git clone https://github.com/intelligentcode-ai/intelligent-claude-code.git
 cd intelligent-claude-code
-make install                   # Linux/macOS
-# or .\install.ps1 install    # Windows
-
-# Initialize
-/icc-init-system
-
-# Start working
-@PM Build a user authentication system
+make install              # or .\install.ps1 install on Windows
+/icc-init-system          # one-time init
 ```
 
-## What You Get
-
-- **14+ Specialist Agents**: @PM, @Developer, @AI-Engineer, @Database-Engineer, @Security-Engineer + unlimited dynamic specialists
-- **AgentTask Automation**: Work requests automatically become self-contained AgentTasks
-- **Memory-First Operations**: All agents check/store learnings automatically
-- **Autonomous Execution**: L1 (manual) → L2 (guided) → L3 (fully autonomous)
-
-## Primary Usage Pattern
+Then work conversationally:
 
 ```bash
-# Natural @Role communication - no complex commands needed
-@PM break down [story]         # Story → AgentTasks
-@Developer implement auth      # Auto-creates + executes AgentTask
-@AI-Engineer optimize system   # AI/behavioral improvements
-@DevOps-Engineer deploy prod   # Infrastructure operations
+@PM plan feature XYZ      # breaks into AgentTasks
+@Developer implement auth # executes via AgentTask
+/icc-search-memory auth   # reuse prior learnings
 ```
 
-## Essential Commands (Only 3)
-
-```bash
-/icc-init-system              # Initialize system
-/icc-get-setting [key]        # Get configuration
-/icc-search-memory [query]    # Search learnings
-```
+## What’s inside (at a glance)
+- Specialist roles (PM, Dev, DevOps, QA, Security, DB, AI, etc.) plus dynamic specialists
+- AgentTask automation with templates, memory injection, and constraints
+- Guardrails: main-scope enforcement, scope/summary/file checks, infra safety
+- MCP-ready: memory/docs/issue providers when enabled
 
-**Everything else is automatic** - AgentTask generation, memory storage, specialist creation.
+## Operate safely
+- Main scope: coordinate, delegate, read; agents do the heavy work (configurable)
+- Memory-first: `memory/` is searched/stored automatically
+- Infra protection: IAC-only posture by default; see `icc.config.json`
 
-## Configuration
+## Configure (minimal)
+- Primary knobs live in `icc.config.json` (or project `.icc/config.json`)
+- Quick presets available in `.icc/`:
+  - `config.relaxed.json` – legacy behavior with lighter guardrails
+  - `config.sub-agent.json` – agents do all writes/exec; main scope delegates only
+  - `config.main-scope.json` – coordination-only main scope (agents execute work)
+  - `config.strict-main-scope.json` – read-only/Task-only main scope (ultra-safe mode)
+  - `config.main-scope-dev.json` – Linux/macOS friendly preset where Main Scope may run curated `git`/`gh` commands locally while all guardrails (file naming, folders, git privacy, @codex review, best practices, memory output) remain enabled
+  - `config.workflow-reviewed.json` – Enables workflow enforcement (Task → Plan → Review → Execute → Review → Document) for Main Scope + agents
 
-Configure in `CLAUDE.md` where YOUR files are:
+  See `sample-configs/README.md` for usage instructions and run `make install CONFIG_FILE=sample-configs/<name>.json` to apply one system-wide.
 
-```yaml
-# System adapts to YOUR project structure
-agenttask_configuration:
-  best_practices_paths: ["docs/standards/"]
-
-memory_configuration:
-  external_path: "~/claude-memory"  # Optional external memory
-
-workflow_settings:
-  tiny:
-    version_bump: true
-    changelog_required: true
-    pr_required: false
-```
+- Toggle `enforcement.main_scope_has_agent_privileges: true` if you want the Main Scope treated exactly like an agent (strict main-scope enforcement, PM-only limits, doc routing, etc. all short-circuit). Default is `false`; `icc.config.main-scope-dev.json` turns it on for systems impacted by the V8 issue.
+- Enable `enforcement.workflow` to require the Task → Plan → Review → Execute → Review → Document sequence (see `icc.config.workflow-reviewed.json` for the default step mapping).
 
 ## Documentation
-
-**Start here**: [Documentation Index](docs/index.md)
-
-**Key Guides**:
-- [Installation Guide](docs/installation-guide.md)
-- [User Guide](docs/user-guide.md)
-- [AgentTask System Guide](docs/agenttask-system-guide.md)
-- [Virtual Team Guide](docs/virtual-team-guide.md)
+- Start: [docs/index.md](docs/index.md)
+- Essentials: [installation-guide](docs/installation-guide.md), [user-guide](docs/user-guide.md), [agenttask-system-guide](docs/agenttask-system-guide.md), [virtual-team-guide](docs/virtual-team-guide.md)
 
 ## License
-
-MIT - See LICENSE file
+MIT (see LICENSE)

VERSION

@@ -1 +1 @@
-8.20.86
+8.20.91