Add comprehensive strict mode reference documentation

[Copilot]

Strict mode enforcement was documented in the security guide but lacked detailed reference documentation explaining the CLI flag, frontmatter field relationship, and complete constraint list.

Changes

Reference Documentation (frontmatter.md)

• Expanded strict mode section with all 6 enforcement areas:
  1. Write permissions (requires safe-outputs)
  2. Network configuration (explicit required)
  3. Network wildcards (no * allowed)
  4. MCP network (containers need config)
  5. Action pinning (SHA required)
  6. Deprecated fields (refused)
• Clarified CLI flag vs frontmatter field: CLI takes precedence, frontmatter cannot disable when CLI flag set
• Added cross-references to CLI and security documentation

CLI Documentation (cli.md)

• Added dedicated --strict flag section under compile command
• Documented precedence: CLI flag applies to all workflows, cannot be overridden per-workflow
• Included usage examples:

  gh aw compile --strict
  gh aw compile --strict --zizmor
  gh aw compile --validate --strict

Security Guide (security.md)

• Updated enforcement areas list to match reference docs (added action pinning and deprecated fields)
• Added cross-reference to CLI documentation

All three files now consistently document the same 6 enforcement areas found in pkg/workflow/strict_mode_validation.go.

Addresses #4177

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Add strict-mode reference documentation in frontmatter.md</issue_title>
<issue_description>## Objective
Add comprehensive reference documentation for the strict-mode CLI feature in the frontmatter reference guide.

Context

