Release 8.20.96

[ksamaschke]

Merge dev into main.\n- Version 8.20.96 alignment (root and src)\n- PM docs blacklist bypass\n- Infra/docs fixes previously merged into dev\n\nTests: bash tests/run-tests.sh

[ksamaschke]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Align marker paths with ICC_TEST_MARKER_DIR

ICC_TEST_MARKER_DIR is now honoured by marker detection (lines 23‑27) and is exported by tests/run-tests.sh, but marker creation/cleanup still hardcode ~/.claude/tmp (agent-marker.js/stop.js). When the env var is set—e.g., running the test suite—agent markers are written to the real home directory while detection reads the temp directory, so agents will be misclassified as main scope and their markers won’t be cleaned up. Marker producers need to use the same configurable directory to keep agent detection reliable under the new test env override.

Useful? React with 👍 / 👎.

[Copilot]

Pull request overview

This PR merges development work for release 8.20.96, introducing workflow enforcement capabilities, PM documentation fast-path improvements, and various infrastructure/documentation fixes accumulated across multiple intermediate versions (8.20.91-8.20.95).

• Adds optional workflow enforcement hook that ensures tools execute in the configured sequence (Task → Plan → Review → Execute → Review → Document)
• Enhances PM constraints enforcement with a docs fast-path that bypasses tool blacklist for markdown files in allowlisted directories
• Improves infrastructure protection with better heredoc validation and unquoted keyword detection to prevent false positives

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/hooks/workflow-enforcement.js	New hook that enforces sequential workflow steps with session-based state tracking
src/hooks/pm-constraints-enforcement.js	Adds markdown fast-path logic to bypass blacklist for allowlisted directories; fixes quote escaping in error message
src/hooks/agent-infrastructure-protection.js	Enhances heredoc validation, adds markdown allowlist checks, and implements containsUnquoted for better keyword detection
src/hooks/stop.js	Removes non-standard hookSpecificOutput to fix schema validation errors
src/hooks/project-scope-enforcement.js	Adds main scope agent privileges configuration with environment variable override
src/hooks/summary-file-enforcement.js	Prevents false positives on ALL-CAPS checks when shell variables are present in file paths
src/hooks/lib/marker-detection.js	Refactors to accept hookInput or path strings; adds test directory override support
src/hooks/lib/directory-enforcement.js	Relaxes docs directory enforcement to allow any path containing 'docs' segment
tests/run-tests.sh	Sets deterministic test environment variables to ensure consistent test behavior
tests/hooks/unit/test-marker-detection.js	Updates test to use ICC_TEST_MARKER_DIR environment variable
tests/hooks/unit/test-agent-infra-doc-fastpath.js	Adds tests for heredoc validation with and without quoting
tests/hooks/integration/test-workflow-enforcement.js	New integration test suite for workflow state machine
tests/hooks/integration/test-agent-marker-workflow.js	Updates import path to use relative source path instead of installed location
tests/hooks/regression/test-hash-consistency.js	Adds workflow-enforcement.js to list of hooks requiring consistent project hashing
icc.config.default.json	Adds workflow enforcement configuration block (disabled by default)
sample-configs/icc.config.workflow-reviewed.json	New preset enabling workflow enforcement with default step sequence
sample-configs/icc.config.main-scope-dev.json	Enables parent allowlist paths and adds auto_commit_review configuration
sample-configs/README.md	Documents new workflow-reviewed config and clarifies main scope agent privileges
install.ps1	Updates hook count from 15 to 16 throughout, registers workflow-enforcement.js
ansible/roles/intelligent-claude-code/templates/settings.json.j2	Adds workflow-enforcement.js to PreToolUse hooks
ansible/roles/intelligent-claude-code/tasks/main.yml	Updates documentation messages to reflect 16 hooks
VERSION	Bumps version to 8.20.96
src/VERSION	Bumps version to 8.20.96 (aligned with root)
README.md	Documents workflow enforcement feature and config option
CHANGELOG.md	Comprehensive release notes for versions 8.20.91 through 8.20.96

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Missing return statements before allowOperation calls. While allowOperation does call process.exit(), the missing return makes the control flow unclear and violates best practices. Add return before these calls for clarity:

if (!settings.enabled || settings.steps.length === 0) {
  return allowOperation(log, true);
}

[Copilot]

Inconsistent indentation: the function main() declaration and the initializeHook call have mismatched indentation. The function declaration should align with the rest of the file's top-level code.

Suggested change

	function main() {
	// Initialize hook with shared library function
	const { log, hookInput } = initializeHook('agent-infrastructure-protection');
	function main() {
	// Initialize hook with shared library function
	const { log, hookInput } = initializeHook('agent-infrastructure-protection');

[Copilot]

Unnecessary escape sequences in template literal. In JavaScript template literals (backtick strings), quotes don't need to be escaped. Change \"${tool}\" to "${tool}":

Tool "${tool}" is blocked by the ${blacklistResult.reason}.

Suggested change

	Tool \"${tool}\" is blocked by the ${blacklistResult.reason}.
	Tool "${tool}" is blocked by the ${blacklistResult.reason}.

[Copilot]

Test does not clean up temporary directory. The createTestProject() function creates a temp directory but it's never removed. Consider adding cleanup:

(function runTests() {
  const projectDir = createTestProject();
  try {
    // ... tests ...
  } finally {
    fs.rmSync(projectDir, { recursive: true, force: true });
  }
})();

Suggested change

	const sessionId = 'test-session-1';
	const planFirst = runHook(projectDir, 'Plan', sessionId);
	assert.strictEqual(planFirst.code, 2, 'Plan before Task should be blocked');
	const allowedSequence = ['Task', 'Plan', 'Review', 'Execute', 'Document'];
	allowedSequence.forEach((tool, index) => {
	const result = runHook(projectDir, tool, sessionId);
	assert.strictEqual(result.code, 0, `Step ${index + 1} (${tool}) should be allowed`);
	});
	const restart = runHook(projectDir, 'Task', sessionId);
	assert.strictEqual(restart.code, 0, 'Workflow should reset after Document');
	const outOfOrder = runHook(projectDir, 'Execute', sessionId);
	assert.strictEqual(outOfOrder.code, 2, 'Execute before Plan should be blocked in new cycle');
	console.log('✅ Workflow enforcement integration tests passed');
	try {
	const sessionId = 'test-session-1';
	const planFirst = runHook(projectDir, 'Plan', sessionId);
	assert.strictEqual(planFirst.code, 2, 'Plan before Task should be blocked');
	const allowedSequence = ['Task', 'Plan', 'Review', 'Execute', 'Document'];
	allowedSequence.forEach((tool, index) => {
	const result = runHook(projectDir, tool, sessionId);
	assert.strictEqual(result.code, 0, `Step ${index + 1} (${tool}) should be allowed`);
	});
	const restart = runHook(projectDir, 'Task', sessionId);
	assert.strictEqual(restart.code, 0, 'Workflow should reset after Document');
	const outOfOrder = runHook(projectDir, 'Execute', sessionId);
	assert.strictEqual(outOfOrder.code, 2, 'Execute before Plan should be blocked in new cycle');
	console.log('✅ Workflow enforcement integration tests passed');
	} finally {
	fs.rmSync(projectDir, { recursive: true, force: true });
	}