The schema consistency audit (Discussion #4177) found that while strict-mode is mentioned in guides/security.md, it lacks detailed documentation in the reference documentation. Users need clear guidance on what strict mode does and how to use it.

Related to #4177

Current State

• Brief mention: docs/src/content/docs/guides/security.md:124-126
• Missing from: docs/src/content/docs/reference/frontmatter.md
• Missing from: docs/src/content/docs/setup/cli.md (CLI reference)

Proposed Approach

Add a dedicated section in the appropriate documentation file(s):

1. In frontmatter.md - Add note that this is CLI-only in the "Agentic Workflow Specific Fields" section
2. In cli.md - Document the --strict flag with full details

Suggested Content Structure

### Strict Mode (CLI-only)

Strict mode enforces enhanced security and validation rules during compilation. Enable via CLI flag:

\`\`\`bash
gh aw compile --strict
\`\`\`

**Enforcement Areas:**
- **Action Pinning**: Requires all GitHub Actions to be pinned to specific commit SHAs
- **Network Permissions**: Requires explicit network configuration (no implicit defaults)
- **Write Permissions**: Requires use of safe-outputs for GitHub API write operations
- **Bash Tool Restrictions**: Restricts wildcard usage in bash tool configurations

**Note**: Strict mode is a CLI-only feature and cannot be configured in workflow frontmatter.

Files to Modify

• docs/src/content/docs/reference/frontmatter.md - Add CLI-only features note
• docs/src/content/docs/setup/cli.md - Add --strict flag documentation
• Consider adding to docs/src/content/docs/guides/security.md - Expand existing mention

Acceptance Criteria

• Reference documentation includes strict-mode section
• Documentation clearly states it's CLI-only
• All four enforcement areas are documented
• Examples show CLI usage: gh aw compile --strict
• Cross-references to related security guide sections
• Follows Diátaxis framework (reference style)

Related Files

Implementation references:

• pkg/workflow/compiler.go:111 (SetStrictMode)
• pkg/workflow/compiler.go:684 (validateStrictMode)
• pkg/workflow/strict_mode.go (enforcement logic)
• pkg/workflow/action_pins.go:110,121 (action pinning enforcement)
  Related to [Schema Consistency] 🔍 Schema Consistency Check - 2025-11-17: 83% Consistency Rate (CLI-Only Feature Gap) #4177

AI generated by Plan Command for discussion #4177</issue_description>

Comments on the Issue (you are @copilot in this section)

@pelikhan @copilot the strict mode should be equivalent to the "strict" flag in the schema.

• Fixes [task] Add strict-mode reference documentation in frontmatter.md #4208

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull Request Overview

This PR adds comprehensive reference documentation for strict mode across three documentation files. The changes expand the brief mentions of strict mode into detailed sections that explain the CLI flag, frontmatter field relationship, and complete list of enforcement areas.

Key Changes:

• Expanded strict mode documentation with detailed enforcement areas (write permissions, network configuration, wildcards, MCP network, action pinning, deprecated fields)
• Clarified CLI flag vs frontmatter field precedence relationships
• Added cross-references between CLI, reference, and security documentation
• Provided usage examples for the --strict flag

Reviewed Changes

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

File	Description
docs/src/content/docs/setup/cli.md	Added dedicated --strict flag section with enforcement areas, precedence rules, examples, and cross-references
docs/src/content/docs/reference/frontmatter.md	Expanded strict mode field documentation with detailed enforcement areas, enabling methods, and precedence explanation
docs/src/content/docs/guides/security.md	Updated enforcement areas list to match reference docs and added CLI documentation cross-reference

---

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

[Copilot]

The documentation lists "Action Pinning" as enforcement area #5, but action pinning is not validated in the validateStrictMode() function in strict_mode_validation.go. Instead, strict mode affects action pinning behavior indirectly through GetActionPinWithData() in action_pins.go (lines 121-127), which returns an error when an action cannot be pinned.

This enforcement happens during the compilation/pinning process, not as part of the centralized strict mode validation checks. The documentation should clarify that action pinning enforcement occurs during compilation, not as a validation check, or consider removing it from the "Enforcement Areas" list to accurately reflect what validateStrictMode() actually validates.

Suggested change

	5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs instead of tags or branches.
	6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
	5. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
	> **Note:** Strict mode also enforces that all GitHub Actions must be pinned to specific commit SHAs (not tags or branches). This enforcement occurs during the compilation process, not as part of the strict mode validation checks.

[Copilot]

The documentation lists "Action Pinning" as enforcement area #5, but action pinning is not validated in the validateStrictMode() function in strict_mode_validation.go. Instead, strict mode affects action pinning behavior indirectly through GetActionPinWithData() in action_pins.go (lines 121-127), which returns an error when an action cannot be pinned.

This enforcement happens during the compilation/pinning process, not as part of the centralized strict mode validation checks. The documentation should clarify that action pinning enforcement occurs during compilation, not as a validation check, or consider removing it from the "Enforcement Areas" list to accurately reflect what validateStrictMode() actually validates.

Suggested change

	5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
	6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
	5. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
	> [!NOTE]
	> **Action Pinning:**
	> Action pinning (requiring GitHub Actions to be pinned to specific commit SHAs) is always enforced during the compilation process, not as part of strict mode validation. Strict mode may affect action pinning behavior, but the enforcement occurs during compilation, not as a strict mode validation check.

[Copilot]

The documentation lists "Action Pinning" as enforcement area #5, but action pinning is not validated in the validateStrictMode() function in strict_mode_validation.go. Instead, strict mode affects action pinning behavior indirectly through GetActionPinWithData() in action_pins.go (lines 121-127), which returns an error when an action cannot be pinned.

This enforcement happens during the compilation/pinning process, not as part of the centralized strict mode validation checks. The documentation should clarify that action pinning enforcement occurs during compilation, not as a validation check, or consider removing it from the "Enforcement Areas" list to accurately reflect what validateStrictMode() actually validates.

Suggested change

	5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
	6. **No Deprecated Fields**: Refuses deprecated frontmatter fields.
	5. **No Deprecated Fields**: Refuses deprecated frontmatter fields.
	**Note:** Action pinning (requiring all GitHub Actions to be pinned to specific commit SHAs) is always enforced during the compilation process. In strict mode, any unpinned actions will cause compilation to fail, but this is enforced during compilation/pinning, not as part of strict mode validation checks.